Merge branch 'master' into libusb-1.0+0.1

Closes: #300

Notable commits from master:

 * Documentation
 * statepath environment variables (#473 / #507)
 * nut-scanner (issue #500 / pull #502)
 * Fix one parallel build problem (#418)
 * Compute output load if not provided (#484)

Makefile.am

@@ -23,6 +23,7 @@ DISTCHECK_VALGRIND_FLAGS = --with-all=auto --with-ssl=auto --with-doc=skip --wit
 
 DISTCHECK_CONFIGURE_FLAGS = ${DISTCHECK_FLAGS}		\
  --with-systemdsystemunitdir='$${prefix}/lib/systemd/system' \
+ --with-systemdshutdowndir='$${prefix}/lib/systemd/system-shutdown' \
  --with-augeas-lenses-dir='$${prefix}/usr/share/augeas/lenses'		\
  --with-hotplug-dir='$${prefix}/etc/hotplug'		\
  --with-udev-dir='$${prefix}/etc/udev'			\

common/common.c

@@ -369,19 +369,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
 }
 

configure.ac

@@ -104,10 +104,12 @@ AC_CONFIG_LIBOBJ_DIR([common])
 dnl +-------------------------------------------------------------------
 
 AC_PROG_CC
+AC_PROG_CC_C99
 dnl Needed for per-target flags
 AM_PROG_CC_C_O
 AC_PROG_CPP
 AC_PROG_CXX
+AC_PROG_CXX_C_O
 AC_PROG_INSTALL
 AC_PROG_MKDIR_P
 AC_PROG_LN_S
@@ -155,18 +157,6 @@ AC_CHECK_FUNCS(vsnprintf snprintf, [], [
 AC_REPLACE_FUNCS(setenv strerror atexit)
 
 
-dnl
-dnl Tests for CppUnit availability and usability
-dnl Using CppUnit implies C++ support!
-dnl Theoretically, libcppunit-dev will pull up to g++, through libstdc++...
-dnl AM_PATH_CPPUNIT(1.9.6)
-
-PKG_CHECK_MODULES(CPPUNIT, cppunit, have_cppunit=yes, have_cppunit=no)
-if test "${have_cppunit}" != "yes" ; then
-	AC_MSG_WARN([libcppunit not found.])
-fi
-AM_CONDITIONAL(HAVE_CPPUNIT, test "${have_cppunit}" = "yes")
-
 dnl
 dnl Only use these when compiling with gcc
 dnl
@@ -1215,16 +1205,81 @@ AC_ARG_WITH([systemdsystemunitdir],
 		;;
 	esac
 ], [])
-dnl Override installation directory, with the local installation
-dnl prefix. This is needed for 'distcheck*' targets, otherwise
-dnl files will try to get intalled to the actual system directories
 if test -n "${systemdsystemunitdir}"; then
-	systemdsystemshutdowndir="${libdir}/systemd/system-shutdown"
 	AC_MSG_RESULT(using ${systemdsystemunitdir})
 else
 	AC_MSG_RESULT(no)
 fi
 AM_CONDITIONAL(HAVE_SYSTEMD, test "$systemdsystemunitdir" != "")
+dnl This option is only provided so that make distcheck can override it,
+dnl otherwise we ask pkg-config whenever --with-systemdsystemunitdir is
+dnl given
+AC_ARG_WITH([systemdshutdowndir],
+	AS_HELP_STRING([--with-systemdshutdowndir=DIR], [Directory for systemd shutdown scripts (auto)]),
+	[systemdshutdowndir=${withval}])
+if test -n "${systemdsystemunitdir}"; then
+	case "${systemdshutdowndir}" in
+	yes|auto|"")
+		systemdshutdowndir=`$PKG_CONFIG --variable=systemdshutdowndir systemd`
+	esac
+fi
+
+dnl
+dnl Tests for CppUnit availability and usability (will be built if we can,
+dnl and if valgrind is enabled for this configuration - reported below).
+dnl Using CppUnit implies C++ support!
+dnl Theoretically, libcppunit-dev will pull up to g++, through libstdc++...
+dnl AM_PATH_CPPUNIT(1.9.6)
+
+dnl # Tests with gcc-4.8 require this C++11 option to be provided explicitly
+dnl # gcc-4.6 does not support this yet; newer gcc's should be ok by default.
+dnl # Could use `AX_CXX_COMPILE_STDCXX_11([noext], [optional])` if it were
+dnl # available everywhere. Or AX_CHECK_COMPILE_FLAG if it was ubiquitous:
+dnl ###AX_CHECK_COMPILE_FLAG([-std=c++11],
+dnl ###    [CXXFLAGS="$CXXFLAGS -std=c++11"
+dnl ###     HAVE_CXX11=1],
+dnl ###    [HAVE_CXX11=0])
+
+AC_MSG_CHECKING(for C++11 support in current compiler)
+my_CXXFLAGS="$CXXFLAGS"
+AC_LANG_PUSH([C++])
+
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[
+#include <stdio.h>
+#if __cplusplus < 201103L
+  #error This library needs at least a C++11 compliant compiler
+#endif
+]], [[printf("%ld\n", __cplusplus);]])
+],
+    [AC_MSG_RESULT([yes, out of the box])
+     HAVE_CXX11=1],
+    [CXXFLAGS="$CXXFLAGS -std=c++11"
+     AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[
+#include <stdio.h>
+#if __cplusplus < 201103L
+  #error This library needs at least a C++11 compliant compiler
+#endif
+        ]], [[printf("%ld\n", __cplusplus);]])
+        ],
+        [AC_MSG_RESULT([yes, GCC-style])
+         HAVE_CXX11=1],
+            [AC_MSG_RESULT([no])
+             CXXFLAGS="$my_CXXFLAGS"
+             HAVE_CXX11=0])])
+AC_LANG_POP([C++])
+
+have_cppunit="no"
+CPPUNIT_NUT_CXXFLAGS=""
+AS_IF([test "${HAVE_CXX11}" = 1],
+    [PKG_CHECK_MODULES(CPPUNIT, cppunit, have_cppunit=yes, have_cppunit=no)
+     if test "${have_cppunit}" != "yes" ; then
+        AC_MSG_WARN([libcppunit not found - those C++ tests will not be built.])
+     else
+     AS_IF([test -n "$CXX"],[AS_IF([$CXX --version 2>&1 | grep 'Free Software Foundation' > /dev/null],
+        [CPPUNIT_NUT_CXXFLAGS="-g -O0"])])
+     fi])
+AM_CONDITIONAL(HAVE_CPPUNIT, test "${have_cppunit}" = "yes")
+AC_DEFINE_UNQUOTED(CPPUNIT_NUT_CXXFLAGS, $CPPUNIT_NUT_CXXFLAGS, [Compiler flags for cppunit tests])
 
 AC_MSG_CHECKING(whether to install Augeas configuration-management lenses)
 AC_ARG_WITH(augeas-lenses-dir,
@@ -1397,6 +1452,13 @@ fi
 AM_CONDITIONAL([HAVE_VALGRIND], [test "x${VALGRIND}" != "xnone"])
 AM_CONDITIONAL([WITH_VALGRIND], [test "x${with_valgrind}" = "xyes"])
 
+AC_MSG_CHECKING([whether to build cppunit tests using valgrind support])
+if test "x${with_valgrind}" = xyes && test "x${have_cppunit}" = xyes ; then
+	AC_MSG_RESULT(yes)
+else
+	AC_MSG_RESULT(no)
+fi
+
 dnl expand ${sysconfdir} and write it out
 conftemp="${sysconfdir}"
 eval conftemp=\"${conftemp}\"
@@ -1536,7 +1598,7 @@ AC_SUBST(driverexecdir)
 AC_SUBST(htmldir)
 AC_SUBST(pkgconfigdir)
 AC_SUBST(systemdsystemunitdir)
-AC_SUBST(systemdsystemshutdowndir)
+AC_SUBST(systemdshutdowndir)
 AC_SUBST(auglensdir)
 AC_SUBST(hotplugdir)
 AC_SUBST(udevdir)

data/driver.list.in

@@ -295,6 +295,7 @@
 "Eaton"	"ups"	"5"	"5SC"	"USB port"	"usbhid-ups"
 "Eaton"	"ups"	"5"	"5P"	"USB port"	"usbhid-ups"
 "Eaton"	"ups"	"5"	"9SX"	"USB port"	"usbhid-ups"
+"Eaton"	"ups"	"5"	"9PX"	"USB port"	"usbhid-ups"
 "Eaton"	"ups"	"5"	"9PX Split Phase 6/8/10 kVA"	"USB port"	"usbhid-ups"
 "Eaton"	"ups"	"5"	"Ellipse ASR USBS 600/750/1000/1500 VA"	"Serial cable"	"mge-shut"
 "Eaton"	"ups"	"5"	"Ellipse MAX USBS 600/850/1100/1500 VA"	"Serial cable"	"mge-shut"
@@ -310,7 +311,9 @@
 "Eaton"	"ups"	"5"	"5SC"	"Serial port"	"mge-shut"
 "Eaton"	"ups"	"5"	"5P"	"Serial port"	"mge-shut"
 "Eaton"	"ups"	"5"	"9SX"	"Serial port"	"mge-shut"
+"Eaton"	"ups"	"5"	"9PX"	"Serial port"	"mge-shut"
 "Eaton"	"ups"	"5"	"9PX Split Phase 6/8/10 kVA"	"Serial port"	"mge-shut"
+"Eaton"	"ups"	"5"	"9PX"	"SNMP/Web card"	"netxml-ups"
 "Eaton"	"ups"	"5"	"9PX Split Phase 6/8/10 kVA"	"SNMP/Web card"	"netxml-ups"
 "Eaton"	"ups"	"5"	"EX RT (XML/HTTP)"	"NMC Transverse card (ref 66074)"	"netxml-ups (experimental)"
 "Eaton"	"ups"	"5"	"EX RT (SNMP)"	"NMC Transverse card (ref 66074)"	"snmp-ups (experimental)"
@@ -338,6 +341,7 @@
 "Eaton"	"ups"	"5"	"ConnectUPS X / BD / E Slot"	"Network port"	"snmp-ups"
 "Eaton"	"ups"	"5"	"Management Card Contact"	"Config 3 - Cable 66033"	"genericups upstype=7"
 "Eaton"	"ats"	"5"	"Eaton ATS16"	""	"snmp-ups"
+"Eaton"	"ats"	"5"	"Eaton ATS30"	""	"snmp-ups"
 
 "Effekta"	"ups"	"2"	"MI/MT/MH"	"2502 cable"	"blazer_ser"
 "Effekta"	"ups"	"2"	"RM2000MH"	""	"blazer_ser"

docs/configure.txt

@@ -362,6 +362,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/hid-subdrivers.txt

@@ -9,9 +9,9 @@ different classes (audio, imaging, mass storage etc). Almost all UPS
 devices belong to the "HID" class, which means "Human Interface
 Device", and also includes things like keyboards and mice. What HID
 devices have in common is a particular (and very flexible) interface
-for reading and writing information (such as x/y coordinates and
-button states, in case of a mouse, or voltages and status information,
-in case of a UPS).
+for reading and writing information (such as X/Y coordinates and
+button states, in the case of a mouse, or voltages and status information,
+in the case of a UPS).
 
 The NUT "usbhid-ups" driver is a meta-driver that handles all HID UPS
 devices. It consists of a core driver that handles most of the work of
@@ -20,13 +20,14 @@ specific UPS manufacturers (MGE, APC, and Belkin are currently
 supported).  Adding support for a new HID UPS device is easy, because
 it requires only the creation of a new sub-driver.
 
-There are a few USB UPS devices that are not HID devices. These
+There are a few USB UPS devices that are not true HID devices. These
 devices typically implement some version of the manufacturer's serial
 protocol over USB (which is a really dumb idea, by the way). An
-example is the Tripplite USB. Such devices are *not* supported by the
-usbhid-ups driver, and are not covered in this document. If you need to
-add support for such a device, read new-drivers.txt and see the
-tripplite_usb driver for inspiration.
+example is the original Tripplite USB interface (USB idProduct = 0001). Its HID
+descriptor is only 52 bytes long (compared to several hundred bytes for a true
+PDC HID UPS).  Such devices are *not* supported by the usbhid-ups driver, and
+are not covered in this document. If you need to add support for such a device,
+read new-drivers.txt and see the "tripplite_usb" driver for inspiration.
 
 HID Usage Tree
 ~~~~~~~~~~~~~~
@@ -132,20 +133,22 @@ Writing a subdriver
 In preparation for writing a subdriver for a device that is currently
 unsupported, run usbhid-ups with the following command line:
 
- drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX auto
+ drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX -x port=auto -s ups
 
 (substitute your device's 4-digit VendorID instead of "XXXX"). 
 This will produce a bunch of debugging information, including a number 
 of lines starting with "Path:" that describe the device's usage tree. 
 This information forms the initial basis for a new subdriver. 
 
 You should save this information to a file, e.g. 
- drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX auto >& /tmp/info
+
+ drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX \
+   -x port=auto -s ups 2>&1 | tee /tmp/info
 
 You can create an initial "stub" subdriver for your device by using
 script scripts/subdriver/gen-usbhid-subdriver.sh. Note: this only creates
 a "stub" and needs to be further customized to be useful (see
-CUSTOMIZATION below).
+"Customization" below).
 
 Use the script as follows:
 
@@ -160,22 +163,26 @@ and digits, and use natural capitalization such as "Belkin" (not
 information.
 
 You should put the generated files into the drivers/ subdirectory, and
-update usbhid-ups.c by adding the appropriate #include line and by
-updating the definition of subdriver_list in usbhid-ups.c. You must
-also add the subdriver to USBHID_UPS_SUBDRIVERS in drivers/Makefile.am
-and call "autoreconf" and/or "./configure" from the top level NUT directory.
-You can then recompile usbhid-ups, and start experimenting with the new
+update `usbhid-ups.c` by adding the appropriate `#include` line and by
+updating the definition of `subdriver_list` in `usbhid-ups.c`. You must
+also add the subdriver to USBHID_UPS_SUBDRIVERS in `drivers/Makefile.am`
+and call `autoreconf` and/or `./configure` from the top-level NUT directory.
+You can then recompile `usbhid-ups`, and start experimenting with the new
 subdriver.
 
-CUSTOMIZATION: The initially generated subdriver code is only a stub,
+
+Customization
+~~~~~~~~~~~~~
+
+The initially generated subdriver code is only a stub,
 and will not implement any useful functionality (in particular, it
 will be unable to shut down the UPS). In the beginning, it simply
 attempts to monitor some UPS variables. To make this driver useful,
 you must examine the NUT variables of the form "unmapped.*" in the
 hid_info_t data structure, and map them to actual NUT variables and
 instant commands. There are currently no step-by-step instructions for
 how to do this. Please look at the files to see how the currently implemented
-subdrivers are written.:
+subdrivers are written:
 
 - apc-hid.c/h
 - belkin-hid.c/h

docs/man/Makefile.am

@@ -176,6 +176,15 @@ SRC_DEV_PAGES = \
 
 if WITH_MANS
 # NOTE: nutclient_*.3 has no source counterpart (libnutclient_*.txt)
+
+LIBNUTCLIENT_MISC_DEPS=
+	nutclient_authenticate.3 \
+	nutclient_logout.3 \
+	nutclient_device_login.3 \
+	nutclient_get_device_num_logins.3 \
+	nutclient_device_master.3 \
+	nutclient_device_forced_shutdown.3
+
 MAN3_DEV_PAGES = \
 	upsclient.3 \
 	upscli_add_host_cert.3 \
@@ -201,16 +210,12 @@ MAN3_DEV_PAGES = \
 	libnutclient_misc.3 \
 	libnutclient_tcp.3 \
 	libnutclient_variables.3 \
-	nutclient_authenticate.3 \
+	$(LIBNUTCLIENT_MISC_DEPS)
 	nutclient_destroy.3 \
-	nutclient_device_forced_shutdown.3 \
-	nutclient_device_login.3 \
-	nutclient_device_master.3 \
 	nutclient_execute_device_command.3 \
 	nutclient_get_device_command_description.3 \
 	nutclient_get_device_commands.3 \
 	nutclient_get_device_description.3 \
-	nutclient_get_device_num_logins.3 \
 	nutclient_get_device_rw_variables.3 \
 	nutclient_get_devices.3 \
 	nutclient_get_device_variable_description.3 \
@@ -219,7 +224,6 @@ MAN3_DEV_PAGES = \
 	nutclient_has_device.3 \
 	nutclient_has_device_command.3 \
 	nutclient_has_device_variable.3 \
-	nutclient_logout.3 \
 	nutclient_set_device_variable_value.3 \
 	nutclient_set_device_variable_values.3 \
 	nutclient_tcp_create_client.3 \
@@ -246,6 +250,9 @@ MAN3_DEV_PAGES = \
 	nutscan_get_serial_ports_list.3 \
 	nutscan_init.3
 
+$(LIBNUTCLIENT_MISC_DEPS): libnutclient_misc.3
+	touch $@
+
 MAN1_DEV_PAGES = \
 	libupsclient-config.1
 endif

docs/man/belkin.txt

@@ -20,6 +20,10 @@ Other similar models such as the 425 and 625 should also work.
 
 The Trust UPS and older Belkin units are not supported.
 
+This driver only supports serial connections. If your UPS has a USB port,
+please consult the Hardware Compatibility List (HCL) to see which of the USB
+drivers you should use.
+
 EXTRA ARGUMENTS
 ---------------
 
@@ -44,6 +48,13 @@ The core driver:
 ~~~~~~~~~~~~~~~~
 linkman:nutupsdrv[8]
 
+Other Belkin drivers:
+~~~~~~~~~~~~~~~~~~~~~
+linkman:belkinunv[8],
+linkman:blazer_ser[8],
+linkman:blazer_usb[8],
+linkman:usbhid-ups[8]
+
 Internet resources:
 ~~~~~~~~~~~~~~~~~~~
 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/