Commit | Line | Data |
---|---|---|
006fcfe1 KB |
1 | .\" Copyright (c) 1988 Regents of the University of California. |
2 | .\" All rights reserved. | |
53e9b2ee | 3 | .\" |
006fcfe1 | 4 | .\" Redistribution and use in source and binary forms are permitted |
57a981eb KB |
5 | .\" provided that the above copyright notice and this paragraph are |
6 | .\" duplicated in all such forms and that any documentation, | |
7 | .\" advertising materials, and other materials related to such | |
8 | .\" distribution and use acknowledge that the software was developed | |
9 | .\" by the University of California, Berkeley. The name of the | |
10 | .\" University may not be used to endorse or promote products derived | |
11 | .\" from this software without specific prior written permission. | |
12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
14 | .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
006fcfe1 | 15 | .\" |
85fde6c7 | 16 | .\" @(#)getopt.3 6.11 (Berkeley) %G% |
53e9b2ee KM |
17 | .\" |
18 | .TH GETOPT 3 "" | |
19 | .UC 6 | |
20 | .SH NAME | |
21 | getopt \- get option letter from argv | |
22 | .SH SYNOPSIS | |
23 | .ft B | |
24 | int getopt(argc, argv, optstring) | |
25 | .br | |
26 | int argc; | |
27 | .br | |
28 | char **argv; | |
29 | .br | |
30 | char *optstring; | |
31 | .sp | |
32 | extern char *optarg; | |
33 | .br | |
34 | extern int optind; | |
0b64d222 KB |
35 | .br |
36 | extern int opterr; | |
53e9b2ee KM |
37 | .ft |
38 | .SH DESCRIPTION | |
39 | .I Getopt | |
40 | returns the next option letter in | |
41 | .I argv | |
42 | that matches a letter in | |
43 | .IR optstring . | |
44 | .I Optstring | |
45 | is a string of recognized option letters; | |
46 | if a letter is followed by a colon, the option is expected to have | |
47 | an argument that may or may not be separated from it by white space. | |
48 | .I Optarg | |
49 | is set to point to the start of the option argument on return from | |
50 | .IR getopt . | |
51 | .PP | |
52 | .I Getopt | |
53 | places in | |
54 | .I optind | |
55 | the | |
56 | .I argv | |
57 | index of the next argument to be processed. | |
58 | Because | |
59 | .I optind | |
60 | is external, it is normally initialized to zero automatically | |
61 | before the first call to | |
62 | .IR getopt . | |
63 | .PP | |
64 | When all options have been processed (i.e., up to the first | |
65 | non-option argument), | |
66 | .I getopt | |
67 | returns | |
68 | .BR EOF . | |
69 | The special option | |
70 | .B \-\- | |
71 | may be used to delimit the end of the options; | |
72 | .B EOF | |
73 | will be returned, and | |
74 | .B \-\- | |
75 | will be skipped. | |
53e9b2ee KM |
76 | .SH DIAGNOSTICS |
77 | .I Getopt | |
78 | prints an error message on | |
79 | .I stderr | |
80 | and returns a question mark | |
81 | .RB ( ? ) | |
82 | when it encounters an option letter not included in | |
83 | .IR optstring . | |
0b64d222 | 84 | Setting \fIopterr\fP to a zero will disable this error message. |
53e9b2ee KM |
85 | .SH EXAMPLE |
86 | The following code fragment shows how one might process the arguments | |
87 | for a command that can take the mutually exclusive options | |
88 | .B a | |
89 | and | |
90 | .BR b , | |
91 | and the options | |
92 | .B f | |
93 | and | |
94 | .BR o , | |
95 | both of which require arguments: | |
96 | .PP | |
97 | .RS | |
98 | .nf | |
99 | main(argc, argv) | |
100 | int argc; | |
101 | char **argv; | |
102 | { | |
103 | int c; | |
104 | extern int optind; | |
105 | extern char *optarg; | |
106 | \&. | |
107 | \&. | |
108 | \&. | |
109 | while ((c = getopt(argc, argv, "abf:o:")) != EOF) | |
110 | switch (c) { | |
6a0eb6c6 | 111 | case `a': |
53e9b2ee KM |
112 | if (bflg) |
113 | errflg++; | |
114 | else | |
115 | aflg++; | |
116 | break; | |
6a0eb6c6 | 117 | case `b': |
53e9b2ee KM |
118 | if (aflg) |
119 | errflg++; | |
120 | else | |
121 | bproc(); | |
122 | break; | |
6a0eb6c6 | 123 | case `f': |
53e9b2ee KM |
124 | ifile = optarg; |
125 | break; | |
6a0eb6c6 | 126 | case `o': |
53e9b2ee KM |
127 | ofile = optarg; |
128 | break; | |
6a0eb6c6 | 129 | case `?': |
53e9b2ee KM |
130 | default: |
131 | errflg++; | |
132 | break; | |
133 | } | |
134 | if (errflg) { | |
135 | fprintf(stderr, "Usage: ..."); | |
136 | exit(2); | |
137 | } | |
138 | for (; optind < argc; optind++) { | |
139 | \&. | |
140 | \&. | |
141 | \&. | |
142 | } | |
143 | \&. | |
144 | \&. | |
145 | \&. | |
146 | } | |
147 | .RE | |
53e9b2ee KM |
148 | .SH HISTORY |
149 | Written by Henry Spencer, working from a Bell Labs manual page. | |
53e9b2ee | 150 | .SH BUGS |
58517882 | 151 | ``-'' may be specified as an option letter, however it should never |
7edf3dad KB |
152 | have an argument associated with it. This allows \fIgetopt\fP to be |
153 | used with programs that expect ``-'' as an option flag. This practice | |
154 | is wrong, and should not be used in any current development, it is | |
58517882 | 155 | provided for backward compatibility \fBonly\fP. |
53e9b2ee | 156 | .PP |
7edf3dad KB |
157 | It is possible to handle digits as option letters. This allows |
158 | \fIgetopt\fP to be used with programs that expect ``-#'' as an | |
159 | option flag. This practice is wrong, and should not be used in any | |
160 | current development, it is provided for backward compatibility | |
161 | \fBonly\fP. The following code fragment, while not perfect, works | |
162 | fairly well. | |
163 | .RS | |
164 | .nf | |
165 | ||
166 | int minlen; | |
167 | char *p; | |
168 | ||
169 | minlen = -1; | |
170 | while ((c = getopt(argc, argv, "0123456789")) != EOF) | |
171 | switch (c) { | |
172 | case '0': case '1': case '2': case '3': case '4': | |
173 | case '5': case '6': case '7': case '8': case '9': | |
174 | if (minlen == -1) { | |
175 | p = argv[optind - 1]; | |
176 | if (p[0] == '-' && p[1] == ch && !p[2]) | |
177 | minlen = atoi(++p); | |
178 | else | |
179 | minlen = atoi(argv[optind] + 1); | |
180 | } | |
181 | break; | |
182 | } | |
183 | } | |
184 | \&. | |
185 | \&. | |
186 | \&. | |
187 | .RE | |
188 | .fi | |
189 | .PP | |
475fd909 | 190 | Option arguments are allowed to begin with ``\-''; |
53e9b2ee KM |
191 | this is reasonable but reduces the amount of error checking possible. |
192 | .PP | |
193 | .I Getopt | |
194 | is quite flexible but the obvious price must be paid: there is much | |
195 | it could do that it doesn't, like | |
196 | checking mutually exclusive options, checking type of | |
197 | option arguments, etc. |