As far as is possible, each command description is in a uniform pattern:
- Main title
Description
Synopsis
Syntax description
Exit status (optional)
Error messages (optional)
Files (optional)
Environment variables (optional)
Locale (optional)
Examples (optional)
See also (optional)
These elements are now described in detail.
Main title
The main title includes:
the name of the command
a short description of the command
the suffix (BS2000) in the case of commands which are specially provided for operation with BS2000.
Description
Here the following are described:
the functionality of the command
the various purposes of individual formats if more than one is available
the environment in which the command is to be used (e.g. entries in files, permissions, etc.)
background information
points to be observed before and after the command call.
In the case of commands which call complex programs (e.g. awk, sh), this section simply describes the program call. For further information, e.g. about awk operation, please refer to the associated syntax section.
Syntax
|
The meaning of the metasyntax is described below.
In the syntax:
Boldface characters
Constants: These characters must be entered exactly as shown.
Normal characters
Variables: These characters stand for other characters for which you may select and enter a suitable value.
[ ]
Optional: arguments within square brackets are optional and may be omitted. The effects of these arguments are explained in the description of the options and arguments. You must not enter the square brackets themselves, unless specifically instructed to do so.
|
A vertical bar identifies alternatives from which you may choose one only.
' '
Indicates a mandatory blank (space).
...
Ellipses indicate that the preceding argument can be repeated. If blanks that are not part of the argument have to be placed between repetitions, the ellipses are preceded by ' ' (space).
Syntax description
option
(For a description of options see the section “Command options”)
argument
Description of the remaining arguments which you can pass when calling a command, e.g. input files, output files, parameters, variables, field separators etc.
Exit status (optional)
The exit status is the value which a command returns to the calling process following execution. The exit status provides information about command execution. The exit status is a numerical value which is contained in the ? variable. You can enter the command echo $? to query the exit status.
The exit status section is only included if the exit status deviates from following basic rule:
| 0 | successful execution of the command |
| >0 | the command has failed |
Error messages (optional)
Important error messages are listed and explained here. Additional notes indicate how errors can be avoided and recovered.
Unless otherwise specified, error messages are sent to the standard error output. Standard error (stderr) is usually the screen.
Files (optional)
This section lists files that the command accesses or creates.
Environment variables (optional)
Some commands inspect the values of environment variables. These are listed here.
Locale (optional)
This section describes how NLS affects the command (see the chapter “International environment (NLS locale)”).
Examples (optional)
Examples aim to illustrate:
the main function of the command
the use of the principal options
acceptable complex combinations of options and arguments
See also (optional)
This section contains references to other commands that perform similar functions or work in conjunction with the described command. References to literature containing more information on the command is provided where appropriate.
System calls and library functions for C developers are indicated by a pair of parentheses, e.g. chdir().
Notes and warnings
BS2000
Sections which refer to special characteristics of POSIX operation with the BS2000 are identified in this way.
This symbol indicates important information which you must be careful to observe.
This symbol precedes warnings which you should observe in the interests of system and operating security.
References
The following examples show how references to other sections of the text, manuals, commands, functions, system calls and file formats are presented.
| see the section “Command summary” | Reference to the section “Command Summary” in this manual |
| see "POSIX Basics for Users and System Administrators" [1] | Reference to a manual which is listed as number [1] under Related publications at the back of this manual |
| see also awk | Reference to the awk command in this manual |
| see also chdir() [4] | Reference to the C function, system call or file format chdir() in the manual which is listed as number [4] under Related publications at the back of this manual |