summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJim Meyering <jim@meyering.net>2004-01-22 22:13:27 +0000
committerJim Meyering <jim@meyering.net>2004-01-22 22:13:27 +0000
commit6f8f6eaf4383419c753c85b48e8bb6f2a458177b (patch)
tree6e384fecadebcb02c468112deca4df723ecf48ad /doc
parent3a829a54c2503d3caa76b355a0eb049e09b71702 (diff)
downloadcoreutils-6f8f6eaf4383419c753c85b48e8bb6f2a458177b.tar.xz
(Exit status): Document that ordinary failure
might not exit with status 1 on unusual platforms. Mention chroot, env, nice, and su as having unusual exit status patterns. Don't bother to mention true and false since their exit status patterns are actually normal. (sort invocation, su invocation): Mention its unusual exit status pattern. (chroot invocation): Simplify description of exit status 1. Remove duplicate description of status 127. (env invocation): Use consistent tenses; simplifiy description of status 1. (nice invocation): Likewise.
Diffstat (limited to 'doc')
-rw-r--r--doc/coreutils.texi47
1 files changed, 32 insertions, 15 deletions
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index aace0f88f..6980fcea6 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -122,7 +122,7 @@
This manual documents version @value{VERSION} of the @sc{gnu} core
utilities, including the standard programs for text and file manipulation.
-Copyright @copyright{} 1994, 1995, 1996, 2000, 2001, 2002, 2003
+Copyright @copyright{} 1994, 1995, 1996, 2000, 2001, 2002, 2003, 2004
Free Software Foundation, Inc.
@quotation
@@ -632,19 +632,23 @@ context that requires a file name.
@macro exitstatus
An exit status of zero indicates success,
-and a value of @samp{1} indicates failure.
+and a nonzero value indicates failure.
@end macro
Nearly every command invocation yields an integral @dfn{exit status}
that can be used to change how other commands work.
For the vast majority of commands, an exit status of zero indicates
-success, and a value of @samp{1} indicates failure.
+success. Failure is indicated by a nonzero value---typically
+@samp{1}, though it may differ on unusual platforms as @acronym{POSIX}
+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{expr}, @command{false}, @command{nohup}, @command{printenv},
-@command{sort}, @command{test}, @command{true}, @command{tty}.
+@command{chroot}, @command{env}, @command{expr},
+@command{nice}, @command{nohup}, @command{printenv},
+@command{sort}, @command{su}, @command{test}, @command{tty}.
@node Backup options
@@ -3069,7 +3073,14 @@ In addition, if the final byte of an input file is not a newline, @sc{gnu}
@command{sort} silently supplies one. A line's trailing newline is not
part of the line for comparison purposes.
-Upon any error, @command{sort} exits with a status of @samp{2}.
+@cindex exit status of @command{sort}
+Exit status:
+
+@display
+0 if no error occurred
+1 if invoked with @option{-c} and the input is not properly sorted
+2 if an error occurred
+@end display
@vindex TMPDIR
If the environment variable @env{TMPDIR} is set, @command{sort} uses its
@@ -11529,11 +11540,9 @@ device files), copy them into place, too.
Exit status:
@display
-1 if there are invalid options, if the chroot syscall fails,
- or if the subsequent @samp{chdir ("/")} fails
+1 if @command{chroot} itself fails
126 if @var{command} is found but cannot be invoked
127 if @var{command} cannot be found
-127 if @var{command} cannot be found
the exit status of @var{command} otherwise
@end display
@@ -11595,9 +11604,8 @@ Start with an empty environment, ignoring the inherited environment.
Exit status:
@display
-0 if no @var{command} was specified and the environment was output
-1 if no @var{command} was specified and there was a write error while
- printing the environment
+0 if no @var{command} is specified and the environment is output
+1 if @command{env} itself fails
126 if @var{command} is found but cannot be invoked
127 if @var{command} cannot be found
the exit status of @var{command} otherwise
@@ -11654,9 +11662,8 @@ instead.
Exit status:
@display
-0 if no @var{command} was specified and the current priority was output
-1 if there are invalid options or if no @var{command} was specified and
- there was a write error
+0 if no @var{command} is specified and the current priority is output
+1 if @command{nice} itself fails
126 if @var{command} is found but cannot be invoked
127 if @var{command} cannot be found
the exit status of @var{command} otherwise
@@ -11835,6 +11842,16 @@ shell is restricted (see @option{-m} just above).
@end table
+@cindex exit status of @command{su}
+Exit status:
+
+@display
+1 if @command{su} itself fails
+126 if subshell is found but cannot be invoked
+127 if subshell cannot be found
+the exit status of the subshell otherwise
+@end display
+
@cindex wheel group, not supported
@cindex group wheel, not supported
@cindex fascism