|
|
3b9e0e2 |
.\" -*- nroff -*-
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\" Project: DHCP
|
|
|
3b9e0e2 |
.\" File: dhcpctl.3
|
|
|
3b9e0e2 |
.\" RCSId: $Id$
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
|
|
|
3b9e0e2 |
.\" Copyright (c) 2000-2003 by Internet Software Consortium
|
|
|
3b9e0e2 |
.\" Copyright (c) 2000 Nominum, Inc.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\" Permission to use, copy, modify, and distribute this software for any
|
|
|
3b9e0e2 |
.\" purpose with or without fee is hereby granted, provided that the above
|
|
|
3b9e0e2 |
.\" copyright notice and this permission notice appear in all copies.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
|
|
|
3b9e0e2 |
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
3b9e0e2 |
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
|
|
|
3b9e0e2 |
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
3b9e0e2 |
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
3b9e0e2 |
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
|
|
|
3b9e0e2 |
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\" Internet Systems Consortium, Inc.
|
|
|
3b9e0e2 |
.\" 950 Charter Street
|
|
|
3b9e0e2 |
.\" Redwood City, CA 94063
|
|
|
3b9e0e2 |
.\" <info@isc.org>
|
|
|
3b9e0e2 |
.\" http://www.isc.org/
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\" Description: dhcpctl man page.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Dd Nov 15, 2000
|
|
|
3b9e0e2 |
.Dt DHCPCTL 3
|
|
|
3b9e0e2 |
.Os DHCP 3
|
|
|
3b9e0e2 |
.ds vT DHCP Programmer's Manual
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Sh NAME
|
|
|
3b9e0e2 |
.Nm dhcpctl_initialize
|
|
|
3b9e0e2 |
.Nd dhcpctl library initialization.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Sh SYNOPSIS
|
|
|
3b9e0e2 |
.Fd #include <dhcpctl.h>
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_initialize
|
|
|
3b9e0e2 |
.Fa void
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_connect
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle *cxn"
|
|
|
3b9e0e2 |
.Fa "const char *host"
|
|
|
3b9e0e2 |
.Fa "int port"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle auth"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_wait_for_completion
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_status *status"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_get_value
|
|
|
3b9e0e2 |
.Fa "dhcpctl_data_string *value"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "const char *name"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_get_boolean
|
|
|
3b9e0e2 |
.Fa "int *value"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "const char *name"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_set_value
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_data_string value"
|
|
|
3b9e0e2 |
.Fa "const char *name"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_set_string_value
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "const char *value"
|
|
|
3b9e0e2 |
.Fa "const char *name"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_set_boolean_value
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "int value"
|
|
|
3b9e0e2 |
.Fa "const char *name"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_set_int_value
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "int value"
|
|
|
3b9e0e2 |
.Fa "const char *name"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_object_update
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle connection"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_object_refresh
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle connection"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_object_remove
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle connection"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_set_callback
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "void *data"
|
|
|
3b9e0e2 |
.Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_new_authenticator
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle *object"
|
|
|
3b9e0e2 |
.Fa "const char *name"
|
|
|
3b9e0e2 |
.Fa "const char *algorithm"
|
|
|
3b9e0e2 |
.Fa "const char *secret"
|
|
|
3b9e0e2 |
.Fa "unsigned secret_len"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_new_object
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle *object"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle connection"
|
|
|
3b9e0e2 |
.Fa "const char *object_type"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft dhcpctl_status
|
|
|
3b9e0e2 |
.Fo dhcpctl_open_object
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle object"
|
|
|
3b9e0e2 |
.Fa "dhcpctl_handle connection"
|
|
|
3b9e0e2 |
.Fa "int flags"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft isc_result_t
|
|
|
3b9e0e2 |
.Fo omapi_data_string_new
|
|
|
3b9e0e2 |
.Fa dhcpctl_data_string *data
|
|
|
3b9e0e2 |
.Fa unsigned int length
|
|
|
3b9e0e2 |
.Fa const char *filename,
|
|
|
3b9e0e2 |
.Fa int lineno
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Ft isc_result_t
|
|
|
3b9e0e2 |
.Fo dhcpctl_data_string_dereference
|
|
|
3b9e0e2 |
.Fa "dhcpctl_data_string *"
|
|
|
3b9e0e2 |
.Fa "const char *"
|
|
|
3b9e0e2 |
.Fa "int"
|
|
|
3b9e0e2 |
.Fc
|
|
|
3b9e0e2 |
.Sh DESCRIPTION
|
|
|
3b9e0e2 |
The dhcpctl set of functions provide an API that can be used to communicate
|
|
|
3b9e0e2 |
with and manipulate a running ISC DHCP server. All functions return a value of
|
|
|
3b9e0e2 |
.Dv isc_result_t .
|
|
|
3b9e0e2 |
The return values reflects the result of operations to local data
|
|
|
3b9e0e2 |
structures. If an operation fails on the server for any reason, then the error
|
|
|
3b9e0e2 |
result will be returned through the
|
|
|
3b9e0e2 |
second parameter of the
|
|
|
3b9e0e2 |
.Fn dhcpctl_wait_for_completion
|
|
|
3b9e0e2 |
call.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_initialize
|
|
|
3b9e0e2 |
sets up the data structures the library needs to do its work. This function
|
|
|
3b9e0e2 |
must be called once before any other.
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_connect
|
|
|
3b9e0e2 |
opens a connection to the DHCP server at the given host and port. If an
|
|
|
3b9e0e2 |
authenticator has been created for the connection, then it is given as the 4th
|
|
|
3b9e0e2 |
argument. On a successful return the address pointed at by the first
|
|
|
3b9e0e2 |
argument will have a new connection object assigned to it.
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
For example:
|
|
|
3b9e0e2 |
.Bd -literal -offset indent
|
|
|
3b9e0e2 |
s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
|
|
|
3b9e0e2 |
.Ed
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
connects to the DHCP server on the localhost via port 7911 (the standard
|
|
|
3b9e0e2 |
OMAPI port). No authentication is used for the connection.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_wait_for_completion
|
|
|
3b9e0e2 |
flushes a pending message to the server and waits for the response. The result
|
|
|
3b9e0e2 |
of the request as processed on the server is returned via the second
|
|
|
3b9e0e2 |
parameter.
|
|
|
3b9e0e2 |
.Bd -literal -offset indent
|
|
|
3b9e0e2 |
s = dhcpctl_wait_for_completion(cxn, &wv;;
|
|
|
3b9e0e2 |
if (s != ISC_R_SUCCESS)
|
|
|
3b9e0e2 |
local_failure(s);
|
|
|
3b9e0e2 |
else if (wv != ISC_R_SUCCESS)
|
|
|
3b9e0e2 |
server_failure(wc);
|
|
|
3b9e0e2 |
.Ed
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
The call to
|
|
|
3b9e0e2 |
.Fn dhcpctl_wait_for_completion
|
|
|
3b9e0e2 |
won't return until the remote message processing completes or the connection
|
|
|
3b9e0e2 |
to the server is lost.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_get_value
|
|
|
3b9e0e2 |
extracts a value of an attribute from the handle. The value can be of any
|
|
|
3b9e0e2 |
length and is treated as a sequence of bytes. The handle must have been
|
|
|
3b9e0e2 |
created first with
|
|
|
3b9e0e2 |
.Fn dhcpctl_new_object
|
|
|
3b9e0e2 |
and opened with
|
|
|
3b9e0e2 |
.Fn dhcpctl_open_object .
|
|
|
3b9e0e2 |
The value is returned via the parameter named
|
|
|
3b9e0e2 |
.Dq value .
|
|
|
3b9e0e2 |
The last parameter is the name of attribute to retrieve.
|
|
|
3b9e0e2 |
.Bd -literal -offset indent
|
|
|
3b9e0e2 |
dhcpctl_data_string value = NULL;
|
|
|
3b9e0e2 |
dhcpctl_handle lease;
|
|
|
3b9e0e2 |
time_t thetime;
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
s = dhcpctl_get_value (&value, lease, "ends");
|
|
|
3b9e0e2 |
assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
|
|
|
3b9e0e2 |
memcpy(&thetime, value->value, value->len);
|
|
|
3b9e0e2 |
.Ed
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_get_boolean
|
|
|
3b9e0e2 |
extracts a boolean valued attribute from the object handle.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
The
|
|
|
3b9e0e2 |
.Fn dhcpctl_set_value ,
|
|
|
3b9e0e2 |
.Fn dhcpctl_set_string_value ,
|
|
|
3b9e0e2 |
.Fn dhcpctl_set_boolean_value ,
|
|
|
3b9e0e2 |
and
|
|
|
3b9e0e2 |
.Fn dhcpctl_set_int_value
|
|
|
3b9e0e2 |
functions all set a value on the object handle.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_object_update
|
|
|
3b9e0e2 |
function queues a request for
|
|
|
3b9e0e2 |
all the changes made to the object handle be be sent to the remote
|
|
|
3b9e0e2 |
for processing. The changes made to the atributes on the handle will be
|
|
|
3b9e0e2 |
applied to remote object if permitted.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_object_refresh
|
|
|
3b9e0e2 |
queues up a request for a fresh copy of all the attribute values to be sent
|
|
|
3b9e0e2 |
from the remote to
|
|
|
3b9e0e2 |
refresh the values in the local object handle.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_object_remove
|
|
|
3b9e0e2 |
queues a request for the removal on the server of the object referenced by the
|
|
|
3b9e0e2 |
handle.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
The
|
|
|
3b9e0e2 |
.Fn dhcpctl_set_callback
|
|
|
3b9e0e2 |
function sets up a user-defined function to be called when an event completes
|
|
|
3b9e0e2 |
on the given object handle. This is needed for asynchronous handling of
|
|
|
3b9e0e2 |
events, versus the synchronous handling given by
|
|
|
3b9e0e2 |
.Fn dhcpctl_wait_for_completion .
|
|
|
3b9e0e2 |
When the function is called the first parameter is the object the event
|
|
|
3b9e0e2 |
arrived for, the second is the status of the message that was processed, the
|
|
|
3b9e0e2 |
third is the same value as the second parameter given to
|
|
|
3b9e0e2 |
.Fn dhcpctl_set_callback .
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
The
|
|
|
3b9e0e2 |
.Fn dhcpctl_new_authenticator
|
|
|
3b9e0e2 |
creates a new authenticator object to be used for signing the messages
|
|
|
3b9e0e2 |
that cross over the network. The
|
|
|
3b9e0e2 |
.Dq name ,
|
|
|
3b9e0e2 |
.Dq algorithm ,
|
|
|
3b9e0e2 |
and
|
|
|
3b9e0e2 |
.Dq secret
|
|
|
3b9e0e2 |
values must all match what the server uses and are defined in its
|
|
|
3b9e0e2 |
configuration file. The created object is returned through the first parameter
|
|
|
3b9e0e2 |
and must be used as the 4th parameter to
|
|
|
3b9e0e2 |
.Fn dhcpctl_connect .
|
|
|
3b9e0e2 |
Note that the 'secret' value must not be base64 encoded, which is different
|
|
|
3b9e0e2 |
from how the value appears in the dhcpd.conf file.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_new_object
|
|
|
3b9e0e2 |
creates a local handle for an object on the the server. The
|
|
|
3b9e0e2 |
.Dq object_type
|
|
|
3b9e0e2 |
parameter is the ascii name of the type of object being accessed. e.g.
|
|
|
3b9e0e2 |
.Qq lease .
|
|
|
3b9e0e2 |
This function only sets up local data structures, it does not queue any
|
|
|
3b9e0e2 |
messages
|
|
|
3b9e0e2 |
to be sent to the remote side,
|
|
|
3b9e0e2 |
.Fn dhcpctl_open_object
|
|
|
3b9e0e2 |
does that.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_open_object
|
|
|
3b9e0e2 |
builds and queues the request to the remote side. This function is used with
|
|
|
3b9e0e2 |
handle created via
|
|
|
3b9e0e2 |
.Fn dhcpctl_new_object .
|
|
|
3b9e0e2 |
The flags argument is a bit mask with the following values available for
|
|
|
3b9e0e2 |
setting:
|
|
|
3b9e0e2 |
.Bl -tag -offset indent -width 20
|
|
|
3b9e0e2 |
.It DHCPCTL_CREATE
|
|
|
3b9e0e2 |
if the object does not exist then the remote will create it
|
|
|
3b9e0e2 |
.It DHCPCTL_UPDATE
|
|
|
3b9e0e2 |
update the object on the remote side using the
|
|
|
3b9e0e2 |
attributes already set in the handle.
|
|
|
3b9e0e2 |
.It DHCPCTL_EXCL
|
|
|
3b9e0e2 |
return and error if the object exists and DHCPCTL_CREATE
|
|
|
3b9e0e2 |
was also specified
|
|
|
3b9e0e2 |
.El
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
The
|
|
|
3b9e0e2 |
.Fn omapi_data_string_new
|
|
|
3b9e0e2 |
function allocates a new
|
|
|
3b9e0e2 |
.Ft dhcpctl_data_string
|
|
|
3b9e0e2 |
object. The data string will be large enough to hold
|
|
|
3b9e0e2 |
.Dq length
|
|
|
3b9e0e2 |
bytes of data. The
|
|
|
3b9e0e2 |
.Dq file
|
|
|
3b9e0e2 |
and
|
|
|
3b9e0e2 |
.Dq lineno
|
|
|
3b9e0e2 |
arguments are the source file location the call is made from, typically by
|
|
|
3b9e0e2 |
using the
|
|
|
3b9e0e2 |
.Dv __FILE__
|
|
|
3b9e0e2 |
and
|
|
|
3b9e0e2 |
.Dv __LINE__
|
|
|
3b9e0e2 |
macros or the
|
|
|
3b9e0e2 |
.Dv MDL
|
|
|
3b9e0e2 |
macro defined in
|
|
|
3b9e0e2 |
.
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.\"
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
.Fn dhcpctl_data_string_dereference
|
|
|
3b9e0e2 |
deallocates a data string created by
|
|
|
3b9e0e2 |
.Fn omapi_data_string_new .
|
|
|
3b9e0e2 |
The memory for the object won't be freed until the last reference is
|
|
|
3b9e0e2 |
released.
|
|
|
3b9e0e2 |
.Sh EXAMPLES
|
|
|
3b9e0e2 |
.Pp
|
|
|
3b9e0e2 |
The following program will connect to the DHCP server running on the local
|
|
|
3b9e0e2 |
host and will get the details of the existing lease for IP address
|
|
|
3b9e0e2 |
10.0.0.101. It will then print out the time the lease is due to expire. Note
|
|
|
3b9e0e2 |
that most error checking has been ommitted for brevity.
|
|
|
3b9e0e2 |
.Bd -literal -offset indent
|
|
|
3b9e0e2 |
#include <stdarg.h>
|
|
|
3b9e0e2 |
#include <sys/time.h>
|
|
|
3b9e0e2 |
#include <sys/socket.h>
|
|
|
3b9e0e2 |
#include <stdio.h>
|
|
|
3b9e0e2 |
#include <netinet/in.h>
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
#include <isc/result.h>
|
|
|
3b9e0e2 |
#include <dhcpctl.h>
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
int main (int argc, char **argv) {
|
|
|
3b9e0e2 |
dhcpctl_data_string ipaddrstring = NULL;
|
|
|
3b9e0e2 |
dhcpctl_data_string value = NULL;
|
|
|
3b9e0e2 |
dhcpctl_handle connection = NULL;
|
|
|
3b9e0e2 |
dhcpctl_handle lease = NULL;
|
|
|
3b9e0e2 |
isc_result_t waitstatus;
|
|
|
3b9e0e2 |
struct in_addr convaddr;
|
|
|
3b9e0e2 |
time_t thetime;
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_initialize ();
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_connect (&connection, "127.0.0.1",
|
|
|
3b9e0e2 |
7911, 0);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_new_object (&lease, connection,
|
|
|
3b9e0e2 |
"lease");
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
memset (&ipaddrstring, 0, sizeof
|
|
|
3b9e0e2 |
ipaddrstring);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
inet_pton(AF_INET, "10.0.0.101",
|
|
|
3b9e0e2 |
&convaddr);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
omapi_data_string_new (&ipaddrstring,
|
|
|
3b9e0e2 |
4, MDL);
|
|
|
3b9e0e2 |
memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_set_value (lease, ipaddrstring,
|
|
|
3b9e0e2 |
"ip-address");
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_open_object (lease, connection, 0);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_wait_for_completion (lease,
|
|
|
3b9e0e2 |
&waitstatus);
|
|
|
3b9e0e2 |
if (waitstatus != ISC_R_SUCCESS) {
|
|
|
3b9e0e2 |
/* server not authoritative */
|
|
|
3b9e0e2 |
exit (0);
|
|
|
3b9e0e2 |
}
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_data_string_dereference(&ipaddrstring,
|
|
|
3b9e0e2 |
MDL);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_get_value (&value, lease, "ends");
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
memcpy(&thetime, value->value, value->len);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
dhcpctl_data_string_dereference(&value, MDL);
|
|
|
3b9e0e2 |
|
|
|
3b9e0e2 |
fprintf (stdout, "ending time is %s",
|
|
|
3b9e0e2 |
ctime(&thetime));
|
|
|
3b9e0e2 |
}
|
|
|
3b9e0e2 |
.Ed
|
|
|
3b9e0e2 |
.Sh SEE ALSO
|
|
|
3b9e0e2 |
omapi(3), omshell(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
|
|
|
3b9e0e2 |
.Sh AUTHOR
|
|
|
3b9e0e2 |
.Em dhcpctl
|
|
|
3b9e0e2 |
was written by Ted Lemon of Nominum, Inc.
|
|
|
3b9e0e2 |
This preliminary documentation was written by James Brister of Nominum, Inc.
|