• intended usage of the section

• global defaults that affect all the standard utilities

• the meanings of notations used in the standard that are specific to individual utility sections.

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.

SYNOPSIS

The SYNOPSIS section summarises the syntax of the calling sequence for the utility, including options, option-arguments and operands. Standards for utility naming are described in XBD specification, Utility Syntax Guidelines  ; for describing the utility's arguments in XBD specification, Utility Argument Syntax  .

DESCRIPTION

The DESCRIPTION section describes the actions of the utility. If the utility has a very complex set of subcommands or its own procedural language, an EXTENDED DESCRIPTION section is also provided. Most explanations of optional functionality are omitted here, as they are usually explained in the OPTIONS section. 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.

OPTIONS

The OPTIONS section describes the utility options and option-arguments, and how they modify the actions of the utility. Standard utilities that have options either fully comply with the XBD specification, Utility Syntax Guidelines  or describe all deviations. Apparent disagreements between functionality descriptions in the OPTIONS and DESCRIPTION (or EXTENDED DESCRIPTION) sections are always resolved in favour of the OPTIONS section. 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:

foo -- -myfile

and avoid any problems with -m used as an extension.

OPERANDS

The OPERANDS section describes the utility operands, and how they affect the actions of the utility. Apparent disagreements between functionality descriptions in the OPERANDS and DESCRIPTION (or EXTENDED DESCRIPTION) sections are always resolved in favour of the OPERANDS section. 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.

STDIN

The STDIN section describes the standard input of the utility. This section is frequently merely a reference to the following section, as many utilities treat standard input and input files in the same manner. Unless otherwise stated, all restrictions described in the INPUT FILES section apply to this section as well. 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.

INPUT FILES

The INPUT FILES section describes the files, other than the standard input, used as input by the utility. It includes files named as operands and option-arguments as well as other files that are referred to, such as startup and initialisation files, databases, and so on. Commonly-used files are generally described in one place and cross-referenced by other utilities. 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.

ENVIRONMENT VARIABLES

The ENVIRONMENT VARIABLES section lists what variables affect the utility's execution. 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.

ASYNCHRONOUS EVENTS

The ASYNCHRONOUS EVENTS section lists how the utility reacts to such events as signals and what signals are caught. 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:

1. The action is that inherited from the parent according to the rules of inheritance of signal actions defined in the XSH specification.
2. When no action has been taken to change the default, the default action is that specified by the XSH specification.
3. The result of the utility's execution is as if default actions had been taken.

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.

STDOUT

The STDOUT section describes the standard output of the utility. This section is frequently merely a reference to the following section, OUTPUT FILES, because many utilities treat standard output and output files in the same manner. 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.

STDERR

The STDERR section describes the standard error output of the utility. Only those messages that are purposely sent by the utility are described. 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.

OUTPUT FILES

The OUTPUT FILES section describes the files created or modified by the utility. Temporary or system files that are created for internal usage by this utility or other parts of the implementation (for example, spool, log and audit files) are not described in this, or any, section. The utilities creating such files and the names of such files are unspecified. If applications are written to use temporary or intermediate files, they should use the TMPDIR environment variable, if it is set and represents an accessible directory, to select the location of temporary files. 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:

1. Resources for temporary files other than the name space (for example, disk space, available directory entries, or number of processes allowed) are not guaranteed.
2. Certain standard utilities generate output files that are intended as input for other utilities, (for example, lex generates lex.yy.c ) and these cannot have unique names. These cases are explicitly identified in the descriptions of the respective utilities.

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.

EXTENDED DESCRIPTION

The EXTENDED DESCRIPTION section provides a place for describing the actions of very complicated utilities, such as text editors or language processors, which typically have elaborate command languages. Default Behaviour: When this section is listed as "None", no further description is necessary.

EXIT STATUS

The EXIT STATUS section describes the values the utility will return to the calling program, or shell, and the conditions that cause these values to be returned. Usually, utilities return zero for successful completion and values greater than zero for various error conditions. If specific numeric values are listed in this section, the system will use those values for the errors described. In some cases, status values are listed more loosely, such as ">0". A portable application cannot rely on any specific value in the range shown and must be prepared to receive any value in the range. 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.

CONSEQUENCES OF ERRORS

The CONSEQUENCES OF ERRORS section describes the effects on the environment, file systems, process state, and so on, when error conditions occur. It does not describe error messages produced or exit status values used. 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:

• If the requested action cannot be performed on an operand representing a file, directory, user, process, and so on, the utility will issue a diagnostic message to standard error and continue processing the next operand in sequence, but the final exit status is returned as non-zero. 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.
• If the requested action characterised by an option or option-argument cannot be performed, the utility will issue a diagnostic message to standard error and the exit status returned will be non-zero.
• When an unrecoverable error condition is encountered, the utility will exit with a non-zero exit status.
• A diagnostic message will be written to standard error whenever an error condition occurs.

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.

APPLICATION USAGE

The APPLICATION USAGE section gives advice to the application programmer or user about the way the utility should be used.

EXAMPLES

The EXAMPLES section gives one or more examples of usage, where appropriate. This section is non-normative. In the event of conflict between an example and a normative part of the specification, the normative material is to be taken as correct. 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.

FUTURE DIRECTIONS

The FUTURE DIRECTIONS section should be used as a guide to current thinking; there is not necessarily a commitment to implement all of these future directions in their entirety.

SEE ALSO

The SEE ALSO section lists related entries.

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.