The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

1. Introduction

1.1 Scope

The scope of IEEE Std 1003.1-2001 is described in the Base Definitions volume of IEEE Std 1003.1-2001.

1.2 Conformance

Conformance requirements for IEEE Std 1003.1-2001 are defined in the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 2, Conformance.

1.3 Normative References

Normative references for IEEE Std 1003.1-2001 are defined in the Base Definitions volume of IEEE Std 1003.1-2001.

1.4 Change History

Change history is described in the Rationale (Informative) volume of IEEE Std 1003.1-2001, and in the CHANGE HISTORY section of reference pages.

1.5 Terminology

This section appears in the Base Definitions volume of IEEE Std 1003.1-2001, but is repeated here for convenience:

For the purposes of IEEE Std 1003.1-2001, the following terminology definitions apply:

can

Describes a permissible optional feature or behavior available to the user or application. The feature or behavior is mandatory for an implementation that conforms to IEEE Std 1003.1-2001. An application can rely on the existence of the feature or behavior.

implementation-defined

Describes a value or behavior that is not defined by IEEE Std 1003.1-2001 but is selected by an implementor. The value or behavior may vary among implementations that conform to IEEE Std 1003.1-2001. An application should not rely on the existence of the value or behavior. An application that relies on such a value or behavior cannot be assured to be portable across conforming implementations.

The implementor shall document such a value or behavior so that it can be used correctly by an application.

legacy

Describes a feature or behavior that is being retained for compatibility with older applications, but which has limitations which make it inappropriate for developing portable applications. New applications should use alternative means of obtaining equivalent functionality.

may

Describes a feature or behavior that is optional for an implementation that conforms to IEEE Std 1003.1-2001. An application should not rely on the existence of the feature or behavior. An application that relies on such a feature or behavior cannot be assured to be portable across conforming implementations.

To avoid ambiguity, the opposite of may is expressed as need not, instead of may not.

1.5.5 shall

For an implementation that conforms to IEEE Std 1003.1-2001, describes a feature or behavior that is mandatory. An application can rely on the existence of the feature or behavior.

For an application or user, describes a behavior that is mandatory.

should

For an implementation that conforms to IEEE Std 1003.1-2001, describes a feature or behavior that is recommended but not mandatory. An application should not rely on the existence of the feature or behavior. An application that relies on such a feature or behavior cannot be assured to be portable across conforming implementations.

For an application, describes a feature or behavior that is recommended programming practice for optimum portability.

undefined

Describes the nature of a value or behavior not defined by IEEE Std 1003.1-2001 which results from use of an invalid program construct or invalid data input.

The value or behavior may vary among implementations that conform to IEEE Std 1003.1-2001. An application should not rely on the existence or validity of the value or behavior. An application that relies on any particular value or behavior cannot be assured to be portable across conforming implementations.

unspecified

Describes the nature of a value or behavior not specified by IEEE Std 1003.1-2001 which results from use of a valid program construct or valid data input.

The value or behavior may vary among implementations that conform to IEEE Std 1003.1-2001. An application should not rely on the existence or validity of the value or behavior. An application that relies on any particular value or behavior cannot be assured to be portable across conforming implementations.

Definitions

Concepts and definitions are defined in the Base Definitions volume of IEEE Std 1003.1-2001.

1.7 Relationship to Other Documents

1.7.1 System Interfaces

This subsection describes some of the features provided by the System Interfaces volume of IEEE Std 1003.1-2001 that are assumed to be globally available on all systems conforming to this volume of IEEE Std 1003.1-2001. This subsection does not attempt to detail all of the features defined in the System Interfaces volume of IEEE Std 1003.1-2001 that are required by all of the utilities defined in this volume of IEEE Std 1003.1-2001; the utility and function descriptions point out additional functionality required to provide the corresponding specific features needed by each.

The following subsections describe frequently used concepts. Many of these concepts are described in the Base Definitions volume of IEEE Std 1003.1-2001. Utility and function description statements override these defaults when appropriate.

Process Attributes

The following process attributes, as described in the System Interfaces volume of IEEE Std 1003.1-2001, are assumed to be supported for all processes in this volume of IEEE Std 1003.1-2001:


Controlling Terminal
Current Working Directory
Effective Group ID
Effective User ID
File Descriptors
File Mode Creation Mask
Process Group ID
Process ID


Real Group ID
Real User ID
Root Directory
Saved Set-Group-ID
Saved Set-User-ID
Session Membership
Supplementary Group IDs

A conforming implementation may include additional process attributes.

Concurrent Execution of Processes

The following functionality of the fork() function defined in the System Interfaces volume of IEEE Std 1003.1-2001 shall be available on all systems conforming to this volume of IEEE Std 1003.1-2001:

  1. Independent processes shall be capable of executing independently without either process terminating.

  2. A process shall be able to create a new process with all of the attributes referenced in Process Attributes , determined according to the semantics of a call to the fork() function defined in the System Interfaces volume of IEEE Std 1003.1-2001 followed by a call in the child process to one of the exec functions defined in the System Interfaces volume of IEEE Std 1003.1-2001.

