1Intro(1) User Commands Intro(1)
2
6 Intro, intro - introduction to commands and application programs
7
9 This section describes, in alphabetical order, commands available with
10 this operating system.
11 Pages of special interest are categorized as follows:
14 1B Commands found only in the SunOS/BSD Compatibility Package.
16 1C Commands for communicating with other systems.
19 1F Commands associated with Form and Menu Language Interpreter
22 (FMLI).
23 1S Commands specific to SunOS.
26 OTHER SECTIONS
29 See the following sections of the SunOS Reference Manual for more
30 information.
31 o Section 1M for system maintenance commands.
33 o Section 4 for information on file formats.
35 o Section 5 for descriptions of publicly available files and
37 miscellaneous information pages.
38 For tutorial information about these commands and procedures, see
41 Solaris Advanced User's Guide.
42 Manual Page Command Syntax
44 Unless otherwise noted, commands described in the SYNOPSIS section of a
45 manual page accept options and other arguments according to the follow‐
46 ing syntax and should be interpreted as explained below.
47 name [-option...] [cmdarg...] where:
50 [ ] Surround an option or cmdarg that is not required.
52 ... Indicates multiple occurrences of the option or cmdarg.
55 name The name of an executable file.
58 { } The options and/or arguments enclosed within braces are
61 interdependent, such that everything enclosed must be
62 treated as a unit.
63 option (Always preceded by a "−".) noargletter... or, argletter
66 optarg[,...]
67 noargletter A single letter representing an option without an
70 option-argument. Notice that more than one noargletter
71 option can be grouped after one "−" (Guideline 5,
72 below).
73 argletter A single letter representing an option requiring an
76 option-argument.
77 optarg An option-argument (character string) satisfying a pre‐
80 ceding argletter. Notice that groups of optargs follow‐
81 ing an argletter must be separated by commas, or sepa‐
82 rated by a tab or space character and quoted (Guideline
83 8, below).
84 cmdarg Path name (or other command argument) not beginning with
87 "−", or "−" by itself indicating the standard input.
88 Unless otherwise specified, whenever an operand or option-argument is,
92 or contains, a numeric value:
93 o The number is interpreted as a decimal integer.
95 o Numerals in the range 0 to 2147483647 are syntactically rec‐
97 ognized as numeric values.
98 o When the utility description states that it accepts negative
100 numbers as operands or option-arguments, numerals in the
101 range -2147483647 to 2147483647 are syntactically recognized
102 as numeric values.
103 o Ranges greater than those listed here are allowed.
105 Command Syntax Standard: Guidelines
107 These command syntax guidelines are not followed by all current com‐
108 mands, but new commands are likely to obey them. getopts(1) should be
109 used by all shell procedures to parse positional parameters and to
110 check for legal options. It supports Guidelines 3-10 below. The
111 enforcement of the other guidelines must be done by the command itself.
112 1. Command names (name above) should be between two and nine
114 characters long.
115 2. Command names should include only lower-case letters and
117 digits.
118 3. Option names (option above) must be one character long.
120 4. All options must be preceded by "−".
122 5. Options with no arguments can be grouped after a single "−".
124 6. The first option-argument (optarg above) following an option
126 must be preceded by a tab or space character.
127 7. Option-arguments cannot be optional.
129 8. Groups of option-arguments following an option must either
131 be separated by commas or separated by tab or space charac‐
132 ter and quoted (-o xxx,z,yy or -o"xxx z yy").
133 9. All options must precede operands (cmdarg above) on the com‐
135 mand line.
136 10. "−−" can be used to indicate the end of the options.
138 11. The order of the options relative to one another should not
140 matter.
141 12. The relative order of the operands (cmdarg above) can affect
143 their significance in ways determined by the command with
144 which they appear.
145 13. "−" preceded and followed by a white space character should
147 only be used to mean standard input.
148 An expanded set of guidelines referred to as CLIP for Command Line
151 Interface Paradigm has been developed for Solaris and other Sun prod‐
152 ucts. Its intent is to provide a command line syntax more closely
153 aligned with the GNU command line syntax popular on Linux systems.There
154 is no intent to retrofit existing utilities or even to apply this to
155 all new utilities. It is only intended to be applied to sets of utili‐
156 ties being developed when appropriate.
157 CLIP is a full superset of the guidelines discussed above which are
160 closely aligned with IEEE Std. 1003.1-2001 (SUSv3). It does not include
161 all the GNU syntax. The GNU syntax allows constructs that either con‐
162 flict with the IEEE rules or are ambiguous. These constructs are not
163 allowed.
164 The expanded CLIP command line syntax is:
167 utility_name -a --longopt1 -c option_argument \
169 -f option_argument --longopt2=option_argument \
170 --longopt3 option_argument operand
171 The utility in the example is named utility_name. It is followed by
176 options, option-arguments, and operands, collectively referred to as
177 arguments. The arguments that consist of a hyphen followed a single
178 letter or digit, such as -a, are known as short-options . The arguments
179 that consist of two hyphens followed by a series of letters, digits and
180 hyphens, such as --longopt1, are known as long-options . Collectively,
181 short-options and long-options are referred to as options (or histori‐
182 cally, flags ). Certain options are followed by an option-argument, as
183 shown with -c option_argument . The arguments following the last
184 options and option-arguments are named operands. Once the first operand
185 is encountered, all subsequent arguments are interpreted to be oper‐
186 ands.
187 Option-arguments are sometimes shown separated from their short-options
190 by BLANKSs, sometimes directly adjacent. This reflects the situation
191 that in some cases an option-argument is included within the same argu‐
192 ment string as the option; in most cases it is the next argument. This
193 specification requires that the option be a separate argument from its
194 option-argument, but there are some exceptions to ensure continued
195 operation of historical applications:
196 o If the SYNOPSIS of a utility shows a SPACE between a short-
198 option and option-argument (as with -c option_argument in
199 the example), the application uses separate arguments for
200 that option and its option-argument.
201 o If a SPACE is not shown (as with -f option_argument in the
203 example), the application expects an option and its option-
204 argument directly adjacent in the same argument string,
205 without intervening BLANKs.
206 o Notwithstanding the preceding requirements, an application
208 should accept short-options and option-arguments as a single
209 argument or as separate arguments whether or not a SPACE is
210 shown on the synopsis line.
211 o Long-options with option-arguments are always documented as
213 using an equals sign as the separator between the option
214 name and the option-argument. If the OPTIONS section of a
215 utility shows an equals sign (=) between a long-option and
216 its option-argument (as with --longopt2= option_argument in
217 the example), a application shall also permit the use of
218 separate arguments for that option and its option-argument
219 (as with --longopt1 option_argument in the example).
220 CLIP expands the guidelines discussed with the following additional
223 guidelines:
224 14. The form command subcommand [options] [operands] is appropriate
226 for grouping similar operations. Subcommand names should follow
227 the same conventions as command names as specified in guidelines
228 1 and 2.
229 15. Long-options should be preceded by -- and should include only
232 alphanumeric characters and hyphens from the portable character
233 set. Option names are typically one to three words long, with
234 hyphens to separate words.
235 16. --name=argument should be used to specify an option-argument for
238 a long-option. The form --name argument is also accepted.
239 17. All utilities should support two standard long-options: --ver‐
242 sion (with the short-option synonym -V ) and --help (with the
243 short-option synonym -? ). The short option synonyms for --ver‐
244 sion can vary if the preferred synonym is already in use (but a
245 synonym shall be provided). Both of these options stop further
246 argument processing when encountered and after displaying the
247 appropriate output, the utility successfully exits.
248 18. Every short-option should have exactly one corresponding long-
251 option and every long-option should have exactly one correspond‐
252 ing short-option. Synonymous options can be allowed in the
253 interest of compatibility with historical practice or community
254 versions of equivalent utilities.
255 19. The short-option name should get its name from the long-option
258 name according to these rules:
259 1. Use the first letter of the long-option name for the
261 short-option name.
262 2. If the first letter conflicts with other short-option
264 names, choose a prominent consonant.
265 3. If the first letter and the prominent consonant con‐
267 flict with other shortoption names, choose a promi‐
268 nent vowel.
269 4. If none of the letters of the long-option name are
271 usable, select an arbitrary character.
272 20. If a long-option name consists of a single character, it must
275 use the same character as the short-option name. Single charac‐
276 ter long-options should be avoided. They are only allowed for
277 the exceptionally rare case that a single character is the most
278 descriptive name.
279 21. The subcommand in the form described in guideline 1 of the addi‐
282 tional CLIP guidelines is generally required. In the case where
283 it is omitted, the command shall take no operands and only
284 options which are defined to stop further argument processing
285 when encountered are allowed. Invoking a command of this form
286 without a subcommand and no arguments is an error. This guide‐
287 line is provided to allow the common forms command --help, com‐
288 mand -?, command --version, and command -V to be accepted in the
289 command-subcommand construct.
290 Several of these guidelines are only of interest to the authors of
294 utilities. They are provided here for the use of anyone wanting to
295 author utilities following this syntax.
296
298 See attributes(5) for a discussion of the attributes listed in this
299 section.
300
302 Sun Microsystems, Inc. gratefully acknowledges The Open Group for per‐
303 mission to reproduce portions of its copyrighted documentation. Origi‐
304 nal documentation from The Open Group can be obtained online at
305 http://www.opengroup.org/bookstore/.
306 The Institute of Electrical and Electronics Engineers and The Open
309 Group, have given us permission to reprint portions of their documenta‐
310 tion.
311 In the following statement, the phrase ``this text'' refers to portions
314 of the system documentation.
315 Portions of this text are reprinted and reproduced in electronic form
318 in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
319 Standard for Information Technology -- Portable Operating System Inter‐
320 face (POSIX), The Open Group Base Specifications Issue 6, Copyright (C)
321 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc
322 and The Open Group. In the event of any discrepancy between these ver‐
323 sions and the original IEEE and The Open Group Standard, the original
324 IEEE and The Open Group Standard is the referee document. The original
325 Standard can be obtained online at http://www.open‐
326 group.org/unix/online.html.
327 This notice shall appear on any product containing this material.
330
332 getopts(1), wait(1), exit(2), getopt(3C), wait(3UCB), attributes(5)
333
335 Upon termination, each command returns two bytes of status, one sup‐
336 plied by the system and giving the cause for termination, and (in the
337 case of "normal" termination) one supplied by the program [see
338 wait(3UCB) and exit(2)]. The former byte is 0 for normal termination.
339 The latter byte is customarily 0 for successful execution and non-zero
340 to indicate troubles such as erroneous parameters, or bad or inaccessi‐
341 ble data. It is called variously "exit code", "exit status", or "return
342 code", and is described only where special conventions are involved.
343
345 Some commands produce unexpected results when processing files contain‐
346 ing null characters. These commands often treat text input lines as
347 strings and therefore become confused upon encountering a null charac‐
348 ter (the string terminator) within a line.
349SunOS 5.11 18 Nov 2008 Intro(1)