aboutsummaryrefslogtreecommitdiff
path: root/contrib/isc-dhcp/dhcpctl/dhcpctl.3
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/isc-dhcp/dhcpctl/dhcpctl.3')
-rw-r--r--contrib/isc-dhcp/dhcpctl/dhcpctl.3470
1 files changed, 470 insertions, 0 deletions
diff --git a/contrib/isc-dhcp/dhcpctl/dhcpctl.3 b/contrib/isc-dhcp/dhcpctl/dhcpctl.3
new file mode 100644
index 000000000000..8ab7918f8c34
--- /dev/null
+++ b/contrib/isc-dhcp/dhcpctl/dhcpctl.3
@@ -0,0 +1,470 @@
+.\" -*- nroff -*-
+.\"
+.\" Project: DHCP
+.\" File: dhcpctl.3
+.\" RCSId: $Id: dhcpctl.3,v 1.3.2.1 2001/06/26 18:35:35 mellon 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 freed 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
+.SH SEE ALSO
+omapi(3), omshell(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
+.SH AUTHOR
+.B dhcpctl
+was written by Ted Lemon of Nominum, Inc. Information about Nominum
+and support contracts for DHCP and BIND can be found at
+.B http://www.nominum.com. This preliminary documentation was
+written by James Brister of Nominum, Inc.
generated by cgit v1.2.3 (git 2.25.1) at 2023-03-29 23:50:40 +0000