diff options
Diffstat (limited to 'dhcpctl/dhcpctl.3')
| -rw-r--r-- | dhcpctl/dhcpctl.3 | 170 |
1 files changed, 140 insertions, 30 deletions
diff --git a/dhcpctl/dhcpctl.3 b/dhcpctl/dhcpctl.3 index ee2e583a..48fd728c 100644 --- a/dhcpctl/dhcpctl.3 +++ b/dhcpctl/dhcpctl.3 @@ -3,9 +3,8 @@ .\" Project: DHCP .\" File: dhcpctl.3 .\" RCSId: $Id: dhcpctl.3,v 1.9 2011/04/25 23:43:16 sar Exp $ -.\" -.\" Copyright (c) 2011,2014 by Internet Systems Consortium, Inc. ("ISC") -.\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Copyright (c) 2004-2022 by Internet Systems Consortium, Inc. ("ISC") .\" Copyright (c) 2000-2003 by Internet Software Consortium .\" Copyright (c) 2000 Nominum, Inc. .\" @@ -22,13 +21,13 @@ .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" Internet Systems Consortium, Inc. -.\" 950 Charter Street -.\" Redwood City, CA 94063 +.\" PO Box 360 +.\" Newmarket, NH 03857 USA .\" <info@isc.org> .\" https://www.isc.org/ -.\" +.\" .\" Description: dhcpctl man page. -.\" +.\" .\" .Dd Nov 15, 2000 .Dt DHCPCTL 3 @@ -61,6 +60,25 @@ .\" .\" .Ft dhcpctl_status +.Fo dhcpctl_timed_connect +.Fa "dhcpctl_handle *cxn" +.Fa "const char *host" +.Fa "int port" +.Fa "dhcpctl_handle auth" +.Fa "dhcpctl_status *status" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_disconnect +.Fa "dhcpctl_handle *cxn" +.Fa "int force" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status .Fo dhcpctl_wait_for_completion .Fa "dhcpctl_handle object" .Fa "dhcpctl_status *status" @@ -69,6 +87,15 @@ .\" .\" .Ft dhcpctl_status +.Fo dhcpctl_timed_wait_for_completion +.Fa "dhcpctl_handle object" +.Fa "dhcpctl_status *status" +.Fa "struct timeval *timeout" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status .Fo dhcpctl_get_value .Fa "dhcpctl_data_string *value" .Fa "dhcpctl_handle object" @@ -207,8 +234,8 @@ with and manipulate a running ISC DHCP server. All functions return a value of 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 +second parameter of the +.Fn dhcpctl_wait_for_completion call. .\" .\" @@ -235,19 +262,66 @@ OMAPI port). No authentication is used for the connection. .\" .\" .Pp +.Fn 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, \fBtimeout\fR. If the value is null, it will wait indefinetly +Otherwise it will wait for the amount of time specified by \fBtimeout\fR +(tv_sec:tv_usec). Values of zero for both fields are valid but not recommended. +An example is shown below: +.Pp +For example: +.Bd -literal -offset indent +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); +.Ed +.Pp +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. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_disconnect +closes the open connection specified by the first parameter, \fBcxn\fR. Note +that this call will free the connection object and \fBcxn\fR will be set to + nul. If the second parameter,\fBforce\fR, 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. +.Pp +For example: +.Bd -literal -offset indent +s = dhcpctl_disconnect(&cxn, 1); +.Ed +.Pp +will close the connection immediately. This funcion should be considered +\fBEXPERIMENTAL\fR. +.\" +.\" +.\" +.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) +if (s != ISC_R_SUCCESS) local_failure(s); else if (wv != ISC_R_SUCCESS) server_failure(wc); .Ed .Pp -The call to +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. @@ -255,6 +329,43 @@ to the server is lost. .\" .\" .Pp + +.Fn 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, \fBtimeout\fR. If the value is null, it will wait indefinetly or +until the connection is lost. Otherwise it will wait for the amount of time +specified by \fBtimeout\fR (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: +.Bd -literal -offset indent + +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); +} +.Ed +.Pp +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 +\fBdhcpctl_wait_for_completion()\fR 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 +\fBdisconnet()\fR, and then reconnecting via \fBconnect()\fR. Please note +this function should be considered \fBEXPERIMENTAL\fR. + +.\" +.\" +.\" +.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 @@ -290,7 +401,7 @@ The .Fn dhcpctl_set_boolean_value , and .Fn dhcpctl_set_int_value -functions all set a value on the object handle. +functions all set a value on the object handle. .\" .\" .\" @@ -319,7 +430,7 @@ handle. .\" .\" .Pp -The +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 @@ -327,23 +438,23 @@ 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 +third is the same value as the second parameter given to .Fn dhcpctl_set_callback . .\" .\" .\" .Pp -The +The .Fn dhcpctl_new_authenticator creates a new authenticator object to be used for signing the messages -that cross over the network. The +that cross over the network. The .Dq name , .Dq algorithm , -and +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 +and must be used as the 4th parameter to .Fn 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. @@ -352,11 +463,11 @@ from how the value appears in the dhcpd.conf file. .\" .Pp .Fn dhcpctl_new_object -creates a local handle for an object on the server. The +creates a local handle for an object on the server. The .Dq object_type -parameter is the ascii name of the type of object being accessed. e.g. +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 +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 @@ -385,22 +496,22 @@ was also specified .\" .\" .Pp -The +The .Fn omapi_data_string_new function allocates a new .Ft dhcpctl_data_string -object. The data string will be large enough to hold +object. The data string will be large enough to hold .Dq length bytes of data. The -.Dq file +.Dq file and .Dq lineno arguments are the source file location the call is made from, typically by -using the +using the .Dv __FILE__ and .Dv __LINE__ -macros or the +macros or the .Dv MDL macro defined in . @@ -414,11 +525,11 @@ deallocates a data string created by The memory for the object won't be freed until the last reference is released. .Sh EXAMPLES -.Pp +.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 omitted for brevity. +that most error checking has been omitted for brevity. .Bd -literal -offset indent #include <sys/time.h> #include <stdio.h> @@ -446,7 +557,7 @@ int main (int argc, char **argv) { dhcpctl_connect (&connection, "127.0.0.1", 7911, 0); - + dhcpctl_new_object (&lease, connection, "lease"); @@ -492,4 +603,3 @@ omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5). is maintained by ISC. To learn more about Internet Systems Consortium, see .B https://www.isc.org - |