---
name: "dhcpctl"
section: "3"
platform: "linux"
package: "dhcp"
version: "4.4.3.P1-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/dhcpctl"
---

# dhcpctl(3)

dhcpctl library initialization.

## NAME

**dhcpctl\_initialize** – dhcpctl library initialization.

## SYNOPSIS

**#include \<dhcpctl/dhcpctl.h\>**

*dhcpctl\_status*\

**dhcpctl\_initialize**(*void*);

*dhcpctl\_status*\

**dhcpctl\_connect**(*dhcpctl\_handle \*cxn*, *const char \*host*, *int port*, *dhcpctl\_handle auth*);

*dhcpctl\_status*\

**dhcpctl\_timed\_connect**(*dhcpctl\_handle \*cxn*, *const char \*host*, *int port*, *dhcpctl\_handle auth*, *dhcpctl\_status \*status*);

*dhcpctl\_status*\

**dhcpctl\_disconnect**(*dhcpctl\_handle \*cxn*, *int force*);

*dhcpctl\_status*\

**dhcpctl\_wait\_for\_completion**(*dhcpctl\_handle object*, *dhcpctl\_status \*status*);

*dhcpctl\_status*\

**dhcpctl\_timed\_wait\_for\_completion**(*dhcpctl\_handle object*, *dhcpctl\_status \*status*, *struct timeval \*timeout*);

*dhcpctl\_status*\

**dhcpctl\_get\_value**(*dhcpctl\_data\_string \*value*, *dhcpctl\_handle object*, *const char \*name*);

*dhcpctl\_status*\

**dhcpctl\_get\_boolean**(*int \*value*, *dhcpctl\_handle object*, *const char \*name*);

*dhcpctl\_status*\

**dhcpctl\_set\_value**(*dhcpctl\_handle object*, *dhcpctl\_data\_string value*, *const char \*name*);

*dhcpctl\_status*\

**dhcpctl\_set\_string\_value**(*dhcpctl\_handle object*, *const char \*value*, *const char \*name*);

*dhcpctl\_status*\

**dhcpctl\_set\_boolean\_value**(*dhcpctl\_handle object*, *int value*, *const char \*name*);

*dhcpctl\_status*\

**dhcpctl\_set\_int\_value**(*dhcpctl\_handle object*, *int value*, *const char \*name*);

*dhcpctl\_status*\

**dhcpctl\_object\_update**(*dhcpctl\_handle connection*, *dhcpctl\_handle object*);

*dhcpctl\_status*\

**dhcpctl\_object\_refresh**(*dhcpctl\_handle connection*, *dhcpctl\_handle object*);

*dhcpctl\_status*\

**dhcpctl\_object\_remove**(*dhcpctl\_handle connection*, *dhcpctl\_handle object*);

*dhcpctl\_status*\

**dhcpctl\_set\_callback**(*dhcpctl\_handle object*, *void \*data*, *void (\*function) (dhcpctl\_handle, dhcpctl\_status, void \*)*);

*dhcpctl\_status*\

**dhcpctl\_new\_authenticator**(*dhcpctl\_handle \*object*, *const char \*name*, *const char \*algorithm*, *const char \*secret*, *unsigned secret\_len*);

*dhcpctl\_status*\

**dhcpctl\_new\_object**(*dhcpctl\_handle \*object*, *dhcpctl\_handle connection*, *const char \*object\_type*);

*dhcpctl\_status*\

**dhcpctl\_open\_object**(*dhcpctl\_handle object*, *dhcpctl\_handle connection*, *int flags*);

*isc\_result\_t*\

**omapi\_data\_string\_new**(*dhcpctl\_data\_string*, *\*data*, *unsigned*, *int*, *length*, *const*, *char*, *\*filename,*, *int*, *lineno*);

*isc\_result\_t*\

**dhcpctl\_data\_string\_dereference**(*dhcpctl\_data\_string \**, *const char \**, *int*);

## DESCRIPTION

The dhcpctl set of functions provide an API that can be used to communicate with and manipulate a running ISC DHCP server. All functions return a value of isc\_result\_t. The return values reflects the result of operations to local data structures. If an operation fails on the server for any reason, then the error result will be returned through the second parameter of the **dhcpctl\_wait\_for\_completion**() call.

**dhcpctl\_initialize**() sets up the data structures the library needs to do its work. This function must be called once before any other.

**dhcpctl\_connect**() opens a connection to the DHCP server at the given host and port. If an authenticator has been created for the connection, then it is given as the 4th argument. On a successful return the address pointed at by the first argument will have a new connection object assigned to it.

