Commit | Line | Data |
---|---|---|
7a2ca3d7 NW |
1 | .Dd June 21, 1993 |
2 | .Dt GETOPT 1 | |
3 | .Os | |
4 | .Sh NAME | |
5 | .Nm getopt | |
6 | .Nd parse command options | |
7 | .Sh SYNOPSIS | |
8 | .Nm set \-\- \`getopt optstring $*\` | |
9 | .Sh DESCRIPTION | |
10 | .Nm Getopt | |
11 | is used to break up options in command lines for easy parsing by | |
12 | shell procedures, and to check for legal options. | |
13 | .Op Optstring | |
14 | is a string of recognized option letters (see | |
15 | .Xr getopt 3 | |
16 | ); | |
17 | if a letter is followed by a colon, the option | |
18 | is expected to have an argument which may or may not be | |
19 | separated from it by white space. | |
20 | The special option | |
21 | .B \-\- | |
22 | is used to delimit the end of the options. | |
23 | .Nm Getopt | |
24 | will place | |
25 | .B \-\- | |
26 | in the arguments at the end of the options, | |
27 | or recognize it if used explicitly. | |
28 | The shell arguments | |
29 | (\fB$1 $2\fR ...) are reset so that each option is | |
30 | preceded by a | |
31 | .B \- | |
32 | and in its own shell argument; | |
33 | each option argument is also in its own shell argument. | |
34 | .Sh EXAMPLE | |
35 | The following code fragment shows how one might process the arguments | |
36 | for a command that can take the options | |
37 | .Op a | |
38 | and | |
39 | .Op b , | |
40 | and the option | |
41 | .Op o , | |
42 | which requires an argument. | |
43 | .Pp | |
44 | .Bd -literal -offset indent | |
45 | set \-\- \`getopt abo: $*\` | |
46 | if test $? != 0 | |
47 | then | |
48 | echo 'Usage: ...' | |
49 | exit 2 | |
50 | fi | |
51 | for i | |
52 | do | |
53 | case "$i" | |
54 | in | |
55 | \-a|\-b) | |
56 | flag=$i; shift;; | |
57 | \-o) | |
58 | oarg=$2; shift; shift;; | |
59 | \-\-) | |
60 | shift; break;; | |
61 | esac | |
62 | done | |
63 | .Ed | |
64 | .Pp | |
65 | This code will accept any of the following as equivalent: | |
66 | .Pp | |
67 | .Bd -literal -offset indent | |
68 | cmd \-aoarg file file | |
69 | cmd \-a \-o arg file file | |
70 | cmd \-oarg -a file file | |
71 | cmd \-a \-oarg \-\- file file | |
72 | .Ed | |
73 | .Sh SEE ALSO | |
74 | .Xr sh 1 , | |
75 | .Xr getopt 3 | |
76 | .Sh DIAGNOSTICS | |
77 | .Nm Getopt | |
78 | prints an error message on the standard error output when it | |
79 | encounters an option letter not included in | |
80 | .Op optstring . | |
81 | .Sh HISTORY | |
82 | Written by Henry Spencer, working from a Bell Labs manual page. | |
83 | Behavior believed identical to the Bell version. | |
84 | .Sh BUGS | |
85 | Whatever | |
86 | .Xr getopt 3 | |
87 | has. | |
88 | .Pp | |
89 | Arguments containing white space or imbedded shell metacharacters | |
90 | generally will not survive intact; this looks easy to fix but isn't. | |
91 | .Pp | |
92 | The error message for an invalid option is identified as coming | |
93 | from | |
94 | .Nm getopt | |
95 | rather than from the shell procedure containing the invocation | |
96 | of | |
97 | .Nm getopt ; | |
98 | this again is hard to fix. | |
99 | .Pp | |
100 | The precise best way to use the | |
101 | .Nm set | |
102 | command to set the arguments without disrupting the value(s) of | |
103 | shell options varies from one shell version to another. |