Integer variables and constants, including the values of operands and option-arguments, used by the utilities listed in this specification shall be implemented as equivalent to the ISO C standard signed long data type. Conversion between types shall be as described in the ISO C standard. The evaluation of arithmetic expressions shall be equivalent to that described in Section 6.3 of the ISO C standard.
Some utilities in this specification are described in terms of functionality equivalent to the XSH specification. When specific functions are cited, the underlying operating system provides equivalent functionality and all side effects associated with successful execution of the function. The treatment of errors and intermediate results from the individual functions cited are generally not specified by this specification. See the utility's EXIT STATUS and CONSEQUENCES OF ERRORS sections for all actions associated with errors encountered by the utility.
Each OPTIONS section that uses the phrase "The ... utility supports the Utility Syntax Guidelines ..." refers only to the use of the utility as specified by this specification; implementation extensions should also conform to the guidelines, but may allow exceptions for historical practice.
Unless otherwise stated in the utility description, when given an option unrecognised by the implementation, or when a required option-argument is not provided, standard utilities will issue a diagnostic message to standard error and exit with a non-zero exit status.
All utilities in this specification are capable of processing arguments using 8-bit transparency.
Default Behaviour: When this section is listed as "None", it means that the implementation need not support any options. Standard utilities that do not accept options, but that do accept operands, will recognise -- as a first argument to be discarded.
The requirement for recognising --
is because portable applications need a way to shield their
operands from any arbitrary options that the implementation
may provide as an extension.
For example, if the standard utility
foo
is listed as taking no options, and the application needed
to give it a pathname with a leading hyphen, it could safely
do it as:
and avoid any problems with -m used as an extension.
foo -- -myfile
If an operand naming a file can be specified as "-", which means to use the standard input instead of a named file, this is explicitly stated in this section. Unless otherwise stated, the use of multiple instances of "-" to mean standard input in a single command produces unspecified results.
Unless otherwise stated, the standard utilities that accept operands will process those operands in the order specified in the command line.
Default Behaviour: When this section is listed as "None", it means that the implementation need not support any operands.
Use of a terminal for standard input can cause any of the standard utilities that read standard input to stop when used in the background. For this reason, applications should not use interactive features in scripts to be placed in the background.
The specified standard input format of the standard utilities does not depend on the existence or value of the environment variables defined in this specification, except as provided by this specification.
Default Behaviour: When this section is listed as "Not used," it means that the standard input will not be read when the utility is used as described by this specification.
All utilities in this specification are capable of processing input files using 8-bit transparency.
When a standard utility reads a seekable input file and terminates
without an error before it reaches end-of-file,
the utility will ensure that the file offset in the open file description
is properly positioned just past the last byte
processed by the utility.
For files that are not seekable,
the state of the file offset
in the open file description for that file is unspecified.
A portable application cannot assume that
the following three commands are equivalent:
tail -n +2 file
(sed -n 1q; cat) < file
cat file | (sed -n 1q; cat)
The second command is equivalent to the first only when the file is seekable. The third command leaves the file offset in the open file description in an unspecified state. Other utilities, such as head, read and sh, have similar properties.
Some of the standard utilities, such as filters, process input files a line or a block at a time and have no restrictions on the maximum input file size. Some utilities may have size limitations that are not as obvious as file space or memory limitations. Such limitations should reflect resource limitations of some sort, not arbitrary limits set by implementors. Implementations will document those utilities that are limited by constraints other than file system space, available memory and other limits specifically cited by this specification, and identify what the constraint is and indicate a way of estimating when the constraint would be reached. Similarly, some utilities descend the directory tree (recursively). Implementations will also document any limits that they may have in descending the directory tree that are beyond limits cited by this specification.
When an input file is described as a text file , the utility produces undefined results if given input that is not from a text file, unless otherwise stated. Some utilities (for example, make, read, sh) allow for continued input lines using an escaped <newline> convention; unless otherwise stated, the utility need not be able to accumulate more than {LINE_MAX} bytes from a set of multiple, continued input lines. Thus, for a portable application the total of all the continued lines in a set cannot exceed {LINE_MAX}. If a utility using the escaped <newline> convention detects an end-of-file condition immediately after an escaped <newline>, the results are unspecified.
Record formats are described in a notation similar to that used by the C-language function, printf(). See XBD specification, File Format Notation for a description of this notation. The format description is intended to be sufficiently rigorous to allow other applications to generate these input files. However, since <blank> characters can legitimately be included in some of the fields described by the standard utilities, particularly in locales other than the POSIX locale, this intent is not always realised.
Default Behaviour: When this section is listed as "None", it means that no input files are required to be supplied when the utility is used as described by this specification.
The entire manner in which environment variables described in this specification affect the behaviour of each utility is described in the ENVIRONMENT VARIABLES section for that utility, in conjunction with the global effects of the LANG , LC_ALL and NLSPATH environment variables described in XBD specification, Environment Variables . The existence or value of environment variables described in this document will not otherwise affect the specified behaviour of the standard utilities. Any effects of the existence or value of environment variables not described by this specification upon the standard utilities are unspecified.
For those standard utilities that use environment variables as a means for selecting a utility to execute (such as CC in make), the string provided to the utility is subjected to the path search described for PATH in the XBD specification, Environment Variables .
All utilities in this specification are capable of processing environment variable names and values using 8-bit transparency.
Default Behaviour: When this section is listed as "None", it means that the behaviour of the utility is not directly affected by environment variables described by this specification when the utility is used as described by this specification.
Default Behaviour: When this section is listed as "Default", or it refers to "the standard action for all other signals; see Utility Description Defaults" it means that the action taken as a result of the signal is one of the following:
A utility is permitted to catch a signal, perform some additional processing (such as deleting temporary files), restore the default signal action (or action inherited from the parent process) and resignal itself.
Use of a terminal for standard output may cause any of the standard utilities that write standard output to stop when used in the background. For this reason, applications should not use interactive features in scripts to be placed in the background.
Record formats are described in a notation similar to that used by the C-language function, printf(). See the XBD specification, File Format Notation for a description of this notation.
The specified standard output of the standard utilities does not depend on the existence or value of the environment variables defined in this specification, except as provided by this specification.
Some of the standard utilities describe their output using the verb display, defined in the XBD specification, Glossary . Output described in the STDOUT sections of such utilities may be produced using means other than standard output. When standard output is directed to a terminal, the output described will be written directly to the terminal. Otherwise, the results are undefined.
Default Behaviour: When this section is listed as "Not used", it means that the standard output will not be written when the utility is used as described by this specification.
Use of a terminal for standard error may cause any of the standard utilities that write standard error output to stop when used in the background. For this reason, applications should not use interactive features in scripts to be placed in the background.
The format of diagnostic messages for most utilities is unspecified, but the language and cultural conventions of diagnostic and informative messages whose format is unspecified by this standard should be affected by the setting of LC_MESSAGES and NLSPATH .
The specified standard error output of standard utilities does not depend on the existence or value of the environment variables defined in this specification, except as provided by this specification.
Default Behaviour: When this section is listed as "Used only for diagnostic messages," it means that, unless otherwise stated, the diagnostic messages are sent to the standard error only when the exit status is non-zero and the utility is used as described by this specification.
When this section is listed as "Not used", it means that the standard error will not be used when the utility is used as described in this specification.
This section does not describe error messages that refer to incorrect operation of the utility. Consider a utility that processes program source code as its input. This section is used to describe messages produced by a correctly operating utility that encounters an error in the program source code on which it is processing. However, a message indicating that the utility had insufficient memory in which to operate would not be described.
Some compilers have traditionally produced warning messages without returning a non-zero exit status; these are specifically noted in their sections. Other utilities are expected to remain absolutely quiet on the standard error if they want to return zero, unless the implementation provides some sort of extension to increase the verbosity or debugging level.
Temporary files used by the standard utilities are named so that different utilities or multiple instances of the same utility can operate simultaneously without regard to their working directories, or any other process characteristic other than process ID. There are two exceptions to this rule:
Any temporary file created by the implementation is removed by the implementation upon a utility's successful exit, exit because of errors, or before termination by any of the SIGHUP, SIGINT or SIGTERM signals, unless specified otherwise by the utility description.
Receipt of the SIGQUIT signal should generally cause termination (unless in some debugging mode) that would bypass any attempted recovery actions.
Record formats are described in a notation similar to that used by the C-language function, printf(). See the XBD specification, File Format Notation for a description of this notation.
Default Behaviour: When this section is listed as "None", it means that no files are created or modified as a consequence of direct action on the part of the utility when the utility is used as described by this specification. However, the utility may create or modify system files, such as log files, that are outside the utility's normal execution environment.
Default Behaviour: When this section is listed as "None", no further description is necessary.
For example, a utility may list zero as a successful return, 1 as a failure for a specific reason, and >1 as "an error occurred". In this case, unspecified conditions may cause a 2 or 3, or other value, to be returned. A portable application should be written so that it tests for successful exit status values (zero in this case), rather than relying upon the single specific error value listed in this specification. In that way, it will have maximum portability, even on implementations with extensions.
Unspecified error conditions may be represented by specific values not listed in this specification.
The many reasons for failure of a utility are generally not specified by the utility descriptions. Utilities may terminate prematurely if they encounter: invalid usage of options, arguments or environment variables; invalid usage of the complex syntaxes expressed in EXTENDED DESCRIPTION sections; difficulties accessing, creating, reading or writing files; or difficulties associated with the privileges of the process.
The following apply to each utility, unless otherwise stated:
For a utility that recursively traverses a file hierarchy (such as
find
or
chown
-R),
if the requested action cannot be performed on a file or directory
encountered in the hierarchy, the utility will issue a diagnostic message to
standard error and continue processing the remaining files in the hierarchy,
but the final exit status will be returned as non-zero.
When a utility encounters an error condition several actions are possible, depending on the severity of the error and the state of the utility. Included in the possible actions of various utilities are: deletion of temporary or intermediate work files; deletion of incomplete files; validity checking of the file system or directory.
Default Behaviour: When this section is listed as "Default", it means that any changes to the environment are unspecified.
In all examples, quoting has been used, showing how sample commands (utility names combined with arguments) could be passed correctly to a shell (see sh) or as a string to the XSH specification system() function. Such quoting would not be used if the utility is invoked using one of the XSH specification exec functions.
Certain of the standard utilities describe how they can invoke other utilities or applications, such as by passing a command string to the command interpreter. The external influences (STDIN, ENVIRONMENT VARIABLES, and so on) and external effects (STDOUT, CONSEQUENCES OF ERRORS, and so on) of such invoked utilities are not described in the section concerning the standard utility that invokes them.