networkupstools · zykh · Feb 12, 2019 · Feb 10, 2019 · Feb 10, 2019 · Feb 10, 2019
diff --git a/clients/Makefile.am b/clients/Makefile.am
@@ -53,7 +53,7 @@ endif
 
 # libupsclient version information
 # http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
-libupsclient_la_LDFLAGS = -version-info 4:0:0
+libupsclient_la_LDFLAGS = -version-info 5:0:0
 
 # libnutclient version information
 libnutclient_la_SOURCES = nutclient.h nutclient.cpp

diff --git a/clients/upsclient.c b/clients/upsclient.c
@@ -1416,7 +1416,7 @@ int upscli_readline_timeout(UPSCONN_t *ups, char *buf, size_t buflen, unsigned i
 
 int upscli_readline(UPSCONN_t *ups, char *buf, size_t buflen)
 {
-	return upscli_readline_timeout(ups, buf, buflen, DEFAULT_TIMEOUT);
+	return upscli_readline_timeout(ups, buf, buflen, DEFAULT_NETWORK_TIMEOUT);
 }
 
 /* split upsname[@hostname[:port]] into separate components */

diff --git a/clients/upscmd.c b/clients/upscmd.c
@@ -32,8 +32,8 @@
 
 static char			*upsname = NULL, *hostname = NULL;
 static UPSCONN_t	*ups = NULL;
-static int			status_info = 0;
-static unsigned int		timeout = 10;
+static int			tracking_enabled = 0;
+static unsigned int		timeout = DEFAULT_TRACKING_TIMEOUT;
 
 struct list_t {
 	char	*name;
@@ -54,7 +54,7 @@ static void usage(const char *prog)
 	printf("  -p <password>	set password for command authentication\n");
 	printf("  -w            wait for the completion of command by the driver\n");
 	printf("                and return its actual result from the device\n");
-	printf("  -t <timeout>	set a timeout when using -w (in seconds, default \"10\")\n");
+	printf("  -t <timeout>	set a timeout when using -w (in seconds, default: %u)\n", DEFAULT_TRACKING_TIMEOUT);
 	printf("\n");
 	printf("  <ups>		UPS identifier - <upsname>[@<hostname>[:<port>]]\n");
 	printf("  <command>	Valid instant command - test.panel.start, etc.\n");
@@ -147,7 +147,7 @@ static void do_cmd(char **argv, const int argc)
 {
 	int		cmd_complete = 0;
 	char	buf[SMALLBUF];
-	char	status_id[UUID4_LEN];
+	char	tracking_id[UUID4_LEN];
 	time_t	start, now;
 
 	if (argc > 1) {
@@ -171,16 +171,16 @@ static void do_cmd(char **argv, const int argc)
 
 	/* check for status tracking id */
 	if (
-		!status_info ||
-		/* sanity check on the size: "OK " + UUID4_LEN */
-		strlen(buf) != UUID4_LEN + 2
+		!tracking_enabled ||
+		/* sanity check on the size: "OK TRACKING " + UUID4_LEN */
+		strlen(buf) != (UUID4_LEN - 1 + strlen("OK TRACKING "))
 	) {
 		/* reply as usual */
 		fprintf(stderr, "%s\n", buf);
 		return;
 	}
 
-	snprintf(status_id, sizeof(status_id), "%s", buf + 3);
+	snprintf(tracking_id, sizeof(tracking_id), "%s", buf + strlen("OK TRACKING "));
 	time(&start);
 
 	/* send status tracking request, looping if status is PENDING */
@@ -191,7 +191,7 @@ static void do_cmd(char **argv, const int argc)
 		if (difftime(now, start) >= timeout)
 			fatalx(EXIT_FAILURE, "Can't receive status tracking information: timeout");
 
-		snprintf(buf, sizeof(buf), "GET CMDSET_STATUS %s\n", status_id);
+		snprintf(buf, sizeof(buf), "GET TRACKING %s\n", tracking_id);
 
 		if (upscli_sendline(ups, buf, strlen(buf)) < 0)
 			fatalx(EXIT_FAILURE, "Can't send status tracking request: %s", upscli_strerror(ups));
@@ -252,7 +252,7 @@ int main(int argc, char **argv)
 			break;
 
 		case 'w':
-			status_info = 1;
+			tracking_enabled = 1;
 			break;
 
 		case 'V':
@@ -371,9 +371,9 @@ int main(int argc, char **argv)
 	}
 
 	/* enable status tracking ID */
-	if (status_info) {
+	if (tracking_enabled) {
 
-		snprintf(buf, sizeof(buf), "SET CMDSET_STATUS ON\n");
+		snprintf(buf, sizeof(buf), "SET TRACKING ON\n");
 
 		if (upscli_sendline(ups, buf, strlen(buf)) < 0) {
 			fatalx(EXIT_FAILURE, "Can't enable command status tracking: %s", upscli_strerror(ups));

diff --git a/clients/upsrw.c b/clients/upsrw.c
@@ -32,8 +32,8 @@
 
 static char			*upsname = NULL, *hostname = NULL;
 static UPSCONN_t	*ups = NULL;
-static int			status_info = 0;
-static unsigned int		timeout = 10;
+static int			tracking_enabled = 0;
+static unsigned int		timeout = DEFAULT_TRACKING_TIMEOUT;
 
 struct list_t {
 	char	*name;
@@ -54,7 +54,7 @@ static void usage(const char *prog)
 	printf("  -p <password> set password for command authentication\n");
 	printf("  -w            wait for the completion of setting by the driver\n");
 	printf("                and return its actual result from the device\n");
-	printf("  -t <timeout>	set a timeout when using -w (in seconds, default \"10\")\n");
+	printf("  -t <timeout>	set a timeout when using -w (in seconds, default: %u)\n", DEFAULT_TRACKING_TIMEOUT);
 	printf("\n");
 	printf("  <ups>         UPS identifier - <upsname>[@<hostname>[:<port>]]\n");
 	printf("\n");
@@ -76,7 +76,7 @@ static void do_set(const char *varname, const char *newval)
 {
 	int		cmd_complete = 0;
 	char	buf[SMALLBUF], enc[SMALLBUF];
-	char	status_id[UUID4_LEN];
+	char	tracking_id[UUID4_LEN];
 	time_t	start, now;
 
 	snprintf(buf, sizeof(buf), "SET VAR %s %s \"%s\"\n", upsname, varname, pconf_encode(newval, enc, sizeof(enc)));
@@ -96,16 +96,16 @@ static void do_set(const char *varname, const char *newval)
 
 	/* check for status tracking id */
 	if (
-		!status_info ||
-		/* sanity check on the size: "OK " + UUID4_LEN */
-		strlen(buf) != UUID4_LEN + 2
+		!tracking_enabled ||
+		/* sanity check on the size: "OK TRACKING " + UUID4_LEN */
+		strlen(buf) != (UUID4_LEN - 1 + strlen("OK TRACKING "))
 	) {
 		/* reply as usual */
 		fprintf(stderr, "%s\n", buf);
 		return;
 	}
 
-	snprintf(status_id, sizeof(status_id), "%s", buf + 3);
+	snprintf(tracking_id, sizeof(tracking_id), "%s", buf + strlen("OK TRACKING "));
 	time(&start);
 
 	/* send status tracking request, looping if status is PENDING */
@@ -116,7 +116,7 @@ static void do_set(const char *varname, const char *newval)
 		if (difftime(now, start) >= timeout)
 			fatalx(EXIT_FAILURE, "Can't receive status tracking information: timeout");
 
-		snprintf(buf, sizeof(buf), "GET CMDSET_STATUS %s\n", status_id);
+		snprintf(buf, sizeof(buf), "GET TRACKING %s\n", tracking_id);
 
 		if (upscli_sendline(ups, buf, strlen(buf)) < 0)
 			fatalx(EXIT_FAILURE, "Can't send status tracking request: %s", upscli_strerror(ups));
@@ -227,9 +227,9 @@ static void do_setvar(const char *varname, char *uin, const char *pass)
 	}
 
 	/* enable status tracking ID */
-	if (status_info) {
+	if (tracking_enabled) {
 
-		snprintf(temp, sizeof(temp), "SET CMDSET_STATUS ON\n");
+		snprintf(temp, sizeof(temp), "SET TRACKING ON\n");
 
 		if (upscli_sendline(ups, temp, strlen(temp)) < 0) {
 			fatalx(EXIT_FAILURE, "Can't enable set variable status tracking: %s", upscli_strerror(ups));
@@ -603,7 +603,7 @@ int main(int argc, char **argv)
 			username = optarg;
 			break;
 		case 'w':
-			status_info = 1;
+			tracking_enabled = 1;
 			break;
 		case 'V':
 			printf("Network UPS Tools %s %s\n", prog, UPS_VERSION);

diff --git a/conf/upsd.conf.sample b/conf/upsd.conf.sample
@@ -22,8 +22,8 @@
 # for notifications from upsd about staleness.
 
 # =======================================================================
-# CMDSETSTATUSDELAY <seconds>
-# CMDSETSTATUSDELAY 3600
+# TRACKINGDELAY <seconds>
+# TRACKINGDELAY 3600
 #
 # This defaults to 1 hour. When instant commands and variables setting status
 # tracking is enabled, status execution information are kept during this

diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am
@@ -252,7 +252,9 @@ MAN3_DEV_PAGES = \
 	upscli_list_next.3 \
 	upscli_list_start.3 \
 	upscli_readline.3 \
+	upscli_readline_timeout.3 \
 	upscli_sendline.3 \
+	upscli_sendline_timeout.3 \
 	upscli_splitaddr.3 \
 	upscli_splitname.3 \
 	upscli_ssl.3 \
@@ -289,6 +291,12 @@ MAN3_DEV_PAGES = \
 	nutscan_get_serial_ports_list.3 \
 	nutscan_init.3
 
+upscli_readline_timeout.3: upscli_readline.3
+	touch $@
+
+upscli_sendline_timeout.3: upscli_sendline.3
+	touch $@
+
 MAN1_DEV_PAGES = \
 	libupsclient-config.1
 endif

diff --git a/docs/man/upscli_readline.txt b/docs/man/upscli_readline.txt
@@ -4,31 +4,36 @@ UPSCLI_READLINE(3)
 NAME
 ----
 
-upscli_readline - read a single response from a UPS
+upscli_readline, upscli_readline_timeout - read a single response from a UPS
 
 SYNOPSIS
 --------
 
  #include <upsclient.h>
 
  int upscli_readline(UPSCONN_t *ups, char *buf, size_t buflen);
+ int upscli_readline_timeout(UPSCONN_t *ups, char *buf, size_t buflen, unsigned int timeout);
 
 DESCRIPTION
 -----------
-The *upscli_readline()* function takes the pointer 'ups' to a
-`UPSCONN_t` state structure, receives a single line from the server, and
-copies up to 'buflen' bytes of the response into the buffer
-'buf'.
+The *upscli_readline()* and *upscli_readline_timeout()* functions take the
+pointer 'ups' to a `UPSCONN_t` state structure, receive a single line from the
+server, and copy up to 'buflen' bytes of the response into the buffer 'buf'.
 
 Some parsing of the string occurs during reception.  In particular,
 ERR messages from linkman:upsd[8] are detected and will cause this
 function to return -1.
 
+The difference between the two functions is that *upscli_readline_timeout()*
+let the caller decide the amount of time ('timeout' seconds) after which it
+should give up and return, whereas *upscli_readline()* does not offer this
+freedom.
+
 RETURN VALUE
 ------------
 
-The *upscli_readline()* function returns 0 on success, or -1 if an
-error occurs.
+The *upscli_readline()* and *upscli_readline_timeout()* functions return 0 on
+success, or -1 if an error occurs.
 
 SEE ALSO
 --------

diff --git a/docs/man/upscli_sendline.txt b/docs/man/upscli_sendline.txt
@@ -4,7 +4,7 @@ UPSCLI_SENDLINE(3)
 NAME
 ----
 
-upscli_sendline - send a single command to a UPS
+upscli_sendline, upscli_sendline_timeout - send a single command to a UPS
 
 SYNOPSIS
 --------
@@ -13,22 +13,28 @@ SYNOPSIS
  #include <upsclient.h>
 
  int upscli_sendline(UPSCONN_t *ups, const char *buf, size_t buflen);
+ int upscli_sendline_timeout(UPSCONN_t *ups, const char *buf, size_t buflen, unsigned int timeout);
 
 DESCRIPTION
 -----------
 
-The *upscli_sendline()* function takes the pointer 'ups' to a
-`UPSCONN_t` state structure and transmits a buffer 'buf' of size
-'buflen' to the server. 
+The *upscli_sendline()* and *upscli_sendline_timeout()* functions take the
+pointer 'ups' to a `UPSCONN_t` state structure and transmit a buffer 'buf' of
+size 'buflen' to the server.
 
 The data in 'buf' must be a fully formatted protocol command as no
 parsing of the buffer occurs within this function.
 
+The difference between the two functions is that *upscli_sendline_timeout()*
+let the caller decide the amount of time ('timeout' seconds) after which it
+should give up and return, whereas *upscli_sendline()* does not offer this
+freedom.
+
 RETURN VALUE
 ------------
 
-The *upscli_sendline()* function returns 0 on success, or -1 if an
-error occurs.
+The *upscli_sendline()* and *upscli_sendline_timeout()* functions return 0 on
+success, or -1 if an error occurs.
 
 SEE ALSO
 --------

diff --git a/docs/man/upscmd.txt b/docs/man/upscmd.txt
@@ -45,7 +45,7 @@ like -u, and you will be prompted for it if necessary.
 *-w*::
 Wait for the completion of command execution by the driver and return its
 actual result from the device. Note that this feature requires that upsd
-supports CMDSET_STATUS (NUT version 2.7.5 or higher) or it will otherwise fail.
+supports TRACKING (NUT version 2.7.5 or higher) or it will otherwise fail.
 The command will also block until an actual result is provided from the driver,
 or the timeout is reached (see *-t*).
 

diff --git a/docs/man/upsd.conf.txt b/docs/man/upsd.conf.txt
@@ -26,7 +26,7 @@ to make upsd wait longer.
 +
 Most users should leave this at the default value.
 
-"CMDSETSTATUSDELAY 'seconds'"::
+"TRACKINGDELAY 'seconds'"::
 
 When instant commands and variables setting status tracking is enabled, status
 execution information are kept during this amount of time, and then cleaned up.

diff --git a/docs/man/upsrw.txt b/docs/man/upsrw.txt
@@ -61,7 +61,7 @@ like -u, and you will be prompted for it if necessary.
 *-w*::
 Wait for the completion of setting execution by the driver and return its
 actual result from the device. Note that this feature requires that upsd
-supports CMDSET_STATUS (NUT version 2.7.5 or higher) or it will otherwise fail.
+supports TRACKING (NUT version 2.7.5 or higher) or it will otherwise fail.
 The command will also block until an actual result is provided from the driver,
 or the timeout is reached (see *-t*).
 

diff --git a/docs/net-protocol.txt b/docs/net-protocol.txt
@@ -45,7 +45,7 @@ NUT network protocol, over the time:
 .2+|1.2        .2+|>= 2.6.4    |Add "LIST CLIENTS" and "NETVER" commands
                                |Add ranges of values for writable variables
 .2+|1.3        .2+|>= 2.7.5    |Add "cmdparam" to "INSTCMD"
-                               |Add "CMDSET_STATUS" commands (GET, SET)
+                               |Add "TRACKING" commands (GET, SET)
 |===============================================================================
 
 NOTE: any new version of the protocol implies an update of NUT_NETVERSION
@@ -191,19 +191,19 @@ This is like DESC above, but it applies to the instant commands.
 This replaces the old "INSTCMDDESC" command.
 
 
-CMDSET_STATUS
-~~~~~~~~~~~~~
+TRACKING
+~~~~~~~~
 
 Form:
 
-	GET CMDSET_STATUS             (activation status of CMDSET_STATUS)
-	GET CMDSET_STATUS <status_id> (execution status of a command / setvar)
-	GET CMDSET_STATUS 1bd31808-cb49-4aec-9d75-d056e6f018d2
+	GET TRACKING      (activation status of TRACKING)
+	GET TRACKING <id> (execution status of a command / setvar)
+	GET TRACKING 1bd31808-cb49-4aec-9d75-d056e6f018d2
 
 Response:
 
-	ON                   (CMDSET_STATUS feature is enabled)
-	OFF                  (CMDSET_STATUS feature is disabled)
+	ON                   (TRACKING feature is enabled)
+	OFF                  (TRACKING feature is disabled)
 	PENDING              (command execution is pending)
 	SUCCESS              (command was successfully executed)
 	ERR UNKNOWN          (command execution failed with unknown error)
@@ -409,19 +409,19 @@ Form:
 
 Response:
 
-	OK                         (if CMDSET_STATUS is not enabled)
-	OK <status_id>             (if CMDSET_STATUS is enabled)
+	OK                         (if TRACKING is not enabled)
+	OK TRACKING <id>           (if TRACKING is enabled)
 	ERR <message> [<extra>...] (see Error responses)
 
 
-CMDSET_STATUS
-~~~~~~~~~~~~~
+TRACKING
+~~~~~~~~
 
 Form:
 
-	SET CMDSET_STATUS <value>
-	SET CMDSET_STATUS ON
-	SET CMDSET_STATUS OFF
+	SET TRACKING <value>
+	SET TRACKING ON
+	SET TRACKING OFF
 
 Response:
 
@@ -444,8 +444,8 @@ NOTE: <cmdparam> is an additional and optional parameter for the command.
 
 Response:
 
-	OK                         (if CMDSET_STATUS is not enabled)
-	OK <status_id>             (if CMDSET_STATUS is enabled)
+	OK                         (if TRACKING is not enabled)
+	OK TRACKING <id>           (if TRACKING is enabled)
 	ERR <message> [<extra>...] (see Error responses)