From: Pádraig Brady Date: Tue, 27 Sep 2022 20:59:01 +0000 (+0100) Subject: doc: be more consistent when documenting exit status X-Git-Tag: v9.2~125 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8aa3b82ea1a9751f2a76d47c0c4d1d611273ab8b;p=thirdparty%2Fcoreutils.git 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 699948a8b0..471c50e8c3 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 9839404006..921d9ca3df 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 1bd2163da7..62bf571176 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 55aa95a76d..ce97e13dc2 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 47d74dd477..8e011ad2fe 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 d82e543aae..b1067d2272 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 7db64e9f1e..cefb489c1d 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 b80cea3ec9..4d70901a3d 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 c63b667415..db971473a5 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 06635ab3a2..7c9ff98d59 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\