troff source from james replaces plain text.

1 files changed, 463 insertions, 268 deletions

diff --git a/dhcpctl/dhcpctl.3 b/dhcpctl/dhcpctl.3
index 5597c58d..3c752812 100644
--- a/dhcpctl/dhcpctl.3
+++ b/dhcpctl/dhcpctl.3
@@ -1,268 +1,463 @@
-DHCPCTL(3)                 DHCP Programmer's Manual                 DHCPCTL(3)
-
-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_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 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 =3D 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 =3D dhcpctl_wait_for_completion(cxn, &wv);
-           if (s !=3D ISC_R_SUCCESS)
-                   local_failure(s);
-           else if (wv !=3D 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 =3D NULL;
-           dhcpctl_handle lease;
-           time_t thetime;
-
-           s =3D dhcpctl_get_value (&value, lease, "ends");
-           assert(s =3D=3D ISC_R_SUCCESS && value->len =3D=3D 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 ob
-     ject 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 giv
-     en 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 set
-     ting:
-
-           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 al
-              ready set in the handle.
-
-           DHCPCTL_EXCL
-              return and error if the object exists and DHCPCTL_CREATE was al
-              so 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 compelely
-     deallocated until the last reference is released.
-
-EXAMPLES
-
-     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
-     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/dhcpctl.h>
-
-           int main (int argc, char **argv) {
-                   dhcpctl_data_string ipaddrstring =3D NULL;
-                   dhcpctl_data_string value =3D NULL;
-                   dhcpctl_handle connection =3D NULL;
-                   dhcpctl_handle lease =3D 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 !=3D 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-intro(1)
-
- DHCP                            Nov 15, 2000                          5
-
+.\" -*- nroff -*-
+.\"
+.\" Project:      DHCP
+.\" File:         dhcpctl.3
+.\" RCSId:        $Id: dhcpctl.3,v 1.3 2001/04/16 17:44:11 tamino Exp $
+.\" 
+.\"     Copyright (C) 2000  Nominum, Inc.
+.\"     
+.\" Description:	dhcpctl man page.
+.\" 
+.\"
+.Dd Nov 15, 2000
+.Dt DHCPCTL 3
+.Os DHCP 3
+.ds vT DHCP Programmer's Manual
+.\"
+.\"
+.\"
+.Sh NAME
+.Nm dhcpctl_initialize
+.Nd dhcpctl library initialization.
+.\"
+.\"
+.\"
+.Sh SYNOPSIS
+.Fd #include <dhcpctl/dhcpctl.h>
+.Fd
+.Ft dhcpctl_status
+.Fo dhcpctl_initialize
+.Fa void
+.Fc
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_connect
+.Fa "dhcpctl_handle *cxn"
+.Fa "const char *host"
+.Fa "int port"
+.Fa "dhcpctl_handle auth"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_wait_for_completion
+.Fa "dhcpctl_handle object"
+.Fa "dhcpctl_status *status"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_get_value
+.Fa "dhcpctl_data_string *value"
+.Fa "dhcpctl_handle object"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_get_boolean
+.Fa "int *value"
+.Fa "dhcpctl_handle object"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_value
+.Fa "dhcpctl_handle object"
+.Fa "dhcpctl_data_string value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_string_value
+.Fa "dhcpctl_handle object"
+.Fa "const char *value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_boolean_value
+.Fa "dhcpctl_handle object"
+.Fa "int value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_int_value
+.Fa "dhcpctl_handle object"
+.Fa "int value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_object_update
+.Fa "dhcpctl_handle connection"
+.Fa "dhcpctl_handle object"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_object_refresh
+.Fa "dhcpctl_handle connection"
+.Fa "dhcpctl_handle object"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_object_remove
+.Fa "dhcpctl_handle connection"
+.Fa "dhcpctl_handle object"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_callback
+.Fa "dhcpctl_handle object"
+.Fa "void *data"
+.Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_new_authenticator
+.Fa "dhcpctl_handle *object"
+.Fa "const char *name"
+.Fa "const char *algorithm"
+.Fa "const char *secret"
+.Fa "unsigned secret_len"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_new_object
+.Fa "dhcpctl_handle *object"
+.Fa "dhcpctl_handle connection"
+.Fa "const char *object_type"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_open_object
+.Fa "dhcpctl_handle object"
+.Fa "dhcpctl_handle connection"
+.Fa "int flags"
+.Fc
+.\"
+.\"
+.\"
+.Ft isc_result_t
+.Fo omapi_data_string_new
+.Fa dhcpctl_data_string *data
+.Fa unsigned int length
+.Fa const char *filename,
+.Fa int lineno
+.Fc
+.\"
+.\"
+.\"
+.Ft isc_result_t
+.Fo dhcpctl_data_string_dereference
+.Fa "dhcpctl_data_string *"
+.Fa "const char *"
+.Fa "int"
+.Fc
+.Sh 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
+.Dv 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 
+.Fn dhcpctl_wait_for_completion 
+call.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_initialize
+sets up the data structures the library needs to do its work. This function
+must be called once before any other.
+.Pp
+.Fn 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.
+.Pp
+For example:
+.Bd -literal -offset indent
+s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
+.Ed
+.Pp
+connects to the DHCP server on the localhost via port 7911 (the standard
+OMAPI port). No authentication is used for the connection.
+.\"
+.\"
+.\"
+.Pp
+.Fn 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.
+.Bd -literal -offset indent
+s = dhcpctl_wait_for_completion(cxn, &wv);
+if (s != ISC_R_SUCCESS) 
+	local_failure(s);
+else if (wv != ISC_R_SUCCESS)
+	server_failure(wc);
+.Ed
+.Pp
+The call to 
+.Fn dhcpctl_wait_for_completion
+won't return until the remote message processing completes or the connection
+to the server is lost.
+.\"
+.\"
+.\"
+.Pp
+.Fn 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
+.Fn dhcpctl_new_object
+and opened with
+.Fn dhcpctl_open_object .
+The value is returned via the parameter named
+.Dq value .
+The last parameter is the name of attribute to retrieve.
+.Bd -literal -offset indent
+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);
+.Ed
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_get_boolean
+extracts a boolean valued attribute from the object handle.
+.\"
+.\"
+.\"
+.Pp
+The
+.Fn dhcpctl_set_value ,
+.Fn dhcpctl_set_string_value ,
+.Fn dhcpctl_set_boolean_value ,
+and
+.Fn dhcpctl_set_int_value
+functions all set a value on the object handle. 
+.\"
+.\"
+.\"
+.Pp
+.Fn 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.
+.\"
+.\"
+.\"
+.Pp
+.Fn 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.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_object_remove
+queues a request for the removal on the server of the object referenced by the
+handle.
+.\"
+.\"
+.\"
+.Pp
+The 
+.Fn 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
+.Fn 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 
+.Fn dhcpctl_set_callback .
+.\"
+.\"
+.\"
+.Pp
+The 
+.Fn dhcpctl_new_authenticator
+creates a new authenticator object to be used for signing the messages
+that cross over the network. The 
+.Dq name ,
+.Dq algorithm ,
+and 
+.Dq 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 
+.Fn dhcpctl_connect .
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_new_object
+creates a local handle for an object on the the server. The 
+.Dq object_type
+parameter is the ascii name of the type of object being accessed. e.g. 
+.Qq lease .
+This function only sets up local data structures, it does not queue any 
+messages
+to be sent to the remote side,
+.Fn dhcpctl_open_object
+does that.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_open_object
+builds and queues the request to the remote side. This function is used with
+handle created via
+.Fn dhcpctl_new_object .
+The flags argument is a bit mask with the following values available for
+setting:
+.Bl -tag -offset indent -width 20
+.It DHCPCTL_CREATE
+if the object does not exist then the remote will create it
+.It DHCPCTL_UPDATE
+update the object on the remote side using the
+attributes already set in the handle.
+.It DHCPCTL_EXCL
+return and error if the object exists and DHCPCTL_CREATE
+was also specified
+.El
+.\"
+.\"
+.\"
+.Pp
+The 
+.Fn omapi_data_string_new
+function allocates a new
+.Ft dhcpctl_data_string
+object. The data string will be large enough to hold 
+.Dq length
+bytes of data. The
+.Dq file 
+and
+.Dq lineno
+arguments are the source file location the call is made from, typically by
+using the 
+.Dv __FILE__
+and
+.Dv __LINE__
+macros or the 
+.Dv MDL
+macro defined in
+.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_data_string_dereference
+deallocates a data string created by
+.Fn omapi_data_string_new .
+The memory for the object won't be compelely deallocated until the last
+reference is released.
+.Sh EXAMPLES
+.Pp 
+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.
+.Bd -literal -offset indent
+#include <stdarg.h>
+#include <sys/time.h>
+#include <sys/socket.h>
+#include <stdio.h>
+#include <netinet/in.h>
+
+#include <isc/result.h>
+#include <dhcpctl/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));
+}
+.Ed
+.Sh SEE ALSO
+omapi-intro(1)