Commit | Line | Data |
---|---|---|
5b62e993 MW |
1 | .TH getopt 3 |
2 | .SH NAME | |
3 | getopt \- get option character from command line | |
4 | .SH SYNTAX | |
5 | .B #include <getopt.h> | |
6 | ||
7 | char *\fBoptarg\fP; | |
8 | .br | |
9 | int \fBoptind\fP; | |
10 | .br | |
11 | int \fBoptpos\fP; | |
12 | .br | |
13 | int \fBopteof\fP; | |
14 | .br | |
15 | int \fBoptproblem\fP; | |
16 | .br | |
17 | char *\fBoptprogname\fP; | |
18 | .br | |
19 | int \fBopterr\fP; | |
20 | ||
21 | int \fBgetopt(\fP\fIargc,argv,opts\fR\fB)\fP; | |
22 | ||
23 | int \fIargc\fR; | |
24 | .br | |
25 | char **\fIargv\fR; | |
26 | .br | |
27 | char *\fIopts\fR; | |
28 | .SH DESCRIPTION | |
29 | This is a clone version of | |
30 | the standard | |
31 | .B getopt | |
32 | library, | |
33 | built on top of | |
34 | .BR subgetopt(3) . | |
35 | ||
36 | See | |
37 | .B subgetopt(3) | |
38 | for a detailed description of | |
39 | .B getopt | |
40 | processing. | |
41 | The main difference between | |
42 | .B getopt | |
43 | and | |
44 | .B subgetopt | |
45 | is that | |
46 | .B getopt | |
47 | prints error messages | |
48 | in case of problems. | |
49 | To turn off these error messages, set | |
50 | .B opterr | |
51 | (default nonzero) | |
52 | to zero. | |
53 | ||
54 | This clone version of | |
55 | .B getopt | |
56 | also provides an | |
57 | .B optprogname | |
58 | variable. | |
59 | There are two uses for this variable: | |
60 | ||
61 | (1) | |
62 | By default | |
63 | .B optprogname | |
64 | is null. | |
65 | When | |
66 | .B getopt | |
67 | sees this, | |
68 | it | |
69 | attempts to initialize | |
70 | .B optprogname | |
71 | from | |
72 | .IR argv\fB[0] , | |
73 | stripping the directory name. | |
74 | The calling program can use | |
75 | .B optprogname | |
76 | after calling | |
77 | .B getopt | |
78 | at least once. | |
79 | This is appropriate if the name of the program should be | |
80 | determined from its command line. | |
81 | ||
82 | (2) | |
83 | .B getopt | |
84 | prints | |
85 | .B optprogname | |
86 | at the beginning | |
87 | of any error messages. | |
88 | So the calling program can, | |
89 | before calling | |
90 | .BR getopt , | |
91 | initialize | |
92 | .B optprogname | |
93 | as desired. | |
94 | This is appropriate if the name of the program should not be | |
95 | determined from its command line. | |
96 | .SH "COMPATIBILITY" | |
97 | Old versions of | |
98 | .B getopt | |
99 | do not include | |
100 | .BR opterr . | |
101 | .BR optpos , | |
102 | .BR opteof , | |
103 | .BR optproblem , | |
104 | and | |
105 | .B optprogname | |
106 | are specific to this clone version of | |
107 | .BR getopt . | |
108 | ||
109 | Many features of this clone version of | |
110 | .B getopt | |
111 | are poorly defined, if available at all, | |
112 | in most versions of | |
113 | .BR getopt . | |
114 | For example, the standard | |
115 | .B getopt | |
116 | interface does not define | |
117 | .B optind | |
118 | until the end of the option list. | |
119 | And | |
120 | .B optarg | |
121 | is not defined | |
122 | unless | |
123 | .B getopt | |
124 | has just returned | |
125 | an option which takes an argument. | |
126 | In this clone version, | |
127 | .B optind | |
128 | and | |
129 | .B optpos | |
130 | always indicate the next character to be read, | |
131 | and | |
132 | .B optarg | |
133 | is null whenever | |
134 | the current option does not take an argument. | |
135 | See | |
136 | .B subgetopt(3) | |
137 | for precise definitions of the parsing procedure. | |
138 | ||
139 | When it reaches the end of the option list, | |
140 | this version of | |
141 | .B getopt | |
142 | always returns | |
143 | .BR opteof , | |
144 | which is the same as | |
145 | .BR subgetoptdone , | |
146 | which is initialized to | |
147 | .BR SUBGETOPTDONE , | |
148 | which is defined as \-1. | |
149 | The standard behavior is to return | |
150 | EOF | |
151 | from | |
152 | .B stdio(3). | |
153 | This is incompatible | |
154 | on any weird machine where | |
155 | EOF is different from \-1. | |
156 | The calling program could set | |
157 | .B opteof | |
158 | to EOF to imitate the standard behavior. | |
159 | ||
160 | Like most versions of | |
161 | .BR getopt , | |
162 | this clone version allows, but does not demand, that | |
163 | option arguments be | |
164 | separated from the option by whitespace, i.e., be | |
165 | in the next command-line argument. | |
166 | ||
167 | Some versions of | |
168 | .B getopt | |
169 | provide an | |
170 | .B optopt | |
171 | variable. | |
172 | .B optopt | |
173 | is incompatible across systems: | |
174 | for example, | |
175 | GNU | |
176 | .B getopt | |
177 | uses it the same way that this clone version uses | |
178 | .BR optproblem , | |
179 | while | |
180 | BSD | |
181 | .B getopt | |
182 | uses it to | |
183 | indicate the last option character returned by | |
184 | .BR getopt . | |
185 | This clone version does not provide | |
186 | .BR optopt . | |
187 | The use of | |
188 | .B optopt | |
189 | is strongly discouraged. | |
190 | ||
191 | Some versions of | |
192 | .B getopt | |
193 | do not recognize a double hyphen as the end of arguments. | |
194 | This version allows a double hyphen, or in fact any argument beginning | |
195 | with two hyphens. | |
196 | ||
197 | A lone hyphen is always recognized as the end of arguments. | |
198 | Some versions of | |
199 | .B getopt | |
200 | allow lone hyphens as options. | |
201 | This practice is wrong and is strongly discouraged. | |
202 | .SH "SYNTAX NOTE" | |
203 | .B getopt | |
204 | is actually a macro abbreviation for | |
205 | .BR getoptmine . | |
206 | The external | |
207 | .B opterr | |
208 | and | |
209 | .B optprogname | |
210 | variables | |
211 | are macros for | |
212 | .B getopterr | |
213 | and | |
214 | .BR getoptprogname . | |
215 | All the other | |
216 | .B opt | |
217 | variables are macros | |
218 | for | |
219 | .BR subgetopt . | |
220 | These macros are defined in | |
221 | .BR <getopt.h> , | |
222 | unless | |
223 | .B GETOPTNOSHORT | |
224 | is defined. | |
225 | Further macros are defined in | |
226 | .BR <subgetopt.h> , | |
227 | which is included by | |
228 | .BR <getopt.h> , | |
229 | unless | |
230 | .B SUBGETOPTNOSHORT | |
231 | is defined. | |
232 | .SH VERSION | |
233 | getopt version 1.9, 931129. | |
234 | .SH AUTHOR | |
235 | Placed into the public domain by Daniel J. Bernstein. |