[PATCH 3/3] doc: be more consistent when documenting exit status

[Pádraig Brady]

* src/system.h (emit_exec_status): A new function to
output standard "Exit status:" info for commands that exec others.
* doc/coreutils.texi (Exit status): Add "ls" and "runcon"
to the list of commands with non standard exit status.
* src/numfmt.c (main): Call initialize_exit_failure() explicitly
to better indicate this utility may exit with something other than
EXIT_FAILURE.
* src/timeout.c (usage): Use more consistent capitalization.
* src/chroot.c: Call emit_exec_status().
* src/env.c: Likewise.
* src/nice.c: Likewise.
* src/nohup.c: Likewise.
* src/runcon.c: Likewise.
* src/stdbuf.c: Likewise.
---
 doc/coreutils.texi | 12 ++++++++----
 src/chroot.c       |  1 +
 src/env.c          |  1 +
 src/nice.c         |  1 +
 src/nohup.c        |  1 +
 src/numfmt.c       |  3 ++-
 src/runcon.c       |  1 +
 src/stdbuf.c       |  1 +
 src/system.h       | 12 ++++++++++++
 src/timeout.c      |  2 +-
 10 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 699948a8b..471c50e8c 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -827,10 +827,14 @@ requires only that it be nonzero.
 However, some of the programs documented here do produce
 other exit status values and a few associate different
 meanings with the values @samp{0} and @samp{1}.
-Here are some of the exceptions:
-@command{chroot}, @command{env}, @command{expr}, @command{nice},
-@command{nohup}, @command{numfmt}, @command{printenv}, @command{sort},
-@command{stdbuf}, @command{test}, @command{timeout}, @command{tty}.
+Here are the exceptions:
+@c You can generate the following list with:
+@c grep initialize_exit_failure src/*.c | cut -f1 -d: |
+@c sed -n 's|src/\(.*\)\.c|@command{\1},|p' | sort | fmt
+@command{chroot}, @command{env}, @command{expr}, @command{ls},
+@command{nice}, @command{nohup}, @command{numfmt}, @command{printenv},
+@command{runcon}, @command{sort}, @command{stdbuf}, @command{test},
+@command{timeout}, @command{tty}.
 
 
 @node Backup options
diff --git a/src/chroot.c b/src/chroot.c
index 983940400..921d9ca3d 100644
--- a/src/chroot.c
+++ b/src/chroot.c
@@ -210,6 +210,7 @@ Run COMMAND with root directory set to NEWROOT.\n\
 \n\
 If no command is given, run '\"$SHELL\" -i' (default: '/bin/sh -i').\n\
 "), stdout);
+      emit_exec_status (PROGRAM_NAME);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/env.c b/src/env.c
index 1bd2163da..62bf57117 100644
--- a/src/env.c
+++ b/src/env.c
@@ -160,6 +160,7 @@ SIG may be a signal name like 'PIPE', or a signal number 
like '13'.\n\
 Without SIG, all known signals are included.  Multiple signals can be\n\
 comma-separated.  An empty SIG argument is a no-op.\n\
 "), stdout);
+      emit_exec_status (PROGRAM_NAME);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/nice.c b/src/nice.c
index 55aa95a76..ce97e13dc 100644
--- a/src/nice.c
+++ b/src/nice.c
@@ -86,6 +86,7 @@ With no COMMAND, print the current niceness.  Niceness values 
range from\n\
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
+      emit_exec_status (PROGRAM_NAME);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/nohup.c b/src/nohup.c
index 47d74dd47..8e011ad2f 100644
--- a/src/nohup.c
+++ b/src/nohup.c
@@ -67,6 +67,7 @@ If standard error is a terminal, redirect it to standard 
output.\n\
 To save output to FILE, use '%s COMMAND > FILE'.\n"),
               program_name);
       printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
+      emit_exec_status (PROGRAM_NAME);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/numfmt.c b/src/numfmt.c
index d82e543aa..b1067d227 100644
--- a/src/numfmt.c
+++ b/src/numfmt.c
@@ -42,7 +42,7 @@
 #define AUTHORS proper_name ("Assaf Gordon")
 
 /* Exit code when some numbers fail to convert.  */
-enum { EXIT_CONVERSION_WARNINGS = 2 };
+enum { TIMEOUT_FAILURE = 1, EXIT_CONVERSION_WARNINGS = 2 };
 
 enum
 {
@@ -1459,6 +1459,7 @@ main (int argc, char **argv)
     decimal_point = ".";
   decimal_point_length = strlen (decimal_point);
 
+  initialize_exit_failure (TIMEOUT_FAILURE);
   atexit (close_stdout);
 
   while (true)
diff --git a/src/runcon.c b/src/runcon.c
index 7db64e9f1..cefb489c1 100644
--- a/src/runcon.c
+++ b/src/runcon.c
@@ -96,6 +96,7 @@ With neither CONTEXT nor COMMAND, print the current security 
context.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
+      emit_exec_status (PROGRAM_NAME);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/stdbuf.c b/src/stdbuf.c
index b80cea3ec..4d70901a3 100644
--- a/src/stdbuf.c
+++ b/src/stdbuf.c
@@ -121,6 +121,7 @@ for example) then that will override corresponding changes 
by 'stdbuf'.\n\
 Also some filters (like 'dd' and 'cat' etc.) don't use streams for I/O,\n\
 and are thus unaffected by 'stdbuf' settings.\n\
 "), stdout);
+      emit_exec_status (PROGRAM_NAME);
       emit_ancillary_info (PROGRAM_NAME);
     }
   exit (status);
diff --git a/src/system.h b/src/system.h
index c63b66741..db971473a 100644
--- a/src/system.h
+++ b/src/system.h
@@ -626,6 +626,18 @@ the VERSION_CONTROL environment variable.  Here are the 
values:\n\
 "), stdout);
 }
 
+static inline void
+emit_exec_status (char const *program)
+{
+      printf (_("\n\
+Exit status:\n\
+  125  if the %s command itself fails\n\
+  126  if COMMAND is found but cannot be invoked\n\
+  127  if COMMAND cannot be found\n\
+  -    the exit status of COMMAND otherwise\n\
+"), program);
+}
+
 static inline void
 emit_ancillary_info (char const *program)
 {
diff --git a/src/timeout.c b/src/timeout.c
index 06635ab3a..7c9ff98d5 100644
--- a/src/timeout.c
+++ b/src/timeout.c
@@ -299,7 +299,7 @@ It may be necessary to use the KILL signal, since this 
signal can't be caught.\
 \n"), stdout);
 
       fputs (_("\n\
-EXIT status:\n\
+Exit status:\n\
   124  if COMMAND times out, and --preserve-status is not specified\n\
   125  if the timeout command itself fails\n\
   126  if COMMAND is found but cannot be invoked\n\
-- 
2.26.2