doc: be more consistent when documenting exit status

* 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.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 699948a8b0f763286a5b9dd8af036391a1f2c58e..471c50e8c30bd2206d56747916e0101b22084ce6 100644 (file)
--- 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 983940400648b6ac3ec729dfb3b06225923c751f..921d9ca3df5583595185a4cef2a7eb01f5fc4270 100644 (file)
--- 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 1bd2163da7b99ae0b060c6d7f6f92297238a7123..62bf57117680ab16c3d1a69f3819716df43c2197 100644 (file)
--- 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 55aa95a76d5d61ff597d0487be1f9accec1dc342..ce97e13dc2f067a21ff41cf9daf02003ee65ed3a 100644 (file)
--- 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 47d74dd477198667d4e24155b860b88e98f3320c..8e011ad2fe437ef55122d1671bf667ba63759abf 100644 (file)
--- 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 d82e543aae987994b1939ead490f1ef8cd56639f..b1067d2272deee9aa3600c0f823ee33217e7084c 100644 (file)
--- 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 7db64e9f1e0a99704d150511e4ae7fcaed2caa8c..cefb489c1d6486649e93c9710ad0377a94e8dd4b 100644 (file)
--- 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 b80cea3ec945ba8ef7701c72f7b4e09603a4f2fa..4d70901a3d23415b4e10a98b4ff38f9b20851fae 100644 (file)
--- 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 c63b66741553567244f5662a5ab22a9c6159a64b..db971473a55e13cbc17394ebf9aa033ff6bd26bc 100644 (file)
--- 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 06635ab3a24d9061c7f2eca53e2bf08781935b12..7c9ff98d59f9d7d2d4d30c5ac8fe863a15d3c722 100644 (file)
--- 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\