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
communicate with and manipulate 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
parameter 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 sent to the remote for processing. The
changes made to the attributes 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 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
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(). Note that the 'secret' value must not be base64
encoded, which is different from how the value appears in the dhcpd.conf
file.
dhcpctl_new_object() creates a local handle for an object on 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 handle.
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 omitted for brevity.
#include <sys/time.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdarg.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include "omapip/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(1), dhcpd(8), dhclient(8), dhcpd.conf(5),
dhclient.conf(5).
AUTHOR
dhcpctl is maintained by ISC. To learn more about Internet Systems
Consortium, see https://www.isc.org
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
