include/common.h, docs/new-drivers.txt, NEWS.adoc: define common EF_E…

…XIT_FAILURE and EF_EXIT_SUCCESS for set_exit_flag(int) methods [networkupstools#2670]

Signed-off-by: Jim Klimov <[email protected]>

NEWS.adoc

@@ -363,6 +363,8 @@ INSTCMD such as `shutdown.return`, `shutdown.stayoff` or `load.off`. [#2670]
      `gcc-13`+ whose static analyzers on NUT CI farm complained about some
      imperfections after adding newer OS revisions to the population of
      build agents. [#2585, #2588]
+   * defined `EF_EXIT_SUCCESS` and `EF_EXIT_FAILURE` in `include/common.h`
+     to avoid magic numbers in code like `set_exit_flag(-2)`. [#2670]
 
  - updated `docs/nut-names.txt` with items defined by 42ITy NUT fork. [#2339]
 

docs/new-drivers.txt

@@ -162,9 +162,10 @@ process.
 This method should not directly `exit()` the driver program (neither
 should it call `fatalx()` nor `fatal_with_errno()` methods).  It can
 `upslogx(LOG_ERR, ...)` or `upslog_with_errno(LOG_ERR, ...)`, and then
-`set_exit_flag(N)` if required (`-1` for `EXIT_FAILURE` and `-2` for
-`EXIT_SUCCESS` which would be handled in the standard driver loop or
-`forceshutdown()` method of `main.c`).
+`set_exit_flag(N)` if required, using values `EF_EXIT_FAILURE` (`-1`)
+for eventual `exit(EXIT_FAILURE)` and `EF_EXIT_SUCCESS` (`-2`) for
+`exit(EXIT_SUCCESS)`, which would be handled in the standard driver
+loop or in `forceshutdown()` method of `main.c`.
 
 Data types
 ----------

include/common.h

@@ -560,6 +560,15 @@ extern int optind;
 #	define setegid(x) setresgid(-1,x,-1)    /* Works for HP-UX 10.20 */
 #endif
 
+/* Several NUT programs define their set_exit_flag(int) methods
+ * which accept a signal code or similar parameter. Commonly they
+ * also accept a few negative values summarized below, to just
+ * exit (typically after completing a processing loop) with one
+ * of C standard exit codes.
+ */
+#define EF_EXIT_FAILURE	-1	/* eventually exit(EXIT_FAILURE); */
+#define EF_EXIT_SUCCESS	-2	/* eventually exit(EXIT_SUCCESS); */
+
 #ifdef WIN32
 /* FIXME : this might not be the optimal mapping between syslog and ReportEvent*/
 #define LOG_ERR 	EVENTLOG_ERROR_TYPE