FreeBSD Manual Pages
Intro(1) Intro(1) NAME Intro, intro - introduction to commands and application programs This section describes, in alphabetical order, commands available with this operating system. Pages of special interest are categorized as follows: 1B Commands found only in the SunOS/BSD Compatibility Package. 1C Commands for communicating with other systems. 1F Commands associated with Form and Menu Language Interpreter (FMLI). 1S Commands specific to SunOS. OTHER SECTIONS See these sections of the for more information. o Section 1M in this manual for system maintenance commands. o Section 4 of this manual for information on file formats. o Section 5 of this manual for descriptions of publicly available files and miscellaneous information pages. o Section 6 in this manual for computer demonstrations. For tutorial information about these commands and procedures, see: o Manual Page Command Syntax Unless otherwise noted, commands described in the section of a manual page accept options and other arguments according to the following syn- tax and should be interpreted as explained below. name [-option...] [cmdarg...] where: [ ] Surround an option or cmdarg that is not required. ... Indicates multiple occurrences of the option or cmdarg. name The name of an executable file. { } The options and/or arguments enclosed within braces are interdependent, such that everything enclosed must be treated as a unit. option (Always preceded by a "-".) noargletter... or, arglet- ter optarg[,...] noargletter A single letter representing an option without an op- tion-argument. Notice that more than one noargletter option can be grouped after one "-" (Guideline 5, be- low). argletter A single letter representing an option requiring an op- tion-argument. optarg An option-argument (character string) satisfying a pre- ceding argletter. Notice that groups of optargs follow- ing an argletter must be separated by commas, or sepa- rated by a tab or space character and quoted (Guideline 8, below). cmdarg Path name (or other command argument) not beginning with "-", or "-" by itself indicating the standard in- put. Unless otherwise specified, whenever an operand or option-argument is, or contains, a numeric value: o The number is interpreted as a decimal integer. o Numerals in the range 0 to 2147483647 are syntactically recognized as numeric values. o When the utility description states that it accepts negative num- bers as operands or option-arguments, numerals in the range -2147483647 to 2147483647 are syntactically recognized as numeric values. o Ranges greater than those listed here are allowed. Command Syntax Standard: Guidelines These command syntax guidelines are not followed by all current com- mands, but new commands are likely to obey them. getopts(1) should be used by all shell procedures to parse positional parameters and to check for legal options. It supports Guidelines 3-10 below. The en- forcement of the other guidelines must be done by the command itself. 1. Command names (name above) should be between two and nine charac- ters long. 2. Command names should include only lower-case letters and digits. 3. Option names (option above) must be one character long. 4. All options must be preceded by "-". 5. Options with no arguments can be grouped after a single "-". 6. The first option-argument (optarg above) following an option must be preceded by a tab or space character. 7. Option-arguments cannot be optional. 8. Groups of option-arguments following an option must either be sepa- rated by commas or separated by tab or space character and quoted (-o xxx,z,yy or -o"xxx z yy"). 9. All options must precede operands (cmdarg above) on the command line. 10. "--" can be used to indicate the end of the options. 11. The order of the options relative to one another should not matter. 12. The relative order of the operands (cmdarg above) can affect their significance in ways determined by the command with which they ap- pear. 13. "-" preceded and followed by a white space character should only be used to mean standard input. An expanded set of guidelines referred to as CLIP for Command Line In- terface Paradigm has been developed for Solaris and other Sun products. Its intent is to provide a command line syntax more closely aligned with the GNU command line syntax popular on Linux systems.There is no intent to retrofit existing utilities or even to apply this to all new utilities. It is only intended to be applied to sets of utilities being developed when appropriate. CLIP is a full superset of the guidelines discussed above which are closely aligned with IEEE Std. 1003.1-2001 (SUSv3). It does not include all the GNU syntax. The GNU syntax allows constructs that either con- flict with the IEEE rules or are ambiguous. These constructs are not allowed. The expanded CLIP command line syntax is: utility_name -a --longopt1 -c option_argument -f option_argument --longopt2=option_argument --longopt3 option_argument operand The utility in the example is named utility_name. It is followed by op- tions, option-arguments, and operands, collectively referred to as ar- guments. The arguments that consist of a hyphen followed a single let- ter or digit, such as -a, are known as short-options . The arguments that consist of two hyphens followed by a series of letters, digits and hyphens, such as --longopt1, are known as long-options . Collectively, short-options and long-options are referred to as options (or histori- cally, flags ). Certain options are followed by an option-argument, as shown with -c option_argument . The arguments following the last op- tions and option-arguments are named operands. Once the first operand is encountered, all subsequent arguments are interpreted to be oper- ands. Option-arguments are sometimes shown separated from their short-options by <BLANKS>s, sometimes directly adjacent. This reflects the situation that in some cases an option-argument is included within the same argu- ment string as the option; in most cases it is the next argument. This specification requires that the option be a separate argument from its option-argument, but there are some exceptions to ensure continued op- eration of historical applications: o If the SYNOPSIS of a utility shows a <SPACE> between a short-op- tion and option-argument (as with -c option_argument in the exam- ple), the application uses separate arguments for that option and its option-argument. o If a <SPACE> is not shown (as with -f option_argument in the exam- ple), the application expects an option and its option-argument directly adjacent in the same argument string, without intervening <BLANK>s. o Notwithstanding the preceding requirements, an application should accept short-options and option-arguments as a single argument or as separate arguments whether or not a <SPACE> is shown on the synopsis line. o Long-options with option-arguments are always documented as using an equals sign as the separator between the option name and the option-argument. If the OPTIONS section of a utility shows an equals sign (=) between a long-option and its option-argument (as with --longopt2= option_argument in the example), a application shall also permit the use of separate arguments for that option and its option-argument (as with --longopt1 option_argument in the example). CLIP expands the guidelines discussed with the following additional guidelines: 14. The form command subcommand [options] [operands] is appropri- ate for grouping similar operations. Subcommand names should follow the same conventions as command names as specified in guidelines 1 and 2. 15. Long-options should be preceded by -- and should include only alphanumeric characters and hyphens from the portable charac- ter set. Option names are typically one to three words long, with hyphens to separate words. 16. --name=argument should be used to specify an option-argument for a long-option. The form --name argument is also accepted. 17. All utilities should support two standard long-options: --ver- sion (with the short-option synonym -V ) and --help (with the short-option synonym -? ). The short option synonyms for --version can vary if the preferred synonym is already in use (but a synonym shall be provided). Both of these options stop further argument processing when encountered and after dis- playing the appropriate output, the utility successfully ex- its. 18. Every short-option should have exactly one corresponding long- option and every long-option should have exactly one corre- sponding short-option. Synonymous options can be allowed in the interest of compatibility with historical practice or com- munity versions of equivalent utilities. 19. The short-option name should get its name from the long-option name according to these rules: 1. Use the first letter of the long-option name for the short-option name. 2. If the first letter conflicts with other short-option names, choose a prominent consonant. 3. If the first letter and the prominent consonant con- flict with other shortoption names, choose a prominent vowel. 4. If none of the letters of the long-option name are us- able, select an arbitrary character. 20. If a long-option name consists of a single character, it must use the same character as the short-option name. Single char- acter long-options should be avoided. They are only allowed for the exceptionally rare case that a single character is the most descriptive name. 21. The subcommand in the form described in guideline 1 of the ad- ditional CLIP guidelines is generally required. In the case where it is omitted, the command shall take no operands and only options which are defined to stop further argument pro- cessing when encountered are allowed. Invoking a command of this form without a subcommand and no arguments is an error. This guideline is provided to allow the common forms command --help, command -?, command --version, and command -V to be accepted in the command-subcommand construct. Several of these guidelines are only of interest to the authors of utilities. They are provided here for the use of anyone wanting to au- thor utilities following this syntax. See attributes(5) for a discussion of the attributes listed in this section. getopts(1), wait(1), exit(2), getopt(3C), wait(3UCB), attributes(5) Upon termination, each command returns two bytes of status, one sup- plied by the system and giving the cause for termination, and (in the case of "normal" termination) one supplied by the program [see wait(3UCB) and exit(2)]. The former byte is 0 for normal termination. The latter byte is customarily 0 for successful execution and non-zero to indicate troubles such as erroneous parameters, or bad or inaccessi- ble data. It is called variously "exit code", "exit status", or "return code", and is described only where special conventions are involved. Some commands produce unexpected results when processing files contain- ing null characters. These commands often treat text input lines as strings and therefore become confused upon encountering a null charac- ter (the string terminator) within a line. 28 Sep 2005 Intro(1)
NAME
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=intro&sektion=1&manpath=SunOS+5.10>