Commit | Line | Data |
---|---|---|
7860c229 KB |
1 | .\" Copyright (c) 1988, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
53e9b2ee | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
006fcfe1 | 5 | .\" |
a892f3b0 | 6 | .\" @(#)getopt.3 8.4 (Berkeley) %G% |
53e9b2ee | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt GETOPT 3 | |
10 | .Os BSD 4.3 | |
11 | .Sh NAME | |
12 | .Nm getopt | |
924afea1 | 13 | .Nd get option character from command line argument list |
ae59e04c CL |
14 | .Sh SYNOPSIS |
15 | .Fd #include <stdlib.h> | |
a667724f KB |
16 | .Vt extern char *optarg; |
17 | .Vt extern int optind; | |
18 | .Vt extern int optopt; | |
19 | .Vt extern int opterr; | |
20 | .Vt extern int optreset; | |
ae59e04c CL |
21 | .Ft int |
22 | .Fn getopt "int argc" "char * const *argv" "const char *optstring" | |
23 | .Sh DESCRIPTION | |
24 | The | |
25 | .Fn getopt | |
924afea1 KB |
26 | function incrementally parses a command line argument list |
27 | .Fa argv | |
28 | and returns the next | |
ae59e04c | 29 | .Em known |
924afea1 | 30 | option character. |
ae59e04c CL |
31 | An option character is |
32 | .Em known | |
33 | if it has been specified in the string of accepted option characters, | |
34 | .Fa optstring . | |
35 | .Pp | |
36 | The option string | |
37 | .Fa optstring | |
924afea1 KB |
38 | may contain the following elements: individual characters, and |
39 | characters followed by a colon to indicate an option argument | |
660164a2 | 40 | is to follow. |
924afea1 KB |
41 | For example, an option string |
42 | .Li "\&""x"" | |
43 | recognizes an option | |
44 | .Dq Fl x , | |
45 | and an option string | |
46 | .Li "\&""x:"" | |
47 | recognizes an option and argument | |
48 | .Dq Fl x Ar argument . | |
49 | It does not matter to | |
ae59e04c CL |
50 | .Fn getopt |
51 | if a following argument has leading white space. | |
52 | .Pp | |
09885840 | 53 | On return from |
ae59e04c CL |
54 | .Fn getopt , |
55 | .Va optarg | |
56 | points to an option argument, if it is anticipated, | |
57 | and the variable | |
58 | .Va optind | |
59 | contains the index to the next | |
60 | .Fa argv | |
61 | argument for a subsequent call | |
62 | to | |
63 | .Fn getopt . | |
924afea1 KB |
64 | The variable |
65 | .Va optopt | |
66 | saves the last | |
67 | .Em known | |
68 | option character returned by | |
69 | .Fn getopt . | |
ae59e04c CL |
70 | .Pp |
71 | The variable | |
72 | .Va opterr | |
09885840 | 73 | and |
ae59e04c | 74 | .Va optind |
09885840 | 75 | are both initialized to 1. |
660164a2 MT |
76 | The |
77 | .Va optind | |
78 | variable may be set to another value before a set of calls to | |
79 | .Fn getopt | |
80 | in order to skip over more or less argv entries. | |
81 | .Pp | |
8fa9b88f | 82 | In order to use |
ae59e04c | 83 | .Fn getopt |
8fa9b88f KB |
84 | to evaluate multiple sets of arguments, or to evaluate a single set of |
85 | arguments multiple times, | |
660164a2 MT |
86 | the variable |
87 | .Va optreset | |
88 | must be set to 1 before the second and each additional set of calls to | |
89 | .Fn getopt , | |
90 | and the variable | |
ae59e04c | 91 | .Va optind |
660164a2 | 92 | must be reinitialized. |
ae59e04c CL |
93 | .Pp |
94 | The | |
95 | .Fn getopt | |
96 | function | |
97 | returns an | |
98 | .Dv EOF | |
99 | when the argument list is exhausted, or a non-recognized | |
100 | option is encountered. | |
101 | The interpretation of options in the argument list may be cancelled | |
102 | by the option | |
103 | .Ql -- | |
104 | (double dash) which causes | |
105 | .Fn getopt | |
106 | to signal the end of argument processing and return an | |
107 | .Dv EOF . | |
09885840 KB |
108 | When all options have been processed (i.e., up to the first non-option |
109 | argument), | |
ae59e04c CL |
110 | .Fn getopt |
111 | returns | |
112 | .Dv EOF . | |
113 | .Sh DIAGNOSTICS | |
114 | If the | |
115 | .Fn getopt | |
116 | function encounters a character not found in the string | |
117 | .Va optarg | |
118 | or detects | |
660164a2 | 119 | a missing option argument it writes an error message and returns |
ae59e04c CL |
120 | .Ql ? |
121 | to the | |
122 | .Em stderr . | |
09885840 | 123 | Setting |
ae59e04c | 124 | .Va opterr |
09885840 | 125 | to a zero will disable these error messages. |
660164a2 MT |
126 | If |
127 | .Va optstring | |
128 | has a leading | |
129 | .Ql \&: | |
a892f3b0 | 130 | then a missing option argument causes a |
660164a2 | 131 | .Ql \&: |
a892f3b0 | 132 | to be returned in addition to suppressing any error messages. |
660164a2 MT |
133 | .Pp |
134 | Option arguments are allowed to begin with | |
135 | .Dq Li \- ; | |
136 | this is reasonable but | |
137 | reduces the amount of error checking possible. | |
138 | .Sh EXTENSIONS | |
139 | The | |
140 | .Va optreset | |
141 | variable was added to make it possible to call the | |
142 | .Fn getopt | |
143 | function multiple times. | |
144 | This is an extension to the | |
145 | .St -p1003.2 | |
146 | specification. | |
ae59e04c CL |
147 | .Sh EXAMPLE |
148 | .Bd -literal -compact | |
09885840 KB |
149 | extern char *optarg; |
150 | extern int optind; | |
151 | int bflag, ch, fd; | |
152 | ||
153 | bflag = 0; | |
154 | while ((ch = getopt(argc, argv, "bf:")) != EOF) | |
155 | switch(ch) { | |
156 | case 'b': | |
157 | bflag = 1; | |
158 | break; | |
159 | case 'f': | |
160 | if ((fd = open(optarg, O_RDONLY, 0)) < 0) { | |
161 | (void)fprintf(stderr, | |
660164a2 MT |
162 | "myname: %s: %s\en", optarg, strerror(errno)); |
163 | exit(1); | |
53e9b2ee | 164 | } |
09885840 KB |
165 | break; |
166 | case '?': | |
167 | default: | |
168 | usage(); | |
ae59e04c | 169 | } |
09885840 KB |
170 | argc -= optind; |
171 | argv += optind; | |
ae59e04c CL |
172 | .Ed |
173 | .Sh HISTORY | |
174 | The | |
175 | .Fn getopt | |
176 | function appeared | |
177 | .Bx 4.3 . | |
178 | .Sh BUGS | |
ae59e04c CL |
179 | A single dash |
180 | .Dq Li - | |
181 | may be specified as an character in | |
182 | .Fa optstring , | |
09885840 | 183 | however it should |
ae59e04c | 184 | .Em never |
09885840 KB |
185 | have an argument associated with it. |
186 | This allows | |
ae59e04c CL |
187 | .Fn getopt |
188 | to be used with programs that expect | |
189 | .Dq Li - | |
190 | as an option flag. | |
09885840 KB |
191 | This practice is wrong, and should not be used in any current development. |
192 | It is provided for backward compatibility | |
ae59e04c | 193 | .Em only . |
dd71e7d8 | 194 | By default, a single dash causes |
ae59e04c CL |
195 | .Fn getopt |
196 | to return | |
197 | .Dv EOF . | |
dd71e7d8 | 198 | This is, we believe, compatible with System V. |
ae59e04c | 199 | .Pp |
09885840 KB |
200 | It is also possible to handle digits as option letters. |
201 | This allows | |
ae59e04c CL |
202 | .Fn getopt |
203 | to be used with programs that expect a number | |
204 | .Pq Dq Li \&-\&3 | |
205 | as an option. | |
09885840 KB |
206 | This practice is wrong, and should not be used in any current development. |
207 | It is provided for backward compatibility | |
ae59e04c | 208 | .Em only . |
660164a2 | 209 | The following code fragment works in most cases. |
ae59e04c | 210 | .Bd -literal -offset indent |
09885840 KB |
211 | int length; |
212 | char *p; | |
7edf3dad | 213 | |
09885840 KB |
214 | while ((c = getopt(argc, argv, "0123456789")) != EOF) |
215 | switch (c) { | |
216 | case '0': case '1': case '2': case '3': case '4': | |
217 | case '5': case '6': case '7': case '8': case '9': | |
218 | p = argv[optind - 1]; | |
219 | if (p[0] == '-' && p[1] == ch && !p[2]) | |
220 | length = atoi(++p); | |
221 | else | |
222 | length = atoi(argv[optind] + 1); | |
223 | break; | |
7edf3dad | 224 | } |
09885840 | 225 | } |
ae59e04c | 226 | .Ed |