👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

RedHat 9 (Linux i386) - man page for dhcpctl (redhat section 3)

DHCPCTL(3)			   BSD Library Functions Manual 		       DHCPCTL(3)

NAME
     dhcpctl_initialize -- dhcpctl library initialization.

SYNOPSIS
     #include <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_wait_for_completion(dhcpctl_handle object, dhcpctl_status *status);

     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 manipu-
     late 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 parame-
     ter 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_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_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 be sent to the remote for processing. The changes made to the atributes 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 refer-
     enced 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().

     dhcpctl_new_object() creates a local handle for an object on the 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 han-
	       dle.

	   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 ommitted for brevity.

	   #include <stdarg.h>
	   #include <sys/time.h>
	   #include <sys/socket.h>
	   #include <stdio.h>
	   #include <netinet/in.h>

	   #include <isc/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), omshell(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).  dhcpctl was
     written by Ted Lemon of Nominum, Inc.  Information about Nominum and support contracts for
     DHCP and BIND can be found at http://www.nominum.com. This preliminary documentation was
     written by James Brister of Nominum, Inc.

DHCP 3					   Nov 15, 2000 				   DHCP 3


All times are GMT -4. The time now is 07:20 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password