Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DHCPCTL(3)		 BSD Library Functions Manual		    DHCPCTL(3)

     dhcpctl_initialize	-- dhcpctl library initialization.

     #include <dhcpctl/dhcpctl.h>


     dhcpctl_connect(dhcpctl_handle *cxn, const	char *host, int	port,
	 dhcpctl_handle	auth);

     dhcpctl_wait_for_completion(dhcpctl_handle	object,
	 dhcpctl_status	*status);

     dhcpctl_get_value(dhcpctl_data_string *value, dhcpctl_handle object,
	 const char *name);

     dhcpctl_get_boolean(int *value, dhcpctl_handle object, const char *name);

     dhcpctl_set_value(dhcpctl_handle object, dhcpctl_data_string value,
	 const char *name);

     dhcpctl_set_string_value(dhcpctl_handle object, const char	*value,
	 const char *name);

     dhcpctl_set_boolean_value(dhcpctl_handle object, int value,
	 const char *name);

     dhcpctl_set_int_value(dhcpctl_handle object, int value,
	 const char *name);

     dhcpctl_object_update(dhcpctl_handle connection, dhcpctl_handle object);

     dhcpctl_object_refresh(dhcpctl_handle connection, dhcpctl_handle object);

     dhcpctl_object_remove(dhcpctl_handle connection, dhcpctl_handle object);

     dhcpctl_set_callback(dhcpctl_handle object, void *data,
	 void (*function) (dhcpctl_handle, dhcpctl_status, void	*));

     dhcpctl_new_authenticator(dhcpctl_handle *object, const char *name,
	 const char *algorithm,	const char *secret, unsigned secret_len);

     dhcpctl_new_object(dhcpctl_handle *object,	dhcpctl_handle connection,
	 const char *object_type);

     dhcpctl_open_object(dhcpctl_handle	object,	dhcpctl_handle connection,
	 int flags);

     omapi_data_string_new(dhcpctl_data_string,	*data, unsigned, int, length,
	 const,	char, *filename,, int, lineno);

     dhcpctl_data_string_dereference(dhcpctl_data_string *, const char *,

     The dhcpctl set of	functions provide an API that can be used to communi-
     cate with and manipulate a	running	ISC DHCP server. All functions return
     a value of	isc_result_t.  The return values reflects the result of	opera-
     tions to local data structures. If	an operation fails on the server for
     any reason, then the error	result will be returned	through	the second pa-
     rameter 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	as-
     signed to it.

     For example:

	   s = dhcpctl_connect(&cxn, "", 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_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)
	   else	if (wv != ISC_R_SUCCESS)

     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_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

     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 en-
     coded, which is different from how	the value appears in the dhcpd.conf

     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 struc-
     tures, 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 set-

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

	       update the object on the	remote side using the attributes al-
	       ready set in the	handle.

	       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.

     The following program will	connect	to the DHCP server running on the lo-
     cal host and will get the details of the existing lease for IP address 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, "",
				    7911, 0);

		   dhcpctl_new_object (&lease, connection,

		   memset (&ipaddrstring, 0, sizeof

		   inet_pton(AF_INET, "",

		   omapi_data_string_new (&ipaddrstring,
					  4, MDL);
		   memcpy(ipaddrstring->value, &convaddr.s_addr, 4);

		   dhcpctl_set_value (lease, ipaddrstring,

		   dhcpctl_open_object (lease, connection, 0);

		   dhcpctl_wait_for_completion (lease,
		   if (waitstatus != ISC_R_SUCCESS) {
			   /* server not authoritative */
			   exit	(0);


		   dhcpctl_get_value (&value, lease, "ends");

		   memcpy(&thetime, value->value, value->len);

		   dhcpctl_data_string_dereference(&value, MDL);

		   fprintf (stdout, "ending time is %s",

     omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5),

     dhcpctl is	maintained by ISC.  To learn more about	Internet Systems Con-
     sortium, see

DHCP 3				 Nov 15, 2000				DHCP 3


Want to link to this manual page? Use this URL:

home | help