| blob | 72236e492610d57a5c08a7fd606000dc60ea84c6 |
1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH INTRO 1 "May 13, 2017"
8 .SH NAME
9 Intro, intro \- introduction to commands and application programs
10 .SH DESCRIPTION
11 .LP
12 This section describes, in alphabetical order, commands available with this
13 operating system.
14 .sp
15 .LP
16 Pages of special interest are categorized as follows:
17 .sp
18 .ne 2
19 .na
20 \fB1B\fR
21 .ad
22 .RS 6n
23 Commands found only in the \fISunOS/BSD Compatibility Package\fR.
24 .RE
26 .sp
27 .ne 2
28 .na
29 \fB1C\fR
30 .ad
31 .RS 6n
32 Commands for communicating with other systems.
33 .RE
35 .sp
36 .ne 2
37 .na
38 \fB1S\fR
39 .ad
40 .RS 6n
41 Commands specific to SunOS.
42 .RE
44 .SS "OTHER SECTIONS"
45 .LP
46 See the following sections of the SunOS Reference Manual for more information.
47 .RS +4
48 .TP
49 .ie t \(bu
50 .el o
51 Section 1M for system maintenance commands.
52 .RE
53 .RS +4
54 .TP
55 .ie t \(bu
56 .el o
57 Section 4 for information on file formats.
58 .RE
59 .RS +4
60 .TP
61 .ie t \(bu
62 .el o
63 Section 5 for descriptions of publicly available files and miscellaneous
64 information pages.
65 .RE
66 .sp
67 .LP
68 For tutorial information about these commands and procedures, see \fISolaris
69 Advanced User\&'s Guide\fR.
70 .SS "Manual Page Command Syntax"
71 .LP
72 Unless otherwise noted, commands described in the SYNOPSIS section of a manual
73 page accept options and other arguments according to the following syntax and
74 should be interpreted as explained below.
75 .sp
76 .LP
77 \fIname\fR [\fB-\fR\fIoption\fR...] [\fIcmdarg\fR...] where:
78 .sp
79 .ne 2
80 .na
81 \fB[ ]\fR
82 .ad
83 .RS 15n
84 Surround an \fIoption\fR or \fIcmdarg\fR that is not required.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fI\&...\fR\fR
91 .ad
92 .RS 15n
93 Indicates multiple occurrences of the \fIoption\fR or \fIcmdarg\fR.
94 .RE
96 .sp
97 .ne 2
98 .na
99 \fB\fIname\fR\fR
100 .ad
101 .RS 15n
102 The name of an executable file.
103 .RE
105 .sp
106 .ne 2
107 .na
108 \fB{ }\fR
109 .ad
110 .RS 15n
111 The options and/or arguments enclosed within braces are interdependent, such
112 that everything enclosed must be treated as a unit.
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fB\fIoption\fR\fR
119 .ad
120 .RS 15n
121 (Always preceded by a "\(mi".) \fInoargletter\fR... or, \fIargletter\fR
122 \fIoptarg\fR[\fB,\fR...]
123 .RE
125 .sp
126 .ne 2
127 .na
128 \fB\fInoargletter\fR\fR
129 .ad
130 .RS 15n
131 A single letter representing an option without an option-argument. Notice that
132 more than one \fInoargletter\fR option can be grouped after one "\(mi"
133 (Guideline 5, below).
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fIargletter\fR\fR
140 .ad
141 .RS 15n
142 A single letter representing an option requiring an option-argument.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fIoptarg\fR\fR
149 .ad
150 .RS 15n
151 An option-argument (character string) satisfying a preceding \fIargletter\fR.
152 Notice that groups of \fIoptargs\fR following an \fIargletter\fR must be
153 separated by commas, or separated by a tab or space character and quoted
154 (Guideline 8, below).
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fIcmdarg\fR\fR
161 .ad
162 .RS 15n
163 Path name (or other command argument) \fInot\fR beginning with "\(mi", or
164 "\(mi" by itself indicating the standard input.
165 .RE
167 .sp
168 .LP
169 Unless otherwise specified, whenever an operand or option-argument is, or
170 contains, a numeric value:
171 .RS +4
172 .TP
173 .ie t \(bu
174 .el o
175 The number is interpreted as a decimal integer.
176 .RE
177 .RS +4
178 .TP
179 .ie t \(bu
180 .el o
181 Numerals in the range 0 to 2147483647 are syntactically recognized as numeric
182 values.
183 .RE
184 .RS +4
185 .TP
186 .ie t \(bu
187 .el o
188 When the utility description states that it accepts negative numbers as
189 operands or option-arguments, numerals in the range -2147483647 to 2147483647
190 are syntactically recognized as numeric values.
191 .RE
192 .RS +4
193 .TP
194 .ie t \(bu
195 .el o
196 Ranges greater than those listed here are allowed.
197 .RE
198 .SS "Command Syntax Standard: Guidelines"
199 .LP
200 These command syntax guidelines are not followed by all current commands, but
201 new commands are likely to obey them. \fBgetopts\fR(1) should be used by all
202 shell procedures to parse positional parameters and to check for legal options.
203 It supports Guidelines 3-10 below. The enforcement of the other guidelines must
204 be done by the command itself.
205 .RS +4
206 .TP
207 1.
208 Command names (\fIname\fR above) should be between two and nine characters
209 long.
210 .RE
211 .RS +4
212 .TP
213 2.
214 Command names should include only lower-case letters and digits.
215 .RE
216 .RS +4
217 .TP
218 3.
219 Option names (\fIoption\fR above) must be one character long.
220 .RE
221 .RS +4
222 .TP
223 4.
224 All options must be preceded by "\(mi".
225 .RE
226 .RS +4
227 .TP
228 5.
229 Options with no arguments can be grouped after a single "\(mi".
230 .RE
231 .RS +4
232 .TP
233 6.
234 The first option-argument (\fIoptarg\fR above) following an option must be
235 preceded by a tab or space character.
236 .RE
237 .RS +4
238 .TP
239 7.
240 Option-arguments cannot be optional.
241 .RE
242 .RS +4
243 .TP
244 8.
245 Groups of option-arguments following an option must either be separated by
246 commas or separated by tab or space character and quoted (\fB-o\fR xxx,z,yy or
247 \fB-o\fR"xxx z yy").
248 .RE
249 .RS +4
250 .TP
251 9.
252 All options must precede operands (\fIcmdarg\fR above) on the command line.
253 .RE
254 .RS +4
255 .TP
256 10.
257 "\(mi\|\(mi" can be used to indicate the end of the options.
258 .RE
259 .RS +4
260 .TP
261 11.
262 The order of the options relative to one another should not matter.
263 .RE
264 .RS +4
265 .TP
266 12.
267 The relative order of the operands (\fIcmdarg\fR above) can affect their
268 significance in ways determined by the command with which they appear.
269 .RE
270 .RS +4
271 .TP
272 13.
273 "\(mi" preceded and followed by a white space character should only be used
274 to mean standard input.
275 .RE
276 .sp
277 .LP
278 An expanded set of guidelines referred to as CLIP for Command Line Interface
279 Paradigm has been developed for Solaris and other Sun products. Its intent is
280 to provide a command line syntax more closely aligned with the GNU command line
281 syntax popular on Linux systems.There is no intent to retrofit existing
282 utilities or even to apply this to all new utilities. It is only intended to be
283 applied to sets of utilities being developed when appropriate.
284 .sp
285 .LP
286 CLIP is a full superset of the guidelines discussed above which are closely
287 aligned with IEEE Std. 1003.1-2001 (SUSv3). It does not include all the GNU
288 syntax. The GNU syntax allows constructs that either conflict with the IEEE
289 rules or are ambiguous. These constructs are not allowed.
290 .sp
291 .LP
292 The expanded CLIP command line syntax is:
293 .sp
294 .in +2
295 .nf
296 utility_name -a --longopt1 -c option_argument \e
297 -f option_argument --longopt2=option_argument \e
298 --longopt3 option_argument operand
299 .fi
300 .in -2
301 .sp
303 .sp
304 .LP
305 The utility in the example is named \fButility_name\fR. It is followed by
306 options, option-arguments, and operands, collectively referred to as arguments.
307 The arguments that consist of a hyphen followed a single letter or digit, such
308 as \fB-a\fR, are known as short-options \&. The arguments that consist of two
309 hyphens followed by a series of letters, digits and hyphens, such as
310 \fB--longopt1\fR, are known as long-options . Collectively, short-options and
311 long-options are referred to as options (or historically, flags ). Certain
312 options are followed by an option-argument, as shown with \fB-c\fR
313 option_argument . The arguments following the last options and option-arguments
314 are named operands. Once the first operand is encountered, all subsequent
315 arguments are interpreted to be operands.
316 .sp
317 .LP
318 Option-arguments are sometimes shown separated from their short-options by
319 BLANKSs, sometimes directly adjacent. This reflects the situation that in some
320 cases an option-argument is included within the same argument string as the
321 option; in most cases it is the next argument. This specification requires that
322 the option be a separate argument from its option-argument, but there are some
323 exceptions to ensure continued operation of historical applications:
324 .RS +4
325 .TP
326 .ie t \(bu
327 .el o
328 If the \fBSYNOPSIS\fR of a utility shows a SPACE between a short-option and
329 option-argument (as with \fB-c\fR option_argument in the example), the
330 application uses separate arguments for that option and its option-argument.
331 .RE
332 .RS +4
333 .TP
334 .ie t \(bu
335 .el o
336 If a SPACE is not shown (as with \fB-f\fR option_argument in the example), the
337 application expects an option and its option-argument directly adjacent in the
338 same argument string, without intervening BLANKs.
339 .RE
340 .RS +4
341 .TP
342 .ie t \(bu
343 .el o
344 Notwithstanding the preceding requirements, an application should accept
345 short-options and option-arguments as a single argument or as separate
346 arguments whether or not a SPACE is shown on the synopsis line.
347 .RE
348 .RS +4
349 .TP
350 .ie t \(bu
351 .el o
352 Long-options with option-arguments are always documented as using an equals
353 sign as the separator between the option name and the option-argument. If the
354 \fBOPTIONS\fR section of a utility shows an equals sign (\fB=\fR) between a
355 long-option and its option-argument (as with \fB--longopt2= option_argument\fR
356 in the example), a application shall also permit the use of separate arguments
357 for that option and its option-argument (as with \fB--longopt1
358 option_argument\fR in the example).
359 .RE
360 .sp
361 .LP
362 CLIP expands the guidelines discussed with the following additional guidelines:
363 .sp
364 .ne 2
365 .na
366 \fB14.\fR
367 .ad
368 .RS 7n
369 The form \fBcommand subcommand [options] [operands]\fR is appropriate for
370 grouping similar operations. Subcommand names should follow the same
371 conventions as command names as specified in guidelines 1 and 2.
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB15.\fR
378 .ad
379 .RS 7n
380 Long-options should be preceded by \fB--\fR and should include only
381 alphanumeric characters and hyphens from the portable character set. Option
382 names are typically one to three words long, with hyphens to separate words.
383 .RE
385 .sp
386 .ne 2
387 .na
388 \fB16.\fR
389 .ad
390 .RS 7n
391 \fB--name=argument\fR should be used to specify an option-argument for a
392 long-option. The form \fB--name argument\fR is also accepted.
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fB17.\fR
399 .ad
400 .RS 7n
401 All utilities should support two standard long-options: \fB--version\fR (with
402 the short-option synonym \fB-V\fR ) and \fB--help\fR (with the short-option
403 synonym \fB-?\fR ). The short option synonyms for \fB--\fRversion can vary if
404 the preferred synonym is already in use (but a synonym shall be provided).
405 Both of these options stop further argument processing when encountered and
406 after displaying the appropriate output, the utility successfully exits.
407 .RE
409 .sp
410 .ne 2
411 .na
412 \fB18.\fR
413 .ad
414 .RS 7n
415 Every short-option should have exactly one corresponding long-option and every
416 long-option should have exactly one corresponding short-option. Synonymous
417 options can be allowed in the interest of compatibility with historical
418 practice or community versions of equivalent utilities.
419 .RE
421 .sp
422 .ne 2
423 .na
424 \fB19.\fR
425 .ad
426 .RS 7n
427 The short-option name should get its name from the long-option name according
428 to these rules:
429 .RS +4
430 .TP
431 1.
432 Use the first letter of the long-option name for the short-option name.
433 .RE
434 .RS +4
435 .TP
436 2.
437 If the first letter conflicts with other short-option names, choose a
438 prominent consonant.
439 .RE
440 .RS +4
441 .TP
442 3.
443 If the first letter and the prominent consonant conflict with other
444 shortoption names, choose a prominent vowel.
445 .RE
446 .RS +4
447 .TP
448 4.
449 If none of the letters of the long-option name are usable, select an
450 arbitrary character.
451 .RE
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB20.\fR
458 .ad
459 .RS 7n
460 If a long-option name consists of a single character, it must use the same
461 character as the short-option name. Single character long-options should be
462 avoided. They are only allowed for the exceptionally rare case that a single
463 character is the most descriptive name.
464 .RE
466 .sp
467 .ne 2
468 .na
469 \fB21.\fR
470 .ad
471 .RS 7n
472 The subcommand in the form described in guideline 1 of the additional CLIP
473 guidelines is generally required. In the case where it is omitted, the command
474 shall take no operands and only options which are defined to stop further
475 argument processing when encountered are allowed. Invoking a command of this
476 form without a subcommand and no arguments is an error. This guideline is
477 provided to allow the common forms command \fB--help\fR, command \fB-?\fR,
478 command \fB--version\fR, and command \fB-V\fR to be accepted in the
479 command-subcommand construct.
480 .RE
482 .sp
483 .LP
484 Several of these guidelines are only of interest to the authors of utilities.
485 They are provided here for the use of anyone wanting to author utilities
486 following this syntax.
487 .SH ATTRIBUTES
488 .LP
489 See \fBattributes\fR(5) for a discussion of the attributes listed in this
490 section.
491 .SH ACKNOWLEDGMENTS
492 .LP
493 Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to
494 reproduce portions of its copyrighted documentation. Original documentation
495 from The Open Group can be obtained online at
496 http://www.opengroup.org/bookstore/\&.
497 .sp
498 .LP
499 The Institute of Electrical and Electronics Engineers and The Open Group, have
500 given us permission to reprint portions of their documentation.
501 .sp
502 .LP
503 In the following statement, the phrase ``this text'' refers to portions of the
504 system documentation.
505 .sp
506 .LP
507 Portions of this text are reprinted and reproduced in electronic form in the
508 SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for
509 Information Technology -- Portable Operating System Interface (POSIX), The Open
510 Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
511 Electrical and Electronics Engineers, Inc and The Open Group. In the event of
512 any discrepancy between these versions and the original IEEE and The Open Group
513 Standard, the original IEEE and The Open Group Standard is the referee
514 document. The original Standard can be obtained online at
515 http://www.opengroup.org/unix/online.html\&.
516 .sp
517 .LP
518 This notice shall appear on any product containing this material.
519 .SH SEE ALSO
520 .LP
521 \fBgetopts\fR(1), \fBwait\fR(1), \fBexit\fR(2), \fBgetopt\fR(3C),
522 \fBattributes\fR(5)
523 .SH DIAGNOSTICS
524 .LP
525 Upon termination, each command returns two bytes of status, one supplied by the
526 system and giving the cause for termination, and (in the case of "normal"
527 termination) one supplied by the program [see
528 \fBexit\fR(2)]. The former byte is \fB0\fR for normal termination. The latter
529 byte is customarily \fB0\fR for successful execution and non-zero to indicate
530 troubles such as erroneous parameters, or bad or inaccessible data. It is
531 called variously "exit code", "exit status", or "return code", and is described
532 only where special conventions are involved.
533 .SH WARNINGS
534 .LP
535 Some commands produce unexpected results when processing files containing null
536 characters. These commands often treat text input lines as strings and
537 therefore become confused upon encountering a null character (the string
538 terminator) within a line.