For example:

```
s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
```

connects to the DHCP server on the localhost via port 7911 (the standard OMAPI port). No authentication is used for the connection.

**dhcpctl\_timed\_connect**() opens a connection to the DHCP server at the given host and port. If an authenticator has been created for the connection, then it is given as the 4th argument. On a successful return the address pointed at by the first argument will have a new connection object assigned to it. How long the function waits for complete the connection is dictated by the value of the parameter, **timeout**. If the value is null, it will wait indefinitely Otherwise it will wait for the amount of time specified by **timeout** (tv\_sec:tv\_usec). Values of zero for both fields are valid but not recommended. An example is shown below:

For example:

```
struct timeval timeout;
timeout.tv_sec = 5;   /* wait for 5 seconds */
timeout.tv_usec = 0;
s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL, &timeout);
```

connects to the DHCP server on the localhost via port 7911 (the standard OMAPI port). No authentication is used for the connection.  It allows 5 seconds for the connect to complete.

**dhcpctl\_disconnect**() closes the open connection specified by the first parameter, **cxn**.  Note that this call will free the connection object and **cxn** will be set to\
  nul.  If the second parameter,**force**, is nonzero, the connection will be closed immediately. Otherwise the receiving end will be shut down but any unsent data will be sent before actually closing the socket.  Note that disconnecting only destroys the connection object, any other objects previously created will still exist.

For example:

```
s = dhcpctl_disconnect(&cxn, 1);
```

will close the connection immediately.  This funcion should be considered **EXPERIMENTAL**.

**dhcpctl\_wait\_for\_completion**() flushes a pending message to the server and waits for the response. The result of the request as processed on the server is returned via the second parameter.

```
s = dhcpctl_wait_for_completion(cxn, &wv);
if (s != ISC_R_SUCCESS)
	local_failure(s);
else if (wv != ISC_R_SUCCESS)
	server_failure(wc);
```

The call to **dhcpctl\_wait\_for\_completion**() won't return until the remote message processing completes or the connection to the server is lost.

**dhcpctl\_timed\_wait\_for\_completion**() flushes a pending message to the server and waits for the response.  How long the function waits for a response is dictated by the value of the third parameter, **timeout**. If the value is null, it will wait indefinitely or until the connection is lost. Otherwise it will wait for the amount of time specified by **timeout** (tv\_sec:tv\_usec). Values of zero for both fields are valid but not recommended.  The result of the request as processed on the server is returned via the second parameter.  An example is shown below:

```
struct timeval timeout;
timeout.tv_sec = 5;   /* wait for 5 seconds */
timeout.tv_usec = 0;
s = dhcpctl_wait_for_completion(cxn, &wv, &timeout);
if (s != ISC_R_SUCCESS) {
	local_failure(s);
} else if (wv != ISC_R_SUCCESS) {
	server_failure(wc);
}
```

If the function times out, the status returned will be ISC\_R\_TIMEDOUT. Please note that even though the function is no longer waiting for a response, the server does not abandon the request and may still respond by writing the response to the socket. A subsequent call to either this function or **dhcpctl\_wait\_for\_completion()** will see that data and read it. Depending on the application logic flow this may or may not be desired.  Currently though only mechanism for "flushing" this data is to close the connection by calling **disconnet()**, and then reconnecting via **connect()**.  Please note this function should be considered **EXPERIMENTAL**.

**dhcpctl\_get\_value**() extracts a value of an attribute from the handle. The value can be of any length and is treated as a sequence of bytes.  The handle must have been created first with **dhcpctl\_new\_object**() and opened with **dhcpctl\_open\_object**(). The value is returned via the parameter named “value”. The last parameter is the name of attribute to retrieve.

```
dhcpctl_data_string value = NULL;
dhcpctl_handle lease;
time_t thetime;
s = dhcpctl_get_value (&value, lease, "ends");
assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
memcpy(&thetime, value->value, value->len);
```

**dhcpctl\_get\_boolean**() extracts a boolean valued attribute from the object handle.

The **dhcpctl\_set\_value**(), **dhcpctl\_set\_string\_value**(), **dhcpctl\_set\_boolean\_value**(), and **dhcpctl\_set\_int\_value**() functions all set a value on the object handle.

**dhcpctl\_object\_update**() function queues a request for all the changes made to the object handle be sent to the remote for processing. The changes made to the attributes on the handle will be applied to remote object if permitted.