File Access Permissions

The file access control mechanism described by the Base Definitions volume of IEEE Std 1003.1-2001, Section 4.4, File Access Permissions shall apply to all files on an implementation conforming to this volume of IEEE Std 1003.1-2001.

File Read, Write, and Creation

If a file that does not exist is to be written, it shall be created as described below, unless the utility description states otherwise.

When a file that does not exist is created, the following features defined in the System Interfaces volume of IEEE Std 1003.1-2001 shall apply unless the utility or function description states otherwise:

  1. The user ID of the file shall be set to the effective user ID of the calling process.

  2. The group ID of the file shall be set to the effective group ID of the calling process or the group ID of the directory in which the file is being created.

  3. If the file is a regular file, the permission bits of the file shall be set to:

    S_IROTH | S_IWOTH | S_IRGRP | S_IWGRP | S_IRUSR | S_IWUSR
    

    (see the description of File Modes in the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Headers, <sys/stat.h>) except that the bits specified by the file mode creation mask of the process shall be cleared. If the file is a directory, the permission bits shall be set to:

    S_IRWXU | S_IRWXG | S_IRWXO
    

    except that the bits specified by the file mode creation mask of the process shall be cleared.

  4. The st_atime, st_ctime, and st_mtime fields of the file shall be updated as specified in the System Interfaces volume of IEEE Std 1003.1-2001, Section 2.5, Standard I/O Streams.

  5. If the file is a directory, it shall be an empty directory; otherwise, the file shall have length zero.

  6. If the file is a symbolic link, the effect shall be undefined unless the {POSIX2_SYMLINKS} variable is in effect for the directory in which the symbolic link would be created.

  7. Unless otherwise specified, the file created shall be a regular file.

When an attempt is made to create a file that already exists, the utility shall take the action indicated in Actions when Creating a File that Already Exists corresponding to the type of the file the utility is trying to create and the type of the existing file, unless the utility description states otherwise.


Table: Actions when Creating a File that Already Exists

 

New Type

Function

Existing Type

B

C

D

F

L

M

P

Q

R

S

T

Creating New

A

fattach()-ed STREAM

F

F

F

F

F

-

-

-

OF

-

U

N/A

B

Block Special

F

F

F

F

F

U

U

U

OF

U

U

mknod()**

C

Character Special

F

F

F

F

F

U

U

U

OF

U

U

mknod()**

D

Directory

F

F

F

F

F

-

-

-

F

-

U

mkdir()

F

FIFO Special File

F

F

F

F

F

-

-

-

O

-

U

mkfifo()

L

Symbolic Link

F

F

F

F

F

-

-

-

FL

-

U

symlink()

M

Shared Memory

F

F

F

F

F

-

-

-

-

-

U

shm_open()

P

Semaphore

F

F

F

F

F

-

-

-

-

-

U

sem_open()

Q

Message Queue

F

F

F

F

F

-

-

-

-

-

U

mq_open()

R

Regular File

F

F

F

F

F

-

-

-

RF

-

U

open()

S

Socket

F

F

F

F

F

-

-

-

-

-

U

bind()

T

Typed Memory

F

F

F

F

F

U

U

U

U

U

U

*

The following codes are used in Actions when Creating a File that Already Exists :

F
Fail. The attempt to create the new file shall fail and the utility shall either continue with its operation or exit immediately with a non-zero exit status, depending on the description of the utility.
FL
Follow link. Unless otherwise specified, the symbolic link shall be followed as specified for pathname resolution, and the operation performed shall be as if the target of the symbolic link (after all resolution) had been named. If the target of the symbolic link does not exist, it shall be as if that nonexistent target had been named directly.
O
Open FIFO. When attempting to create a regular file, and the existing file is a FIFO special file:
  1. If the FIFO is not already open for reading, the attempt shall block until the FIFO is opened for reading.

  2. Once the FIFO is open for reading, the utility shall open the FIFO for writing and continue with its operation.

OF
The named file shall be opened with the consequences defined for that file type.
RF
Regular file. When attempting to create a regular file, and the existing file is a regular file:
  1. The user ID, group ID, and permission bits of the file shall not be changed.

  2. The file shall be truncated to zero length.

  3. The st_ctime and st_mtime fields shall be marked for update.

-
The effect is implementation-defined unless specified by the utility description.
U
The effect is unspecified unless specified by the utility description.
*
There is no portable way to create a file of this type.
**
Not portable.

When a file is to be appended, the file shall be opened in a manner equivalent to using the O_APPEND flag, without the O_TRUNC flag, in the open() function defined in the System Interfaces volume of IEEE Std 1003.1-2001.

When a file is to be read or written, the file shall be opened with an access mode corresponding to the operation to be performed. If file access permissions deny access, the requested operation shall fail.

File Removal

