Support envvar for ALTPIDPATH with documentation

common/common.c

@@ -374,19 +374,35 @@ const char * dflt_statepath(void)
 {
 	const char * path;
 
-	if ((path = getenv("NUT_STATEPATH")) == NULL)
+	path = getenv("NUT_STATEPATH");
+	if ( (path == NULL) || (*path == '\0') )
 		path = STATEPATH;
 
 	return path;
 }
 
-/* Return the alternate path for pid files */
+/* Return the alternate path for pid files, for processes running as non-root
+ * Per documentation and configure script, the fallback value is the
+ * state-file path as the daemon and drivers can write there too.
+ * Note that this differs from PIDPATH that higher-privileged daemons, such
+ * as upsmon, tend to use.
+ */
 const char * altpidpath(void)
 {
+	const char * path;
+
+	path = getenv("NUT_ALTPIDPATH");
+	if ( (path == NULL) || (*path == '\0') )
+		path = getenv("NUT_STATEPATH");
+
+	if ( (path != NULL) && (*path != '\0') )
+		return path;
+
 #ifdef ALTPIDPATH
 	return ALTPIDPATH;
 #else
-	return dflt_statepath();
+/* We assume, here and elsewhere, that at least STATEPATH is always defined */
+	return STATEPATH;
 #endif
 }
 

docs/configure.txt

@@ -364,6 +364,8 @@ Programs that normally don't have root powers, like the drivers and
 upsd, write their pid files here.  By default this is whatever the
 statepath is, as those programs should be able to write there.
 
+The NUT_ALTPIDPATH environment variable overrides this at run time.
+
 	--with-statepath=PATH
 
 Change the default location of the state sockets created by the

docs/man/nutupsdrv.txt

@@ -148,6 +148,23 @@ ups.conf::
 Required configuration file.  This contains all details on which drivers
 to start and where the hardware is attached.
 
+ENVIRONMENT VARIABLES
+---------------------
+
+*NUT_CONFPATH* is the path name of the directory that contains
+`upsd.conf` and other configuration files.  If this variable is not set,
+*upsd* uses a built-in default, which is often `/usr/local/ups/etc`.
+
+*NUT_STATEPATH* is the path name of the directory in which
+*upsd* keeps state information.  If this variable is not set,
+*upsd* uses a built-in default, which is often `/var/state/ups`.
+The *STATEPATH* directive in linkman:upsd.conf[5] overrides this variable.
+
+*NUT_ALTPIDPATH* is the path name of the directory in which
+*upsd* and drivers store .pid files.  If this variable is not set,
+*upsd* and drivers use either *NUT_STATEPATH* if set, or ALTPIDPATH if set,
+or otherwise the built-in default *STATEPATH*.
+
 BUGS
 ----
 

docs/man/upsd.txt

@@ -126,11 +126,16 @@ ENVIRONMENT VARIABLES
 `upsd.conf` and other configuration files.  If this variable is not set,
 *upsd* uses a built-in default, which is often `/usr/local/ups/etc`.
 
-*NUT_STATEPATH* is the path name of the directory in which 
+*NUT_STATEPATH* is the path name of the directory in which
 *upsd* keeps state information.  If this variable is not set,
 *upsd* uses a built-in default, which is often `/var/state/ups`.
 The *STATEPATH* directive in linkman:upsd.conf[5] overrides this variable.
 
+*NUT_ALTPIDPATH* is the path name of the directory in which
+*upsd* and drivers store .pid files.  If this variable is not set,
+*upsd* and drivers use either *NUT_STATEPATH* if set, or ALTPIDPATH if set,
+or otherwise the built-in default *STATEPATH*.
+
 SEE ALSO
 --------
 

drivers/main.c

@@ -98,7 +98,11 @@ static void help_msg(void)
 
 	printf("  -s <id>        - configure directly from cmd line arguments\n");
 	printf("                 - note: must specify all driver parameters with successive -x\n");
-	printf("                 - note: at least 'port' variable should be set\n\n");
+	printf("                 - note: at least 'port' variable should be set\n");
+	printf("                 - note: to explore the current values on a device from an\n");
+	printf("                   unprivileged user account (with sufficient media access in\n");
+	printf("                   the OS - e.g. to query networked devices), you can specify\n");
+	printf("                   '-d 1' argument and `export NUT_STATEPATH=/tmp` beforehand\n\n");
 
 	printf("  -V             - print version, then exit\n");
 	printf("  -L             - print parseable list of driver variables\n");