The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group
Utility Description Defaults
This section describes all of the subsections used within the utility
descriptions, including:
-
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:
-
The action is that inherited from the parent
according to the rules of inheritance of signal actions defined in the XSH specification.
-
When no action has been taken to change the default, the
default action is that specified by the XSH specification.
-
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:
-
Resources for temporary files other than
the name space (for example, disk space,
available directory entries, or number of
processes allowed) are not guaranteed.
-
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.
UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]