When a directory that is the root directory or current working directory of any process is removed, the effect is implementation-defined. If file access permissions deny access, the requested operation shall fail. Otherwise, when a file is removed:

  1. Its directory entry shall be removed from the file system.

  2. The link count of the file shall be decremented.

  3. If the file is an empty directory (see the Base Definitions volume of IEEE Std 1003.1-2001, Section 3.143, Empty Directory):

    1. If no process has the directory open, the space occupied by the directory shall be freed and the directory shall no longer be accessible.

    2. If one or more processes have the directory open, the directory contents shall be preserved until all references to the file have been closed.

  4. If the file is a directory that is not empty, the st_ctime field shall be marked for update.

  5. If the file is not a directory:

    1. If the link count becomes zero:

      1. If no process has the file open, the space occupied by the file shall be freed and the file shall no longer be accessible.

      2. If one or more processes have the file open, the file contents shall be preserved until all references to the file have been closed.

    2. If the link count is not reduced to zero, the st_ctime field shall be marked for update.

  6. The st_ctime and st_mtime fields of the containing directory shall be marked for update.

File Time Values

All files shall have the three time values described by the Base Definitions volume of IEEE Std 1003.1-2001, Section 4.7, File Times Update.

File Contents

When a reference is made to the contents of a file, pathname, this means the equivalent of all of the data placed in the space pointed to by buf when performing the read() function calls in the following operations defined in the System Interfaces volume of IEEE Std 1003.1-2001:

while (read (fildes, buf, nbytes) > 0)
    ;

If the file is indicated by a pathname pathname, the file descriptor shall be determined by the equivalent of the following operation defined in the System Interfaces volume of IEEE Std 1003.1-2001:

fildes = open (pathname, O_RDONLY);

The value of nbytes in the above sequence is unspecified; if the file is of a type where the data returned by read() would vary with different values, the value shall be one that results in the most data being returned.

If the read() function calls would return an error, it is unspecified whether the contents of the file are considered to include any data from offsets in the file beyond where the error would be returned.

Pathname Resolution

The pathname resolution algorithm, described by the Base Definitions volume of IEEE Std 1003.1-2001, Section 4.11, Pathname Resolution, shall be used by implementations conforming to this volume of IEEE Std 1003.1-2001; see also the Base Definitions volume of IEEE Std 1003.1-2001, Section 4.5, File Hierarchy.

Changing the Current Working Directory

When the current working directory (see the Base Definitions volume of IEEE Std 1003.1-2001, Section 3.436, Working Directory) is to be changed, unless the utility or function description states otherwise, the operation shall succeed unless a call to the chdir() function defined in the System Interfaces volume of IEEE Std 1003.1-2001 would fail when invoked with the new working directory pathname as its argument.

Establish the Locale

The functionality of the setlocale() function defined in the System Interfaces volume of IEEE Std 1003.1-2001 shall be available on all systems conforming to this volume of IEEE Std 1003.1-2001; that is, utilities that require the capability of establishing an international operating environment shall be permitted to set the specified category of the international environment.

Actions Equivalent to Functions

Some utility descriptions specify that a utility performs actions equivalent to a function defined in the System Interfaces volume of IEEE Std 1003.1-2001. Such specifications require only that the external effects be equivalent, not that any effect within the utility and visible only to the utility be equivalent.

1.7.2 Concepts Derived from the ISO C Standard

Some of the standard utilities perform complex data manipulation using their own procedure and arithmetic languages, as defined in their EXTENDED DESCRIPTION or OPERANDS sections. Unless otherwise noted, the arithmetic and semantic concepts (precision, type conversion, control flow, and so on) shall be equivalent to those defined in the ISO C standard, as described in the following sections. Note that there is no requirement that the standard utilities be implemented in any particular programming language.

Arithmetic Precision and Operations

Integer variables and constants, including the values of operands and option-arguments, used by the standard utilities listed in this volume of IEEE Std 1003.1-2001 shall be implemented as equivalent to the ISO C standard signed long data type; floating point shall be implemented as equivalent to the ISO C standard double type. Conversions between types shall be as described in the ISO C standard. All variables shall be initialized to zero if they are not otherwise assigned by the input to the application.

Arithmetic operators and control flow keywords shall be implemented as equivalent to those in the cited ISO C standard section, as listed in Selected ISO C Standard Operators and Control Flow Keywords.


Table: Selected ISO C Standard Operators and Control Flow Keywords

Operation

ISO C Standard Equivalent Reference

()

Section 6.5.1, Primary Expressions

postfix ++

Section 6.5.2, Postfix Operators

postfix --

 

unary +

Section 6.5.3, Unary Operators

unary -

 

prefix ++

 

prefix --

 

˜

 

!

 

sizeof()

 

*

Section 6.5.5, Multiplicative Operators

/

 

%

 

+

Section 6.5.6, Additive Operators

-

 

<<

Section 6.5.7, Bitwise Shift Operators

>>

 

<, <=

Section 6.5.8, Relational Operators

>, >=

 

==

Section 6.5.9, Equality Operators

!=

 

&

Section 6.5.10, Bitwise AND Operator

^

Section 6.5.11, Bitwise Exclusive OR Operator

|

Section 6.5.12, Bitwise Inclusive OR Operator

&&

Section 6.5.13, Logical AND Operator

||

Section 6.5.14, Logical OR Operator

expr?expr:expr

Section 6.5.15, Conditional Operator