**dhcpctl\_object\_refresh**() queues up a request for a fresh copy of all the attribute values to be sent from the remote to refresh the values in the local object handle.

**dhcpctl\_object\_remove**() queues a request for the removal on the server of the object referenced by the handle.

The **dhcpctl\_set\_callback**() function sets up a user-defined function to be called when an event completes on the given object handle. This is needed for asynchronous handling of events, versus the synchronous handling given by **dhcpctl\_wait\_for\_completion**(). When the function is called the first parameter is the object the event arrived for, the second is the status of the message that was processed, the third is the same value as the second parameter given to **dhcpctl\_set\_callback**().

The **dhcpctl\_new\_authenticator**() creates a new authenticator object to be used for signing the messages that cross over the network. The “name”, “algorithm”, and “secret” values must all match what the server uses and are defined in its configuration file. The created object is returned through the first parameter and must be used as the 4th parameter to **dhcpctl\_connect**(). Note that the 'secret' value must not be base64 encoded, which is different from how the value appears in the dhcpd.conf file.

**dhcpctl\_new\_object**() creates a local handle for an object on the server. The “object\_type” parameter is the ascii name of the type of object being accessed. e.g. "lease". This function only sets up local data structures, it does not queue any messages to be sent to the remote side, **dhcpctl\_open\_object**() does that.

**dhcpctl\_open\_object**() builds and queues the request to the remote side. This function is used with handle created via **dhcpctl\_new\_object**(). The flags argument is a bit mask with the following values available for setting:

- DHCPCTL\_CREATE

  if the object does not exist then the remote will create it

- DHCPCTL\_UPDATE

  update the object on the remote side using the attributes already set in the handle.

- DHCPCTL\_EXCL

  return and error if the object exists and DHCPCTL\_CREATE was also specified

The **omapi\_data\_string\_new**() function allocates a new *dhcpctl\_data\_string* object. The data string will be large enough to hold “length” bytes of data. The “file” and “lineno” arguments are the source file location the call is made from, typically by using the \_\_FILE\_\_ and \_\_LINE\_\_ macros or the MDL macro defined in

**dhcpctl\_data\_string\_dereference**() deallocates a data string created by **omapi\_data\_string\_new**(). The memory for the object won't be freed until the last reference is released.

## EXAMPLES

The following program will connect to the DHCP server running on the local host and will get the details of the existing lease for IP address 10.0.0.101. It will then print out the time the lease is due to expire. Note that most error checking has been omitted for brevity.

```
#include <sys/time.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdarg.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include "omapip/result.h"
#include "dhcpctl.h"
int main (int argc, char **argv) {
	dhcpctl_data_string ipaddrstring = NULL;
	dhcpctl_data_string value = NULL;
	dhcpctl_handle connection = NULL;
	dhcpctl_handle lease = NULL;
	isc_result_t waitstatus;
	struct in_addr convaddr;
	time_t thetime;
        dhcpctl_initialize ();
        dhcpctl_connect (&connection, "127.0.0.1",
			 7911, 0);
        dhcpctl_new_object (&lease, connection,
			    "lease");
        memset (&ipaddrstring, 0, sizeof
		ipaddrstring);
        inet_pton(AF_INET, "10.0.0.101",
		  &convaddr);
	omapi_data_string_new (&ipaddrstring,
			       4, MDL);
	memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
	dhcpctl_set_value (lease, ipaddrstring,
			   "ip-address");
	dhcpctl_open_object (lease, connection, 0);
	dhcpctl_wait_for_completion (lease,
				     &waitstatus);
        if (waitstatus != ISC_R_SUCCESS) {
		/* server not authoritative */
		exit (0);
        }
	dhcpctl_data_string_dereference(&ipaddrstring,
					MDL);
        dhcpctl_get_value (&value, lease, "ends");
	memcpy(&thetime, value->value, value->len);
	dhcpctl_data_string_dereference(&value, MDL);
	fprintf (stdout, "ending time is %s",
		 ctime(&thetime));
}
```

## SEE ALSO

[omapi(3)](/omapi/3.md), [omshell(1)](/omshell/1.md), [dhcpd(8)](/dhcpd/8.md), [dhclient(8)](/dhclient/8.md), [dhcpd.conf(5)](/dhcpd.conf/5.md), [dhclient.conf(5)](/dhclient.conf/5.md).

## AUTHOR

*dhcpctl* is maintained by ISC.  To learn more about Internet Systems Consortium, see