diff options
| -rw-r--r-- | doc/coreutils.texi | 199 |
1 files changed, 194 insertions, 5 deletions
diff --git a/doc/coreutils.texi b/doc/coreutils.texi index b3232181c..dacaa17e8 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -559,6 +559,11 @@ context that requires a file name. @node Exit status @section Exit status +@macro exitstatus +An exit status of zero indicates success, +and a value of @samp{1} 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 @@ -1130,6 +1135,8 @@ characters at the end of each line are also visible. @end table +@exitstatus + @node tac invocation @section @command{tac}: Concatenate and write files in reverse @@ -1177,6 +1184,8 @@ Use @var{separator} as the record separator, instead of newline. @end table +@exitstatus + @node nl invocation @section @command{nl}: Number lines and write files @@ -1336,6 +1345,8 @@ Use @var{number} characters for line numbers (default 6). @end table +@exitstatus + @node od invocation @section @command{od}: Write files in octal or other formats @@ -1583,6 +1594,8 @@ address. @end table +@exitstatus + @node Formatting file contents @chapter Formatting file contents @@ -1693,6 +1706,8 @@ leaving the code unchanged. @end table +@exitstatus + @node pr invocation @section @command{pr}: Paginate or columnate files for printing @@ -2062,6 +2077,8 @@ line is never truncated. @end table +@exitstatus + @node fold invocation @section @command{fold}: Wrap input lines to fit in specified width @@ -2119,6 +2136,8 @@ instead. @end table +@exitstatus + @node Output of parts of files @chapter Output of parts of files @@ -2204,6 +2223,9 @@ by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @code{-c}, or @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not allow this; use @option{-c @var{count}} or @option{-n @var{count}} instead. +@exitstatus + + @node tail invocation @section @command{tail}: Output the last part of files @@ -2381,6 +2403,9 @@ an obsolete option @option{+@var{count}} with the same meaning as conformance}) does not allow these options; use @option{-c @var{count}} or @option{-n @var{count}} instead. +@exitstatus + + @node split invocation @section @command{split}: Split a file into fixed-size pieces @@ -2460,6 +2485,8 @@ Write a diagnostic to standard error just before each output file is opened. @end table +@exitstatus + @node csplit invocation @section @command{csplit}: Split a file into context-determined pieces @@ -2589,6 +2616,8 @@ Do not print counts of output file sizes. @end table +@exitstatus + @node Summarizing files @chapter Summarizing files @@ -2687,6 +2716,8 @@ Print only the maximum line lengths. @end table +@exitstatus + @node sum invocation @section @command{sum}: Print checksum and block counts @@ -2736,6 +2767,8 @@ Compute checksums using an algorithm compatible with System V @command{sum} is provided for compatibility; the @command{cksum} program (see next section) is preferable in new applications. +@exitstatus + @node cksum invocation @section @command{cksum}: Print CRC checksum and byte counts @@ -2768,6 +2801,8 @@ previous section); it is more robust. The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node md5sum invocation @section @command{md5sum}: Print or check message-digests @@ -2864,6 +2899,8 @@ are valid. @end table +@exitstatus + @node Operating on sorted files @chapter Operating on sorted files @@ -3494,6 +3531,8 @@ compared. @end table +@exitstatus + @node comm invocation @section @command{comm}: Compare two sorted files line by line @@ -3689,6 +3728,9 @@ Anyhow, that's where tsort came from. To solve an old problem with the way the linker handled archive files, which has since been solved in different ways. +@exitstatus + + @node ptx invocation @section @command{ptx}: Produce permuted indexes @@ -3773,6 +3815,8 @@ processing. @end table +@exitstatus + @node Charset selection in ptx @subsection Charset selection @@ -4249,6 +4293,8 @@ output @var{output_delim_string} between ranges of selected bytes. @end table +@exitstatus + @node paste invocation @section @command{paste}: Merge lines of files @@ -4317,6 +4363,8 @@ $ paste -d '%_' num2 let3 num2 @end table +@exitstatus + @node join invocation @section @command{join}: Join lines on a common field @@ -4437,6 +4485,8 @@ In addition, when @sc{gnu} @command{join} is invoked with exactly one argument, the @option{--help} and @option{--version} options are recognized. @xref{Common options}. +@exitstatus + @node Operating on characters @chapter Operating on characters @@ -4483,6 +4533,8 @@ sets are the characters of the input that @command{tr} operates on. The @option{--complement} (@option{-c}) option replaces @var{set1} with its complement (all of the characters that are not in @var{set1}). +@exitstatus + @menu * Character sets:: Specifying sets of characters. * Translating:: Changing one set of characters to another. @@ -4888,6 +4940,8 @@ characters) on each line to spaces. @end table +@exitstatus + @node unexpand invocation @section @command{unexpand}: Convert spaces to tabs @@ -4940,6 +4994,8 @@ ones, to tabs. @end table +@exitstatus + @node Directory listing @chapter Directory listing @@ -4989,6 +5045,8 @@ within each section, options are listed alphabetically (ignoring case). The division of options into the subsections is not absolute, since some options affect more than one aspect of @command{ls}'s operation. +@exitstatus + Also see @ref{Common options}. @menu @@ -5927,6 +5985,8 @@ of the possibilities. @end table +@exitstatus + @node Basic operations @chapter Basic operations @@ -6285,6 +6345,8 @@ However, mount point directories @emph{are} copied. @end table +@exitstatus + @node dd invocation @section @command{dd}: Convert and copy a file @@ -6456,6 +6518,8 @@ zero bytes. @end table +@exitstatus + @node install invocation @section @command{install}: Copy files and set attributes @@ -6597,6 +6661,8 @@ argument can be @samp{none} (or @samp{off}), @samp{numbered} (or @end table +@exitstatus + @node mv invocation @section @command{mv}: Move (rename) files @@ -6725,6 +6791,8 @@ argument can be @samp{none} (or @samp{off}), @samp{numbered} (or @end table +@exitstatus + @node rm invocation @section @command{rm}: Remove files or directories @@ -6838,6 +6906,8 @@ rm ./-f The Unix @command{rm} program's use of a single @samp{-} for this purpose predates the development of the getopt standard syntax. +@exitstatus + @node shred invocation @section @command{shred}: Remove files more securely @@ -7045,6 +7115,9 @@ your hard disk, you could give a command like this: shred --verbose /dev/sda5 @end example +@exitstatus + + @node Special file types @chapter Special file types @@ -7103,6 +7176,9 @@ must specify a nonexistent entry in an existing directory. @command{link} simply calls @code{link (@var{filename}, @var{linkname})} to create the link. +@exitstatus + + @node ln invocation @section @command{ln}: Make links between files @@ -7265,6 +7341,8 @@ ln -s /some/name myname # creates link ./myname pointing to /some/name ln -s a b .. # creates links ../a and ../b pointing to ./a and ./b @end smallexample +@exitstatus + @node mkdir invocation @section @command{mkdir}: Make directories @@ -7279,8 +7357,8 @@ ln -s a b .. # creates links ../a and ../b pointing to ./a and ./b mkdir [@var{option}]@dots{} @var{name}@dots{} @end example -If a @var{name} is an existing file but not a directory, @command{mkdir} prints a -warning message on stderr and will exit with a status of 1 after +If a @var{name} is an existing file but not a directory, @command{mkdir} prints +a warning message on stderr and will exit with a status of 1 after processing any remaining @var{name}s. The same is done when a @var{name} is an existing directory and the -p option is not given. If a @var{name} is an existing directory and the -p option is given, @command{mkdir} will ignore it. @@ -7319,6 +7397,8 @@ Print a message for each created directory. This is most useful with @option{--parents}. @end table +@exitstatus + @node mkfifo invocation @section @command{mkfifo}: Make FIFOs (named pipes) @@ -7355,6 +7435,8 @@ the bits set in the umask for the point of departure. @xref{File permissions}. @end table +@exitstatus + @node mknod invocation @section @command{mknod}: Make block or character special files @@ -7424,6 +7506,8 @@ of departure. @xref{File permissions}. @end table +@exitstatus + @node readlink invocation @section @command{readlink}: Print the referent of a symbolic link @@ -7445,7 +7529,7 @@ of a symbolic link, it produces no output and exits with a nonzero exit code. @command{readlink} outputs the absolute name of the given file which contains no `.', `..' components nor any repeated path separators (`/') or symlinks. -In any path component is missing or unavailable, +If any path component is missing or unavailable, it produces no output and exits with a nonzero exit code. @end table @@ -7492,6 +7576,8 @@ Report error messages. The @command{readlink} utility first appeared in OpenBSD 2.1. +@exitstatus + @node rmdir invocation @section @command{rmdir}: Remove empty directories @@ -7543,6 +7629,9 @@ Give a diagnostic for each successful removal. @xref{rm invocation}, for how to remove non-empty directories (recursively). +@exitstatus + + @node unlink invocation @section @command{unlink}: Remove files via the unlink syscall @@ -7568,6 +7657,8 @@ options. That makes it a little harder to remove files named @env{POSIXLY_CORRECT} is set, @command{unlink} treats such a command line arguments not as an option, but as an operand. +@exitstatus + @node Changing file attributes @chapter Changing file attributes @@ -7785,6 +7876,8 @@ Recursively change ownership of directories and their contents. @end table +@exitstatus + @node chgrp invocation @section @command{chgrp}: Change group ownership @@ -7891,6 +7984,8 @@ Recursively change the group ownership of directories and their contents. @end table +@exitstatus + @node chmod invocation @section @command{chmod}: Change access permissions @@ -7974,6 +8069,8 @@ Recursively change permissions of directories and their contents. @end table +@exitstatus + @node touch invocation @section @command{touch}: Change file timestamps @@ -8082,6 +8179,8 @@ the argument is interpreted as a date in the current year. @end table +@exitstatus + @node Disk usage @chapter Disk usage @@ -8306,6 +8405,8 @@ Ignored; for compatibility with System V versions of @command{df}. @end table +@exitstatus + @node du invocation @section @command{du}: Estimate file space usage @@ -8501,6 +8602,8 @@ systems, it reports sizes that are twice the correct values for files that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX; it also affects the HP-UX @command{du} program. +@exitstatus + @node stat invocation @section @command{stat}: Report file or filesystem status @@ -8600,6 +8703,8 @@ Interpreted sequences for filesystem stat are: @end itemize @end table +@exitstatus + @node sync invocation @section @command{sync}: Synchronize data on disk with memory @@ -8624,6 +8729,9 @@ result. @command{sync} ensures everything in memory is written to disk. Any arguments are ignored, except for a lone @option{--help} or @option{--version} (@pxref{Common options}). +@exitstatus + + @node Printing text @chapter Printing text @@ -8694,6 +8802,8 @@ a valid octal number, it is printed literally. @end table +@exitstatus + @node printf invocation @section @command{printf}: Format and print data @@ -8789,6 +8899,8 @@ $ recode BIG5..JAVA < sample.txt \ > sample.sh @end smallexample +@exitstatus + @node yes invocation @section @command{yes}: Print a string until interrupted @@ -8800,6 +8912,8 @@ $ recode BIG5..JAVA < sample.txt \ followed by a newline, forever until it is killed. If no arguments are given, it prints @samp{y} followed by a newline forever until killed. +Upon a write error, @command{yes} exits with status @samp{1}. + The only options are a lone @option{--help} or @option{--version}. @xref{Common options}. @@ -9488,6 +9602,8 @@ Ignore interrupt signals. @end table +@exitstatus + @node File name manipulation @chapter File name manipulation @@ -9529,6 +9645,8 @@ result on standard output. The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node dirname invocation @section @command{dirname}: Strip non-directory suffix from a file name @@ -9551,6 +9669,8 @@ If @var{name} is a single component, @command{dirname} prints @samp{.} The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node pathchk invocation @section @command{pathchk}: Check file name portability @@ -9645,6 +9765,8 @@ different functionality than that described here. The only options are a lone @option{--help} or @option{--version}. @xref{Common options}. +@exitstatus + @node stty invocation @section @command{stty}: Print or change terminal characteristics @@ -9716,6 +9838,8 @@ description. On non-@acronym{POSIX} systems, those or other settings also may n be available, but it's not feasible to document all the variations: just try it and see. +@exitstatus + @menu * Control:: Control settings * Input:: Input settings @@ -10441,6 +10565,8 @@ Print only the user id. @end table +@exitstatus + @node logname invocation @section @command{logname}: Print current login name @@ -10461,6 +10587,8 @@ an error message and exits with a status of 1. The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node whoami invocation @section @command{whoami}: Print effective user id @@ -10475,6 +10603,8 @@ effective user id. It is equivalent to the command @samp{id -un}. The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node groups invocation @section @command{groups}: Print group names a user is in @@ -10497,6 +10627,8 @@ The group lists are equivalent to the output of the command @samp{id -Gn}. The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node users invocation @section @command{users}: Print login names of users currently logged in @@ -10525,6 +10657,8 @@ uses that file instead. A common choice is @file{/etc/wtmp}. The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node who invocation @section @command{who}: Print who is currently logged in @@ -10663,6 +10797,8 @@ After each login name print a character indicating the user's message status: @end table +@exitstatus + @node System context @chapter System context @@ -10710,6 +10846,8 @@ which is the same as in the @code{strftime} function. Except for directives, which start with @samp{%}, characters in the format string are printed unchanged. The directives are described below. +@exitstatus + @menu * Time directives:: %[HIklMprsSTXzZ] * Date directives:: %[aAbBcdDhjmUwWxyY] @@ -11316,6 +11454,9 @@ Print the kernel version. @end table +@exitstatus + + @node hostname invocation @section @command{hostname}: Print or set system name @@ -11337,6 +11478,8 @@ hostname [@var{name}] The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node hostid invocation @section @command{hostid}: Print numeric host identifier. @@ -11360,6 +11503,8 @@ On that system, the 32-bit quantity happens to be closely related to the system's Internet address, but that isn't always the case. +@exitstatus + @node Modified command invocation @chapter Modified command invocation @@ -11435,6 +11580,18 @@ files to the required positions under your intended new root directory. Finally, if the executable requires any other files (e.g., data, state, device files), copy them into place, too. +@cindex exit status of @command{chroot} +Exit status: + +@display +1 if there are invalid options, if the chroot syscall fails, + or if the subsequent @samp{chdir ("/")} 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 + @node env invocation @section @command{env}: Run a command in a modified environment @@ -11489,6 +11646,18 @@ Start with an empty environment, ignoring the inherited environment. @end table +@cindex exit status of @command{env} +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 +126 if @var{command} is found but cannot be invoked +127 if @var{command} cannot be found +the exit status of @var{command} otherwise +@end display + @node nice invocation @section @command{nice}: Run a command with modified scheduling priority @@ -11536,6 +11705,18 @@ instead. @end table +@cindex exit status of @command{nice} +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 +126 if @var{command} is found but cannot be invoked +127 if @var{command} cannot be found +the exit status of @var{command} otherwise +@end display + @node nohup invocation @section @command{nohup}: Run a command immune to hangups @@ -11583,8 +11764,8 @@ options}. Exit status: @display -126 if @var{command} was found but could not be invoked -127 if @command{nohup} itself failed or if @var{command} could not be found +126 if @var{command} is found but cannot be invoked +127 if @command{nohup} itself fails or if @var{command} cannot be found the exit status of @var{command} otherwise @end display @@ -11946,6 +12127,8 @@ digits). The only options are @option{--help} and @option{--version}. @xref{Common options}. +@exitstatus + @node Numeric operations @chapter Numeric operations @@ -11997,6 +12180,9 @@ $ factor `echo '2^64-1'|bc` 18446744073709551615: 3 5 17 257 641 65537 6700417 @end example +@exitstatus + + @node seq invocation @section @command{seq}: Print numeric sequences @@ -12130,6 +12316,9 @@ number, specify a slightly larger (or smaller, if @var{increment} is negative) value for @var{last} to ensure that @var{last} is the final value printed by seq. +@exitstatus + + @node File permissions @chapter File permissions @include perm.texi |