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

    Also updated copyrights

9 files changed, 84 insertions, 10 deletions

diff --git a/common/conflex.c b/common/conflex.c
index db1e1a09..e8d8c629 100644
--- 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 dcc08992..9b261209 100644
--- 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
@@ -255,6 +292,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 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.
+
+.\"
+.\"
+.\"
+.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
diff --git a/dhcpctl/dhcpctl.c b/dhcpctl/dhcpctl.c
index e8834382..845fa18c 100644
--- 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 0f779bd8..083ccf12 100644
--- 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 785f59a6..ab99b0f4 100644
--- 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 223e1110..3e71a473 100644
--- 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 323bba3e..ec10f7e5 100644
--- 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 c730094c..34938b39 100644
--- 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 92000a17..8f2581f1 100644
--- 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