=, *=, /=, %=, +=, -=

Section 6.5.16, Assignment Operators

<<=, >>=, &=, ^=, |=

 

if ()

Section 6.8.4, Selection Statements

if () ... else

 

switch ()

 

while ()

Section 6.8.5, Iteration Statements

do ... while ()

 

for ()

 

goto

Section 6.8.6, Jump Statements

continue

 

break

 

return

 

The evaluation of arithmetic expressions shall be equivalent to that described in Section 6.5, Expressions, of the ISO C standard.

Mathematical Functions

Any mathematical functions with the same names as those in the following sections of the ISO C standard:

shall be implemented to return the results equivalent to those returned from a call to the corresponding function described in the ISO C standard.

1.8 Portability

Some of the utilities in the Shell and Utilities volume of IEEE Std 1003.1-2001 and functions in the System Interfaces volume of IEEE Std 1003.1-2001 describe functionality that might not be fully portable to systems meeting the requirements for POSIX conformance (see the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 2, Conformance).

Where optional, enhanced, or reduced functionality is specified, the text is shaded and a code in the margin identifies the nature of the option, extension, or warning (see Codes). For maximum portability, an application should avoid such functionality.

Unless the primary task of a utility is to produce textual material on its standard output, application developers should not rely on the format or content of any such material that may be produced. Where the primary task is to provide such material, but the output format is incompletely specified, the description is marked with the OF margin code and shading. Application developers are warned not to expect that the output of such an interface on one system is any guide to its behavior on another system.

1.8.1 Codes

Codes and their meanings are listed in the Base Definitions volume of IEEE Std 1003.1-2001, but are repeated here for convenience:

[ADV] [Option Start] Advisory Information [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the ADV margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the ADV margin legend.

[AIO] [Option Start] Asynchronous Input and Output [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the AIO margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the AIO margin legend.

[BAR] [Option Start] Barriers [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the BAR margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the BAR margin legend.

[BE] [Option Start] Batch Environment Services and Utilities [Option End]
The functionality described is optional.

Where applicable, utilities are marked with the BE margin legend in the SYNOPSIS section. Where additional semantics apply to a utility, the material is identified by use of the BE margin legend.

[CD] [Option Start] C-Language Development Utilities [Option End]
The functionality described is optional.

Where applicable, utilities are marked with the CD margin legend in the SYNOPSIS section. Where additional semantics apply to a utility, the material is identified by use of the CD margin legend.

[CPT] [Option Start] Process CPU-Time Clocks [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the CPT margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the CPT margin legend.

[CS] [Option Start] Clock Selection [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the CS margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the CS margin legend.

[CX] [Option Start] Extension to the ISO C standard [Option End]
The functionality described is an extension to the ISO C standard. Application writers may make use of an extension as it is supported on all IEEE Std 1003.1-2001-conforming systems.

With each function or header from the ISO C standard, a statement to the effect that "any conflict is unintentional" is included. That is intended to refer to a direct conflict. IEEE Std 1003.1-2001 acts in part as a profile of the ISO C standard, and it may choose to further constrain behaviors allowed to vary by the ISO C standard. Such limitations are not considered conflicts.

Where additional semantics apply to a function or header, the material is identified by use of the CX margin legend.

[FD] [Option Start] FORTRAN Development Utilities [Option End]
The functionality described is optional.

Where applicable, utilities are marked with the FD margin legend in the SYNOPSIS section. Where additional semantics apply to a utility, the material is identified by use of the FD margin legend.

[FR] [Option Start] FORTRAN Runtime Utilities [Option End]
The functionality described is optional.

Where applicable, utilities are marked with the FR margin legend in the SYNOPSIS section. Where additional semantics apply to a utility, the material is identified by use of the FR margin legend.

[FSC] [Option Start] File Synchronization [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the FSC margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the FSC margin legend.

[IP6] [Option Start] IPV6 [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the IP6 margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the IP6 margin legend.

[MC1] [Option Start] Advisory Information and either Memory Mapped Files or Shared Memory Objects [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

This is a shorthand notation for combinations of multiple option codes.

Where applicable, functions are marked with the MC1 margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MC1 margin legend.

Refer to the Base Definitions volume of IEEE Std 1003.1-2001, Section 1.5.2, Margin Code Notation.

[MC2] [Option Start] Memory Mapped Files, Shared Memory Objects, or Memory Protection [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

This is a shorthand notation for combinations of multiple option codes.

Where applicable, functions are marked with the MC2 margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MC2 margin legend.

Refer to the Base Definitions volume of IEEE Std 1003.1-2001, Section 1.5.2, Margin Code Notation.

[MC3] [Option Start] Memory Mapped Files, Shared Memory Objects, or Typed Memory Objects [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

This is a shorthand notation for combinations of multiple option codes.

Where applicable, functions are marked with the MC3 margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MC3 margin legend.

Refer to the Base Definitions volume of IEEE Std 1003.1-2001, Section 1.5.2, Margin Code Notation.

[MF] [Option Start] Memory Mapped Files [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the MF margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MF margin legend.

[ML] [Option Start] Process Memory Locking [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the ML margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the ML margin legend.

[MR] [Option Start] Range Memory Locking [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the MLR margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MLR margin legend.

[MON] [Option Start] Monotonic Clock [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the MON margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MON margin legend.

[MPR] [Option Start] Memory Protection [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the MPR margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MPR margin legend.

[MSG] [Option Start] Message Passing [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the MSG margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MSG margin legend.

[MX] [Option Start] IEC 60559 Floating-Point Option [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the MX margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the MX margin legend.

[OB] [Option Start] Obsolescent [Option End]
The functionality described may be withdrawn in a future version of this volume of IEEE Std 1003.1-2001. Strictly Conforming POSIX Applications and Strictly Conforming XSI Applications shall not use obsolescent features.

Where applicable, the material is identified by use of the OB margin legend.

[OF] [Option Start] Output Format Incompletely Specified [Option End]
The functionality described is an XSI extension. The format of the output produced by the utility is not fully specified. It is therefore not possible to post-process this output in a consistent fashion. Typical problems include unknown length of strings and unspecified field delimiters.

Where applicable, the material is identified by use of the OF margin legend.

[OH] [Option Start] Optional Header [Option End]
In the SYNOPSIS section of some interfaces in the System Interfaces volume of IEEE Std 1003.1-2001 an included header is marked as in the following example:

[OH][Option Start]
#include <sys/types.h>
[Option End]
#include <grp.h>
struct group *getgrnam(const char *name);

The OH margin legend indicates that the marked header is not required on XSI-conformant systems.

[PIO] [Option Start] Prioritized Input and Output [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the PIO margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the PIO margin legend.

[PS] [Option Start] Process Scheduling [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the PS margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the PS margin legend.

[RS] [Option Start] Raw Sockets [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the RS margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the RS margin legend.

[RTS] [Option Start] Realtime Signals Extension [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the RTS margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the RTS margin legend.

[SD] [Option Start] Software Development Utilities [Option End]
The functionality described is optional.

Where applicable, utilities are marked with the SD margin legend in the SYNOPSIS section. Where additional semantics apply to a utility, the material is identified by use of the SD margin legend.

[SEM] [Option Start] Semaphores [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the SEM margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the SEM margin legend.

[SHM] [Option Start] Shared Memory Objects [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the SHM margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the SHM margin legend.

[SIO] [Option Start] Synchronized Input and Output [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the SIO margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the SIO margin legend.

[SPI] [Option Start] Spin Locks [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the SPI margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the SPI margin legend.

[SPN] [Option Start] Spawn [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the SPN margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the SPN margin legend.

[SS] [Option Start] Process Sporadic Server [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the SS margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the SS margin legend.

[TCT] [Option Start] Thread CPU-Time Clocks [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TCT margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TCT margin legend.

[TEF] [Option Start] Trace Event Filter [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TEF margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TEF margin legend.

[THR] [Option Start] Threads [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the THR margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the THR margin legend.

[TMO] [Option Start] Timeouts [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TMO margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TMO margin legend.

[TMR] [Option Start] Timers [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TMR margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TMR margin legend.

[TPI] [Option Start] Thread Priority Inheritance [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TPI margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TPI margin legend.

[TPP] [Option Start] Thread Priority Protection [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TPP margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TPP margin legend.

[TPS] [Option Start] Thread Execution Scheduling [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TPS margin legend for the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TPS margin legend.

[TRC] [Option Start] Trace [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TRC margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TRC margin legend.

[TRI] [Option Start] Trace Inherit [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TRI margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TRI margin legend.

[TRL] [Option Start] Trace Log [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TRL margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TRL margin legend.

[TSA] [Option Start] Thread Stack Address Attribute [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TSA margin legend for the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TSA margin legend.

[TSF] [Option Start] Thread-Safe Functions [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TSF margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TSF margin legend.

[TSH] [Option Start] Thread Process-Shared Synchronization [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TSH margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TSH margin legend.

[TSP] [Option Start] Thread Sporadic Server [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TSP margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TSP margin legend.

[TSS] [Option Start] Thread Stack Size Attribute [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TSS margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TSS margin legend.

[TYM] [Option Start] Typed Memory Objects [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the TYM margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the TYM margin legend.

[UP] [Option Start] User Portability Utilities [Option End]
The functionality described is optional.

Where applicable, utilities are marked with the UP margin legend in the SYNOPSIS section. Where additional semantics apply to a utility, the material is identified by use of the UP margin legend.

[XSI] [Option Start] Extension [Option End]
The functionality described is an XSI extension. Functionality marked XSI is also an extension to the ISO C standard. Application writers may confidently make use of an extension on all systems supporting the X/Open System Interfaces Extension.

If an entire SYNOPSIS section is shaded and marked XSI, all the functionality described in that reference page is an extension. See the Base Definitions volume of IEEE Std 1003.1-2001, Section 3.439, XSI.

[XSR] [Option Start] XSI STREAMS [Option End]
The functionality described is optional. The functionality described is also an extension to the ISO C standard.

Where applicable, functions are marked with the XSR margin legend in the SYNOPSIS section. Where additional semantics apply to a function, the material is identified by use of the XSR margin legend.

1.9 Utility Limits

This section lists magnitude limitations imposed by a specific implementation. The braces notation, {LIMIT}, is used in this volume of IEEE Std 1003.1-2001 to indicate these values, but the braces are not part of the name.

Table: Utility Limit Minimum Values

Name

Description

Value

{POSIX2_BC_BASE_MAX}

The maximum obase value allowed by the bc utility.

99

{POSIX2_BC_DIM_MAX}

The maximum number of elements permitted in an array by the bc utility.

2048

{POSIX2_BC_SCALE_MAX}

The maximum scale value allowed by the bc utility.

99

{POSIX2_BC_STRING_MAX}

The maximum length of a string constant accepted by the bc utility.

1000

{POSIX2_COLL_WEIGHTS_MAX}

The maximum number of weights that can be assigned to an entry of the LC_COLLATE order keyword in the locale definition file; see the border_start keyword in the Base Definitions volume of IEEE Std 1003.1-2001, Section 7.3.2, LC_COLLATE.

2

{POSIX2_EXPR_NEST_MAX}

The maximum number of expressions that can be nested within parentheses by the expr utility.

32

{POSIX2_LINE_MAX}

Unless otherwise noted, the maximum length, in bytes, of the input line of a utility (either standard input or another file), when the utility is described as processing text files. The length includes room for the trailing <newline>.

2048

{POSIX2_RE_DUP_MAX}

The maximum number of repeated occurrences of a BRE permitted when using the interval notation \{m,n\}; see the Base Definitions volume of IEEE Std 1003.1-2001, Section 9.3.6, BREs Matching Multiple Characters.

255

The values specified in Utility Limit Minimum Values represent the lowest values conforming implementations shall provide and, consequently, the largest values on which an application can rely without further enquiries, as described below. These values shall be accessible to applications via the getconf utility (see getconf).

Implementations may provide more liberal, or less restrictive, values than shown in Utility Limit Minimum Values. These possibly more liberal values are accessible using the symbols in Symbolic Utility Limits.

The sysconf() function defined in the System Interfaces volume of IEEE Std 1003.1-2001 or the getconf utility return the value of each symbol on each specific implementation. The value so retrieved is the largest, or most liberal, value that is available throughout the session lifetime, as determined at session creation. The literal names shown in the table apply only to the getconf utility; the high-level language binding describes the exact form of each name to be used by the interfaces in that binding.

All numeric limits defined by the System Interfaces volume of IEEE Std 1003.1-2001, such as {PATH_MAX}, shall also apply to this volume of IEEE Std 1003.1-2001. All the utilities defined by this volume of IEEE Std 1003.1-2001 are implicitly limited by these values, unless otherwise noted in the utility descriptions.

It is not guaranteed that the application can actually reach the specified limit of an implementation in any given case, or at all, as a lack of virtual memory or other resources may prevent this. The limit value indicates only that the implementation does not specifically impose any arbitrary, more restrictive limit.

Table: Symbolic Utility Limits

Name

Description

Minimum Value

{BC_BASE_MAX}

The maximum obase value allowed by the bc utility.

{POSIX2_BC_BASE_MAX}

{BC_DIM_MAX}

The maximum number of elements permitted in an array by the bc utility.

{POSIX2_BC_DIM_MAX}

{BC_SCALE_MAX}

The maximum scale value allowed by the bc utility.

{POSIX2_BC_SCALE_MAX}

{BC_STRING_MAX}

The maximum length of a string constant accepted by the bc utility.

{POSIX2_BC_STRING_MAX}

{COLL_WEIGHTS_MAX}

The maximum number of weights that can be assigned to an entry of the LC_COLLATE order keyword in the locale definition file; see the order_start keyword in the Base Definitions volume of IEEE Std 1003.1-2001, Section 7.3.2, LC_COLLATE.

{POSIX2_COLL_WEIGHTS_MAX}

{EXPR_NEST_MAX}

The maximum number of expressions that can be nested within parentheses by the expr utility.

{POSIX2_EXPR_NEST_MAX}

{LINE_MAX}

Unless otherwise noted, the maximum length, in bytes, of the input line of a utility (either standard input or another file), when the utility is described as processing text files. The length includes room for the trailing <newline>.

{POSIX2_LINE_MAX}

{RE_DUP_MAX}

The maximum number of repeated occurrences of a BRE permitted when using the interval notation \{m,n\}; see the Base Definitions volume of IEEE Std 1003.1-2001, Section 9.3.6, BREs Matching Multiple Characters.

{POSIX2_RE_DUP_MAX}

The following value may be a constant within an implementation or may vary from one pathname to another.

{POSIX2_SYMLINKS}
When referring to a directory, the system supports the creation of symbolic links within that directory; for non-directory files, the meaning of {POSIX2_SYMLINKS} is undefined.

1.10 Grammar Conventions

Portions of this volume of IEEE Std 1003.1-2001 are expressed in terms of a special grammar notation. It is used to portray the complex syntax of certain program input. The grammar is based on the syntax used by the yacc utility. However, it does not represent fully functional yacc input, suitable for program use; the lexical processing and all semantic requirements are described only in textual form. The grammar is not based on source used in any traditional implementation and has not been tested with the semantic code that would normally be required to accompany it. Furthermore, there is no implication that the partial yacc code presented represents the most efficient, or only, means of supporting the complex syntax within the utility. Implementations may use other programming languages or algorithms, as long as the syntax supported is the same as that represented by the grammar.

The following typographical conventions are used in the grammar; they have no significance except to aid in reading.

1.11 Utility Description Defaults

This section describes all of the subsections used within the utility descriptions, including:

NAME
This section gives the name or names of the utility and briefly states its purpose.
SYNOPSIS
The SYNOPSIS section summarizes the syntax of the calling sequence for the utility, including options, option-arguments, and operands. Standards for utility naming are described in the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines; for describing the utility's arguments in the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.1, 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.

As stated in Actions Equivalent to Functions , some functions are described in terms of equivalent functionality. When specific functions are cited, the implementation shall provide equivalent functionality including side effects associated with successful execution of the function. The treatment of errors and intermediate results from the individual functions cited is generally not specified by this volume of IEEE Std 1003.1-2001. 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 Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, 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 favor of the OPTIONS section.

Each OPTIONS section that uses the phrase "The ... utility shall conform to the Utility Syntax Guidelines ..." refers only to the use of the utility as specified by this volume of IEEE Std 1003.1-2001; 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 unrecognized by the implementation, or when a required option-argument is not provided, standard utilities shall issue a diagnostic message to standard error and exit with a non-zero exit status.

All utilities in this volume of IEEE Std 1003.1-2001 shall be capable of processing arguments using eight-bit transparency.

Default Behavior: 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, shall recognize "--" as a first argument to be discarded.

The requirement for recognizing "--" is because conforming 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 shall be resolved in favor 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 shall process those operands in the order specified in the command line.

Default Behavior: 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 shall 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 shall not depend on the existence or value of the environment variables defined in this volume of IEEE Std 1003.1-2001, except as provided by this volume of IEEE Std 1003.1-2001.

Default Behavior: When this section is listed as "Not used.", it means that the standard input shall not be read when the utility is used as described by this volume of IEEE Std 1003.1-2001.

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 start-up and initialization files, databases, and so on. Commonly-used files are generally described in one place and cross-referenced by other utilities.

All utilities in this volume of IEEE Std 1003.1-2001 shall be capable of processing input files using eight-bit transparency.

When a standard utility reads a seekable input file and terminates without an error before it reaches end-of-file, the utility shall 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 conforming application shall not 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 shall document those utilities that are limited by constraints other than file system space, available memory, and other limits specifically cited by this volume of IEEE Std 1003.1-2001, 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 shall also document any limits that they may have in descending the directory tree that are beyond limits cited by this volume of IEEE Std 1003.1-2001.

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 conforming 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 the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 5, 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>s 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 realized.

Default Behavior: 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 volume of IEEE Std 1003.1-2001.

ENVIRONMENT VARIABLES
The ENVIRONMENT VARIABLES section lists what variables affect the utility's execution.

The entire manner in which environment variables described in this volume of IEEE Std 1003.1-2001 affect the behavior 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 [XSI] [Option Start] NLSPATH [Option End] environment variables described in the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8, Environment Variables. The existence or value of environment variables described in this volume of IEEE Std 1003.1-2001 shall not otherwise affect the specified behavior of the standard utilities. Any effects of the existence or value of environment variables not described by this volume of IEEE Std 1003.1-2001 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 Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8, Environment Variables.

All utilities in this volume of IEEE Std 1003.1-2001 shall be capable of processing environment variable names and values using eight-bit transparency.

Default Behavior: When this section is listed as "None.", it means that the behavior of the utility is not directly affected by environment variables described by this volume of IEEE Std 1003.1-2001 when the utility is used as described by this volume of IEEE Std 1003.1-2001.

ASYNCHRONOUS EVENTS
The ASYNCHRONOUS EVENTS section lists how the utility reacts to such events as signals and what signals are caught.

Default Behavior: 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 shall be one of the following:

  1. The action shall be that inherited from the parent according to the rules of inheritance of signal actions defined in the System Interfaces volume of IEEE Std 1003.1-2001.

  2. When no action has been taken to change the default, the default action shall be that specified by the System Interfaces volume of IEEE Std 1003.1-2001.

  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 completely 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 Base Definitions volume of IEEE Std 1003.1-2001, Chapter 5, File Format Notation for a description of this notation.

The specified standard output of the standard utilities shall not depend on the existence or value of the environment variables defined in this volume of IEEE Std 1003.1-2001, except as provided by this volume of IEEE Std 1003.1-2001.

Some of the standard utilities describe their output using the verb display, defined in the Base Definitions volume of IEEE Std 1003.1-2001, Section 3.132, Display. 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 shall be written directly to the terminal. Otherwise, the results are undefined.

Default Behavior: When this section is listed as "Not used.", it means that the standard output shall not be written when the utility is used as described by this volume of IEEE Std 1003.1-2001.

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 volume of IEEE Std 1003.1-2001 should be affected by the setting of LC_MESSAGES and [XSI] [Option Start] NLSPATH . [Option End]

The specified standard error output of standard utilities shall not depend on the existence or value of the environment variables defined in this volume of IEEE Std 1003.1-2001, except as provided by this volume of IEEE Std 1003.1-2001.

Default Behavior: When this section is listed as "The standard error shall be used only for diagnostic messages.", it means that, unless otherwise stated, the diagnostic messages shall be sent to the standard error only when the exit status is non-zero and the utility is used as described by this volume of IEEE Std 1003.1-2001.

When this section is listed as "Not used.", it means that the standard error shall not be used when the utility is used as described in this volume of IEEE Std 1003.1-2001.

OUTPUT FILES
The OUTPUT FILES section completely 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.

Implementations shall ensure that temporary files, when 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 shall be 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 Base Definitions volume of IEEE Std 1003.1-2001, Chapter 5, File Format Notation for a description of this notation.

Default Behavior: 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 volume of IEEE Std 1003.1-2001. 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 Behavior: When this section is listed as "None.", no further description is necessary.

EXIT STATUS
The EXIT STATUS section describes the values the utility shall 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 shall use those values for the errors described. In some cases, status values are listed more loosely, such as >0. A strictly conforming application shall not rely on any specific value in the range shown and shall 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 conforming 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 volume of IEEE Std 1003.1-2001. In that way, it has maximum portability, even on implementations with extensions.

Unspecified error conditions may be represented by specific values not listed in this volume of IEEE Std 1003.1-2001.

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 shall apply to each utility, unless otherwise stated:

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 Behavior: When this section is listed as "Default.", it means that any changes to the environment are unspecified.

APPLICATION USAGE
This section is informative.

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

EXAMPLES
This section is informative.

The EXAMPLES section gives one or more examples of usage, where appropriate. 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 system() function defined in the System Interfaces volume of IEEE Std 1003.1-2001. Such quoting would not be used if the utility is invoked using one of the exec functions defined in the System Interfaces volume of IEEE Std 1003.1-2001.

RATIONALE
This section is informative.

This section contains historical information concerning the contents of this volume of IEEE Std 1003.1-2001 and why features were included or discarded by the standard developers.

FUTURE DIRECTIONS
This section is informative.

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
This section is informative.

The SEE ALSO section lists related entries.

CHANGE HISTORY
This section is informative.

This section shows the derivation of the entry and any significant changes that have been made to it.

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.

1.12 Considerations for Utilities in Support of Files of Arbitrary Size

The following utilities support files of any size up to the maximum that can be created by the implementation. This support includes correct writing of file size-related values (such as file sizes and offsets, line numbers, and block counts) and correct interpretation of command line arguments that contain such values.

basename
Return non-directory portion of pathname.
cat
Concatenate and print files.
cd
Change working directory.
chgrp
Change file group ownership.
chmod
Change file modes.
chown
Change file ownership.
cksum
Write file checksums and sizes.
cmp
Compare two files.
cp
Copy files.
dd
Convert and copy a file.
df
Report free disk space.
dirname
Return directory portion of pathname.
du
Estimate file space usage.
find
Find files.
ln
Link files.
ls
List directory contents.
mkdir
Make directories.
mv
Move files.
pathchk
Check pathnames.
pwd
Return working directory name.
rm
Remove directory entries.
rmdir
Remove directories.
sh
Shell, the standard command language interpreter.
sum
Print checksum and block or byte count of a file.
test
Evaluate expression.
touch
Change file access and modification times.
ulimit
Set or report file size limit.

Exceptions to the requirement that utilities support files of any size up to the maximum are as follows:

  1. Uses of files as command scripts, or for configuration or control, are exempt. For example, it is not required that sh be able to read an arbitrarily large .profile.

  2. Shell input and output redirection are exempt. For example, it is not required that the redirections sum < file or echo foo > file succeed for an arbitrarily large existing file.

1.13 Built-In Utilities

Any of the standard utilities may be implemented as regular built-in utilities within the command language interpreter. This is usually done to increase the performance of frequently used utilities or to achieve functionality that would be more difficult in a separate environment. The utilities named in Regular Built-In Utilities are frequently provided in built-in form. All of the utilities named in the table have special properties in terms of command search order within the shell, as described in Command Search and Execution.

Table: Regular Built-In Utilities


alias
bg
cd
command
 


false
fc
fg
getopts
 


jobs
kill
newgrp
pwd
 


read
true
umask
unalias
 


wait
 

However, all of the standard utilities, including the regular built-ins in the table, but not the special built-ins described in Special Built-In Utilities , shall be implemented in a manner so that they can be accessed via the exec family of functions as defined in the System Interfaces volume of IEEE Std 1003.1-2001 and can be invoked directly by those standard utilities that require it ( env, find, nice, nohup, time, xargs).


UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]