Annotation of embedaddon/dhcp/dhcpctl/dhcpctl.3, revision 1.1
1.1 ! misho 1: .\" -*- nroff -*-
! 2: .\"
! 3: .\" Project: DHCP
! 4: .\" File: dhcpctl.3
! 5: .\" RCSId: $Id: dhcpctl.3,v 1.6.8.2.10.1 2011-04-26 00:01:57 sar Exp $
! 6: .\"
! 7: .\" Copyright (c) 2011 by Internet Systems Consortium, Inc. ("ISC")
! 8: .\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
! 9: .\" Copyright (c) 2000-2003 by Internet Software Consortium
! 10: .\" Copyright (c) 2000 Nominum, Inc.
! 11: .\"
! 12: .\" Permission to use, copy, modify, and distribute this software for any
! 13: .\" purpose with or without fee is hereby granted, provided that the above
! 14: .\" copyright notice and this permission notice appear in all copies.
! 15: .\"
! 16: .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
! 17: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 18: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
! 19: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 20: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 21: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
! 22: .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 23: .\"
! 24: .\" Internet Systems Consortium, Inc.
! 25: .\" 950 Charter Street
! 26: .\" Redwood City, CA 94063
! 27: .\" <info@isc.org>
! 28: .\" https://www.isc.org/
! 29: .\"
! 30: .\" Description: dhcpctl man page.
! 31: .\"
! 32: .\"
! 33: .Dd Nov 15, 2000
! 34: .Dt DHCPCTL 3
! 35: .Os DHCP 3
! 36: .ds vT DHCP Programmer's Manual
! 37: .\"
! 38: .\"
! 39: .\"
! 40: .Sh NAME
! 41: .Nm dhcpctl_initialize
! 42: .Nd dhcpctl library initialization.
! 43: .\"
! 44: .\"
! 45: .\"
! 46: .Sh SYNOPSIS
! 47: .Fd #include <dhcpctl/dhcpctl.h>
! 48: .Ft dhcpctl_status
! 49: .Fo dhcpctl_initialize
! 50: .Fa void
! 51: .Fc
! 52: .\"
! 53: .Ft dhcpctl_status
! 54: .Fo dhcpctl_connect
! 55: .Fa "dhcpctl_handle *cxn"
! 56: .Fa "const char *host"
! 57: .Fa "int port"
! 58: .Fa "dhcpctl_handle auth"
! 59: .Fc
! 60: .\"
! 61: .\"
! 62: .\"
! 63: .Ft dhcpctl_status
! 64: .Fo dhcpctl_wait_for_completion
! 65: .Fa "dhcpctl_handle object"
! 66: .Fa "dhcpctl_status *status"
! 67: .Fc
! 68: .\"
! 69: .\"
! 70: .\"
! 71: .Ft dhcpctl_status
! 72: .Fo dhcpctl_get_value
! 73: .Fa "dhcpctl_data_string *value"
! 74: .Fa "dhcpctl_handle object"
! 75: .Fa "const char *name"
! 76: .Fc
! 77: .\"
! 78: .\"
! 79: .\"
! 80: .Ft dhcpctl_status
! 81: .Fo dhcpctl_get_boolean
! 82: .Fa "int *value"
! 83: .Fa "dhcpctl_handle object"
! 84: .Fa "const char *name"
! 85: .Fc
! 86: .\"
! 87: .\"
! 88: .\"
! 89: .Ft dhcpctl_status
! 90: .Fo dhcpctl_set_value
! 91: .Fa "dhcpctl_handle object"
! 92: .Fa "dhcpctl_data_string value"
! 93: .Fa "const char *name"
! 94: .Fc
! 95: .\"
! 96: .\"
! 97: .\"
! 98: .Ft dhcpctl_status
! 99: .Fo dhcpctl_set_string_value
! 100: .Fa "dhcpctl_handle object"
! 101: .Fa "const char *value"
! 102: .Fa "const char *name"
! 103: .Fc
! 104: .\"
! 105: .\"
! 106: .\"
! 107: .Ft dhcpctl_status
! 108: .Fo dhcpctl_set_boolean_value
! 109: .Fa "dhcpctl_handle object"
! 110: .Fa "int value"
! 111: .Fa "const char *name"
! 112: .Fc
! 113: .\"
! 114: .\"
! 115: .\"
! 116: .Ft dhcpctl_status
! 117: .Fo dhcpctl_set_int_value
! 118: .Fa "dhcpctl_handle object"
! 119: .Fa "int value"
! 120: .Fa "const char *name"
! 121: .Fc
! 122: .\"
! 123: .\"
! 124: .\"
! 125: .Ft dhcpctl_status
! 126: .Fo dhcpctl_object_update
! 127: .Fa "dhcpctl_handle connection"
! 128: .Fa "dhcpctl_handle object"
! 129: .Fc
! 130: .\"
! 131: .\"
! 132: .\"
! 133: .Ft dhcpctl_status
! 134: .Fo dhcpctl_object_refresh
! 135: .Fa "dhcpctl_handle connection"
! 136: .Fa "dhcpctl_handle object"
! 137: .Fc
! 138: .\"
! 139: .\"
! 140: .\"
! 141: .Ft dhcpctl_status
! 142: .Fo dhcpctl_object_remove
! 143: .Fa "dhcpctl_handle connection"
! 144: .Fa "dhcpctl_handle object"
! 145: .Fc
! 146: .\"
! 147: .\"
! 148: .\"
! 149: .Ft dhcpctl_status
! 150: .Fo dhcpctl_set_callback
! 151: .Fa "dhcpctl_handle object"
! 152: .Fa "void *data"
! 153: .Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
! 154: .Fc
! 155: .\"
! 156: .\"
! 157: .\"
! 158: .Ft dhcpctl_status
! 159: .Fo dhcpctl_new_authenticator
! 160: .Fa "dhcpctl_handle *object"
! 161: .Fa "const char *name"
! 162: .Fa "const char *algorithm"
! 163: .Fa "const char *secret"
! 164: .Fa "unsigned secret_len"
! 165: .Fc
! 166: .\"
! 167: .\"
! 168: .\"
! 169: .Ft dhcpctl_status
! 170: .Fo dhcpctl_new_object
! 171: .Fa "dhcpctl_handle *object"
! 172: .Fa "dhcpctl_handle connection"
! 173: .Fa "const char *object_type"
! 174: .Fc
! 175: .\"
! 176: .\"
! 177: .\"
! 178: .Ft dhcpctl_status
! 179: .Fo dhcpctl_open_object
! 180: .Fa "dhcpctl_handle object"
! 181: .Fa "dhcpctl_handle connection"
! 182: .Fa "int flags"
! 183: .Fc
! 184: .\"
! 185: .\"
! 186: .\"
! 187: .Ft isc_result_t
! 188: .Fo omapi_data_string_new
! 189: .Fa dhcpctl_data_string *data
! 190: .Fa unsigned int length
! 191: .Fa const char *filename,
! 192: .Fa int lineno
! 193: .Fc
! 194: .\"
! 195: .\"
! 196: .\"
! 197: .Ft isc_result_t
! 198: .Fo dhcpctl_data_string_dereference
! 199: .Fa "dhcpctl_data_string *"
! 200: .Fa "const char *"
! 201: .Fa "int"
! 202: .Fc
! 203: .Sh DESCRIPTION
! 204: The dhcpctl set of functions provide an API that can be used to communicate
! 205: with and manipulate a running ISC DHCP server. All functions return a value of
! 206: .Dv isc_result_t .
! 207: The return values reflects the result of operations to local data
! 208: structures. If an operation fails on the server for any reason, then the error
! 209: result will be returned through the
! 210: second parameter of the
! 211: .Fn dhcpctl_wait_for_completion
! 212: call.
! 213: .\"
! 214: .\"
! 215: .\"
! 216: .Pp
! 217: .Fn dhcpctl_initialize
! 218: sets up the data structures the library needs to do its work. This function
! 219: must be called once before any other.
! 220: .Pp
! 221: .Fn dhcpctl_connect
! 222: opens a connection to the DHCP server at the given host and port. If an
! 223: authenticator has been created for the connection, then it is given as the 4th
! 224: argument. On a successful return the address pointed at by the first
! 225: argument will have a new connection object assigned to it.
! 226: .Pp
! 227: For example:
! 228: .Bd -literal -offset indent
! 229: s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
! 230: .Ed
! 231: .Pp
! 232: connects to the DHCP server on the localhost via port 7911 (the standard
! 233: OMAPI port). No authentication is used for the connection.
! 234: .\"
! 235: .\"
! 236: .\"
! 237: .Pp
! 238: .Fn dhcpctl_wait_for_completion
! 239: flushes a pending message to the server and waits for the response. The result
! 240: of the request as processed on the server is returned via the second
! 241: parameter.
! 242: .Bd -literal -offset indent
! 243: s = dhcpctl_wait_for_completion(cxn, &wv);
! 244: if (s != ISC_R_SUCCESS)
! 245: local_failure(s);
! 246: else if (wv != ISC_R_SUCCESS)
! 247: server_failure(wc);
! 248: .Ed
! 249: .Pp
! 250: The call to
! 251: .Fn dhcpctl_wait_for_completion
! 252: won't return until the remote message processing completes or the connection
! 253: to the server is lost.
! 254: .\"
! 255: .\"
! 256: .\"
! 257: .Pp
! 258: .Fn dhcpctl_get_value
! 259: extracts a value of an attribute from the handle. The value can be of any
! 260: length and is treated as a sequence of bytes. The handle must have been
! 261: created first with
! 262: .Fn dhcpctl_new_object
! 263: and opened with
! 264: .Fn dhcpctl_open_object .
! 265: The value is returned via the parameter named
! 266: .Dq value .
! 267: The last parameter is the name of attribute to retrieve.
! 268: .Bd -literal -offset indent
! 269: dhcpctl_data_string value = NULL;
! 270: dhcpctl_handle lease;
! 271: time_t thetime;
! 272:
! 273: s = dhcpctl_get_value (&value, lease, "ends");
! 274: assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
! 275: memcpy(&thetime, value->value, value->len);
! 276: .Ed
! 277: .\"
! 278: .\"
! 279: .\"
! 280: .Pp
! 281: .Fn dhcpctl_get_boolean
! 282: extracts a boolean valued attribute from the object handle.
! 283: .\"
! 284: .\"
! 285: .\"
! 286: .Pp
! 287: The
! 288: .Fn dhcpctl_set_value ,
! 289: .Fn dhcpctl_set_string_value ,
! 290: .Fn dhcpctl_set_boolean_value ,
! 291: and
! 292: .Fn dhcpctl_set_int_value
! 293: functions all set a value on the object handle.
! 294: .\"
! 295: .\"
! 296: .\"
! 297: .Pp
! 298: .Fn dhcpctl_object_update
! 299: function queues a request for
! 300: all the changes made to the object handle be be sent to the remote
! 301: for processing. The changes made to the atributes on the handle will be
! 302: applied to remote object if permitted.
! 303: .\"
! 304: .\"
! 305: .\"
! 306: .Pp
! 307: .Fn dhcpctl_object_refresh
! 308: queues up a request for a fresh copy of all the attribute values to be sent
! 309: from the remote to
! 310: refresh the values in the local object handle.
! 311: .\"
! 312: .\"
! 313: .\"
! 314: .Pp
! 315: .Fn dhcpctl_object_remove
! 316: queues a request for the removal on the server of the object referenced by the
! 317: handle.
! 318: .\"
! 319: .\"
! 320: .\"
! 321: .Pp
! 322: The
! 323: .Fn dhcpctl_set_callback
! 324: function sets up a user-defined function to be called when an event completes
! 325: on the given object handle. This is needed for asynchronous handling of
! 326: events, versus the synchronous handling given by
! 327: .Fn dhcpctl_wait_for_completion .
! 328: When the function is called the first parameter is the object the event
! 329: arrived for, the second is the status of the message that was processed, the
! 330: third is the same value as the second parameter given to
! 331: .Fn dhcpctl_set_callback .
! 332: .\"
! 333: .\"
! 334: .\"
! 335: .Pp
! 336: The
! 337: .Fn dhcpctl_new_authenticator
! 338: creates a new authenticator object to be used for signing the messages
! 339: that cross over the network. The
! 340: .Dq name ,
! 341: .Dq algorithm ,
! 342: and
! 343: .Dq secret
! 344: values must all match what the server uses and are defined in its
! 345: configuration file. The created object is returned through the first parameter
! 346: and must be used as the 4th parameter to
! 347: .Fn dhcpctl_connect .
! 348: Note that the 'secret' value must not be base64 encoded, which is different
! 349: from how the value appears in the dhcpd.conf file.
! 350: .\"
! 351: .\"
! 352: .\"
! 353: .Pp
! 354: .Fn dhcpctl_new_object
! 355: creates a local handle for an object on the the server. The
! 356: .Dq object_type
! 357: parameter is the ascii name of the type of object being accessed. e.g.
! 358: .Qq lease .
! 359: This function only sets up local data structures, it does not queue any
! 360: messages
! 361: to be sent to the remote side,
! 362: .Fn dhcpctl_open_object
! 363: does that.
! 364: .\"
! 365: .\"
! 366: .\"
! 367: .Pp
! 368: .Fn dhcpctl_open_object
! 369: builds and queues the request to the remote side. This function is used with
! 370: handle created via
! 371: .Fn dhcpctl_new_object .
! 372: The flags argument is a bit mask with the following values available for
! 373: setting:
! 374: .Bl -tag -offset indent -width 20
! 375: .It DHCPCTL_CREATE
! 376: if the object does not exist then the remote will create it
! 377: .It DHCPCTL_UPDATE
! 378: update the object on the remote side using the
! 379: attributes already set in the handle.
! 380: .It DHCPCTL_EXCL
! 381: return and error if the object exists and DHCPCTL_CREATE
! 382: was also specified
! 383: .El
! 384: .\"
! 385: .\"
! 386: .\"
! 387: .Pp
! 388: The
! 389: .Fn omapi_data_string_new
! 390: function allocates a new
! 391: .Ft dhcpctl_data_string
! 392: object. The data string will be large enough to hold
! 393: .Dq length
! 394: bytes of data. The
! 395: .Dq file
! 396: and
! 397: .Dq lineno
! 398: arguments are the source file location the call is made from, typically by
! 399: using the
! 400: .Dv __FILE__
! 401: and
! 402: .Dv __LINE__
! 403: macros or the
! 404: .Dv MDL
! 405: macro defined in
! 406: .
! 407: .\"
! 408: .\"
! 409: .\"
! 410: .Pp
! 411: .Fn dhcpctl_data_string_dereference
! 412: deallocates a data string created by
! 413: .Fn omapi_data_string_new .
! 414: The memory for the object won't be freed until the last reference is
! 415: released.
! 416: .Sh EXAMPLES
! 417: .Pp
! 418: The following program will connect to the DHCP server running on the local
! 419: host and will get the details of the existing lease for IP address
! 420: 10.0.0.101. It will then print out the time the lease is due to expire. Note
! 421: that most error checking has been ommitted for brevity.
! 422: .Bd -literal -offset indent
! 423: #include <sys/time.h>
! 424: #include <stdio.h>
! 425: #include <stdlib.h>
! 426: #include <string.h>
! 427: #include <stdarg.h>
! 428:
! 429: #include <sys/socket.h>
! 430: #include <netinet/in.h>
! 431: #include <arpa/inet.h>
! 432:
! 433: #include "isc-dhcp/result.h"
! 434: #include "dhcpctl.h"
! 435:
! 436: int main (int argc, char **argv) {
! 437: dhcpctl_data_string ipaddrstring = NULL;
! 438: dhcpctl_data_string value = NULL;
! 439: dhcpctl_handle connection = NULL;
! 440: dhcpctl_handle lease = NULL;
! 441: isc_result_t waitstatus;
! 442: struct in_addr convaddr;
! 443: time_t thetime;
! 444:
! 445: dhcpctl_initialize ();
! 446:
! 447: dhcpctl_connect (&connection, "127.0.0.1",
! 448: 7911, 0);
! 449:
! 450: dhcpctl_new_object (&lease, connection,
! 451: "lease");
! 452:
! 453: memset (&ipaddrstring, 0, sizeof
! 454: ipaddrstring);
! 455:
! 456: inet_pton(AF_INET, "10.0.0.101",
! 457: &convaddr);
! 458:
! 459: omapi_data_string_new (&ipaddrstring,
! 460: 4, MDL);
! 461: memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
! 462:
! 463: dhcpctl_set_value (lease, ipaddrstring,
! 464: "ip-address");
! 465:
! 466: dhcpctl_open_object (lease, connection, 0);
! 467:
! 468: dhcpctl_wait_for_completion (lease,
! 469: &waitstatus);
! 470: if (waitstatus != ISC_R_SUCCESS) {
! 471: /* server not authoritative */
! 472: exit (0);
! 473: }
! 474:
! 475: dhcpctl_data_string_dereference(&ipaddrstring,
! 476: MDL);
! 477:
! 478: dhcpctl_get_value (&value, lease, "ends");
! 479:
! 480: memcpy(&thetime, value->value, value->len);
! 481:
! 482: dhcpctl_data_string_dereference(&value, MDL);
! 483:
! 484: fprintf (stdout, "ending time is %s",
! 485: ctime(&thetime));
! 486: }
! 487: .Ed
! 488: .Sh SEE ALSO
! 489: omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
! 490: .Sh AUTHOR
! 491: .Em dhcpctl
! 492: was written by Ted Lemon of Nominum, Inc.
! 493: This preliminary documentation was written by James Brister of Nominum, Inc.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dhcpctl.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / dhcpctl