[#76] Added new functions to man page dhcpctl/dhcpctl.3

    Also updated copyrights

diff --git a/common/conflex.c b/common/conflex.c
index db1e1a09af111d50b530c6bf20533de38e640eb9..e8d8c629e00214f219c921f156619346cb85ec59 100644 (file)
--- a/common/conflex.c
+++ b/common/conflex.c
@@ -3,7 +3,7 @@
    Lexical scanner for dhcpd config file... */
 
 /*
- * Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 1995-2003 by Internet Software Consortium
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

diff --git a/dhcpctl/dhcpctl.3 b/dhcpctl/dhcpctl.3
index dcc08992db867f247539213e34895adbcb83d7c5..9b2612095aba89eecde97e8247a274b4b18d7fb5 100644 (file)
--- a/dhcpctl/dhcpctl.3
+++ b/dhcpctl/dhcpctl.3
@@ -4,8 +4,7 @@
 .\" 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.
 .\"
@@ -61,6 +60,14 @@
 .\"
 .\"
 .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 +76,15 @@
 .\"
 .\"
 .Ft dhcpctl_status
+.Fo dhcpctl_timed_wait_for_completion
+.Fa "dhcpctl_handle object"
+.Fa "struct timeval *timeout"
+.Fa "dhcpctl_status *status"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
 .Fo dhcpctl_get_value
 .Fa "dhcpctl_data_string *value"
 .Fa "dhcpctl_handle object"
@@ -235,6 +251,27 @@ OMAPI port). No authentication is used for the connection.
 .\"
 .\"
 .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
@@ -251,6 +288,43 @@ 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_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 second
+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 third 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, &timeout, &wv);
+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.
+
 .\"
 .\"
 .\"

diff --git a/dhcpctl/dhcpctl.c b/dhcpctl/dhcpctl.c
index e8834382eadecb854e613df621d7914198585d7f..845fa18c6f03131b47e5f3c126c1b81022fe97ab 100644 (file)
--- a/dhcpctl/dhcpctl.c
+++ b/dhcpctl/dhcpctl.c
@@ -3,7 +3,7 @@
    Subroutines providing general support for objects. */
 
 /*
- * Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 1999-2003 by Internet Software Consortium
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

diff --git a/dhcpctl/dhcpctl.h b/dhcpctl/dhcpctl.h
index 0f779bd802574e591b806ae290fcc4860455860e..083ccf1209422c3634953763cfdb27c8fd226188 100644 (file)
--- a/dhcpctl/dhcpctl.h
+++ b/dhcpctl/dhcpctl.h
@@ -3,7 +3,7 @@
    Subroutines providing general support for objects. */
 
 /*
- * Copyright (c) 2004,2009,2014 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 1999-2003 by Internet Software Consortium
  *
  * Permission to use, copy, modify, and distribute this software for any

diff --git a/dhcpctl/omshell.c b/dhcpctl/omshell.c
index 785f59a6652d6ad474a7d5b83f387de4d2e33dfa..ab99b0f4153f7c8331b21354e7db769e2e31a6e5 100644 (file)
--- a/dhcpctl/omshell.c
+++ b/dhcpctl/omshell.c
@@ -3,7 +3,7 @@
    Examine and modify omapi objects. */
 
 /*
- * Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 2001-2003 by Internet Software Consortium
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

diff --git a/includes/dhctoken.h b/includes/dhctoken.h
index 223e11101705f8216783de1f137cc68688e99e91..3e71a4738ebc8bcbdfdc2d0dc66f10b7a8b23e00 100644 (file)
--- a/includes/dhctoken.h
+++ b/includes/dhctoken.h
@@ -3,7 +3,7 @@
    Tokens for config file lexer and parser. */
 
 /*
- * Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 1996-2003 by Internet Software Consortium
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

diff --git a/includes/omapip/omapip_p.h b/includes/omapip/omapip_p.h
index 323bba3ea8523e3fceb473f5dcdefbe83dcde11d..ec10f7e513e8a0a6a9f0bc813adb806e35942000 100644 (file)
--- a/includes/omapip/omapip_p.h
+++ b/includes/omapip/omapip_p.h
@@ -3,7 +3,7 @@
    Private master include file for the OMAPI library. */
 
 /*
- * Copyright (c) 2004-2019 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 1996-2003 by Internet Software Consortium
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

diff --git a/omapip/dispatch.c b/omapip/dispatch.c
index c730094cd191a31749bdfe47c65935824efc2a20..34938b39e01811c2a41990a57b09aa3a32f5e5c1 100644 (file)
--- a/omapip/dispatch.c
+++ b/omapip/dispatch.c
@@ -3,7 +3,7 @@
    I/O dispatcher. */
 
 /*
- * Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 1999-2003 by Internet Software Consortium
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

diff --git a/omapip/support.c b/omapip/support.c
index 92000a1776925636e7cfe9affa53860d33029e8e..8f2581f13307d47c15e534a64f625483e53f2db0 100644 (file)
--- a/omapip/support.c
+++ b/omapip/support.c
@@ -3,7 +3,7 @@
    Subroutines providing general support for objects. */
 
 /*
- * Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (c) 2004-2020 by Internet Systems Consortium, Inc. ("ISC")
  * Copyright (c) 1999-2003 by Internet Software Consortium
  *
  * This Source Code Form is subject to the terms of the Mozilla Public