Commit | Line | Data |
---|---|---|
62402cb1 MP |
1 | .TH POPT 3 "June 30, 1998" "" "Linux Programmer's Manual" |
2 | .SH NAME | |
3 | popt \- Parse command line options | |
4 | .SH SYNOPSIS | |
5 | .nf | |
6 | .B #include <popt.h> | |
7 | .sp | |
8 | .BI "poptContext poptGetContext(char * " name ", int " argc , | |
9 | .BI " char ** "argv , | |
10 | .BI " struct poptOption * " options , | |
11 | .BI " int " flags ); | |
12 | .sp | |
13 | .BI "void poptFreeContext(poptContext " con ); | |
14 | .sp | |
15 | .BI "void poptResetContext(poptContext " con ); | |
16 | .sp | |
17 | .BI "int poptGetNextOpt(poptContext " con ); | |
18 | .sp | |
19 | .BI "char * poptGetOptArg(poptContext " con ); | |
20 | .sp | |
21 | .BI "char * poptGetArg(poptContext " con ); | |
22 | .sp | |
23 | .BI "char * poptPeekArg(poptContext " con ); | |
24 | .sp | |
25 | .BI "char ** poptGetArgs(poptContext " con ); | |
26 | .sp | |
27 | .BI "const char * poptStrerror(const int " error ); | |
28 | .sp | |
29 | .BI "char * poptBadOption(poptContext " con ", int " flags ); | |
30 | .sp | |
31 | .BI "int poptReadDefaultConfig(poptContext " con ", int " flags ); | |
32 | .sp | |
33 | .BI "int poptReadConfigFile(poptContext " con ", char * " fn ); | |
34 | .sp | |
35 | .BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias , | |
36 | .BI " int " flags ); | |
37 | .sp | |
38 | .BI "int poptParseArgvString(char * " s ", int * " argcPtr , | |
39 | .BI " char *** " argvPtr ); | |
40 | .sp | |
41 | .BI "int poptStuffArgs(poptContext " con ", char ** " argv ); | |
42 | .sp | |
43 | .fi | |
44 | .SH DESCRIPTION | |
45 | The popt library exists essentially for parsing command-line | |
46 | options. It is found superior in many ways when compared to | |
47 | parsing the argv array by hand or using the getopt functions | |
48 | .B getopt() | |
49 | and | |
50 | .B getopt_long() | |
51 | [see | |
52 | .BR getopt "(3)]." | |
53 | Some specific advantages of popt are: it does not utilize global | |
54 | .RI "variables, thus enabling multiple passes in parsing " argv | |
55 | .RI "; it can parse an arbitrary array of " argv "-style elements, " | |
56 | allowing parsing of command-line-strings from any source; | |
57 | it provides a standard method of option aliasing (to be | |
58 | discussed at length below.); it can exec external option filters; and, | |
59 | finally, it can automatically generate help and usage messages for | |
60 | the application. | |
61 | .sp | |
62 | Like | |
63 | .BR getopt_long() , | |
64 | the popt library supports short and long style options. Recall | |
65 | that a | |
66 | .B short option | |
67 | consists of a - character followed by a single alphanumeric character. | |
68 | A | |
69 | .BR "long option" , | |
70 | common in GNU utilities, consists of two - characters followed by a | |
71 | string made up of letters, numbers and hyphens. Long options are | |
72 | optionally allowed to begin with a single -, primarily to allow command-line | |
73 | compatibility between popt applications and X toolkit applications. | |
74 | Either type of option may be followed by an argument. A space separates a | |
75 | short option from its arguments; either a space or an = separates a long | |
76 | option from an argument. | |
77 | .sp | |
78 | The popt library is highly portable and should work on any POSIX | |
79 | platform. The latest version is always available from: | |
80 | ftp://ftp.redhat.com/pub/redhat/code/popt. | |
81 | .sp | |
82 | It may be redistributed under either the GNU General Public License | |
83 | or the GNU Library General Public License, at the distributor's discretion. | |
84 | .SH "BASIC POPT USAGE" | |
85 | .SS "1. THE OPTION TABLE" | |
86 | Applications provide popt with information on their command-line | |
87 | options by means of an "option table," i.e., an array of | |
88 | .B struct poptOption | |
89 | structures: | |
90 | .sp | |
91 | #include <popt.h> | |
92 | .sp | |
93 | .nf | |
94 | struct poptOption { | |
95 | const char * longName; /* may be NULL */ | |
96 | char shortName; /* may be '\\0' */ | |
97 | int argInfo; | |
98 | void * arg; /* depends on argInfo */ | |
99 | int val; /* 0 means don't return, just update flag */ | |
100 | char * descrip; /* description for autohelp -- may be NULL */ | |
101 | char * argDescrip; /* argument description for autohelp */ | |
102 | }; | |
103 | .fi | |
104 | .sp | |
105 | Each member of the table defines a single option that may be | |
106 | passed to the program. Long and short options are considered | |
107 | a single option that may occur in two different forms. The | |
108 | first two members, | |
109 | .IR longName " and " shortName ", define the names of the option;" | |
110 | the first is a long name, while the latter is a single character. | |
111 | .sp | |
112 | The | |
113 | .IR argInfo " member tell popt what type of argument is expected" | |
114 | after the argument. If no option is expected, | |
115 | .BR POPT_ARG_NONE " should be used. (Connoisseurs of " getopt() | |
116 | .RI "will note that " argInfo " is the only required field of " | |
117 | .BR "struct poptOption" " that is not directly analogous to a field in " | |
118 | .RB "the " getopt_long() " argument table. The similarity between the " | |
119 | .RB "two allows for easy transitions from " getopt_long " to popt.) " | |
120 | The rest of the valid values are shown in the following table: | |
121 | .sp | |
122 | .nf | |
123 | .B " Value Description arg Type" | |
124 | .BR POPT_ARG_NONE " No argument expected int" | |
125 | .BR POPT_ARG_STRING " No type checking to be performed char *" | |
126 | .BR POPT_ARG_INT " An integer argument is expected int" | |
127 | .BR POPT_ARG_LONG " A long integer is expected long" | |
128 | .sp | |
129 | .fi | |
130 | If \fIargInfo\fR value is logically or'd with \fBPOPT_ARGFLAG_ONEDASH\fR, | |
131 | the long argument may be given with a single - instead of two. For example, | |
132 | if \fB--longopt\fR is an option with \fBPOPT_ARGFLAG_ONEDASH\fR, is | |
133 | specified, \fB-longopt\fR is accepted as well. | |
134 | .sp | |
135 | .RI "The next element, " arg ", allows popt to automatically update " | |
136 | .RI "program variables when the option is used. If " arg " is " | |
137 | .BR NULL ", it is ignored and popt takes no special action. " | |
138 | Otherwise it should point to a variable of the type indicated in the | |
139 | right-most column of the table above. | |
140 | .sp | |
141 | .RI "If the option takes no argument (" argInfo " is " | |
142 | .BR POPT_ARG_NONE "), the variable pointed to by " | |
143 | .IR arg " is set to 1 when the option is used. (Incidentally, it " | |
144 | will perhaps not escape the attention of hunt-and-peck typists that | |
145 | .RB "the value of " POPT_ARG_NONE " is 0.) If the option does take " | |
146 | an argument, the variable that | |
147 | .IR arg " points to is updated to reflect the value of the argument." | |
148 | .RB "Any string is acceptable for " POPT_ARG_STRING " arguments, but " | |
149 | .BR POPT_ARG_INT " and " POPT_ARG_LONG " are converted to the | |
150 | appropriate type, and an error returned if the conversion fails. | |
151 | .sp | |
152 | .RI "The next option, " val ", is the value popt's parsing function | |
153 | should return when the option is encountered. If it is 0, the parsing | |
154 | function does not return a value, instead parsing the next | |
155 | command-line argument. | |
156 | .sp | |
157 | .RI "The last two options, " descrip " and " argDescrip " are only required | |
158 | if automatic help messages are desired (automatic usage messages can | |
159 | .RI "be generated without them). " descrip " is a text description of the | |
160 | .RI "argument and " argdescrip " is a short summary of the type of arguments | |
161 | .RI "the option expects, or NULL if the option doesn't require any | |
162 | arguments. | |
163 | .sp | |
164 | .RB "If popt should automatically provide " --usage " and " --help " (" -? ") | |
165 | .RB "options, one line in the table should be the macro " POPT_AUTOHELP ". | |
166 | .RB "This macro includes another option table (via " POPT_ARG_INCLUDE_TABLE; | |
167 | see below) in the main one which provides the table entries for these | |
168 | .RB "arguments. When " --usage " or " --help " are passed to programs which | |
169 | use popt's automatical help, popt displays the appropriate message on | |
170 | stderr as soon as it finds the option, and exits the program with a | |
171 | return code of 0. If you want to use popt's automatic help generation in | |
172 | a different way, you need to explicitly add the option entries to your programs | |
173 | .RB "option table instead of using " POPT_AUTOHELP ". | |
174 | .sp | |
175 | The final structure in the table should have all the pointer values set | |
176 | .RB "to " NULL " and all the arithmetic values set to 0, marking the " | |
177 | end of the table. | |
178 | .sp | |
179 | There are two types of option table entries which do not specify command | |
180 | line options. When either of these types of entries are used, the | |
181 | \fIlongName\fR element must be \fBNULL\fR and the \fBshortName\fR element | |
182 | must be \fB'\\0'\fR. | |
183 | .sp | |
184 | The first of these special entry types allows the application to nest | |
185 | another option table in the current one; such nesting may extend quite | |
186 | deeply (the actual depth is limited by the program's stack). Including | |
187 | other option tables allows a library to provide a standard set of | |
188 | command-line options to every program which uses it (this is often done | |
189 | in graphical programming toolkits, for example). To do this, set | |
190 | the \fIargInfo\fR field to \fBPOPT_ARG_INCLUDE_TABLE\fR and the | |
191 | \fRarg\fR field to point to the table which is being included. If | |
192 | automatic help generation is being used, the \fIdescrip\fR field should | |
193 | contain a overall description of the option table being included. | |
194 | .sp | |
195 | The other special option table entry type tells popt to call a function (a | |
196 | callback) when any option in that table is found. This is especially usefull | |
197 | when included option tables are being used, as the program which provides | |
198 | the top-level option table doesn't need to be aware of the other options | |
199 | which are provided by the included table. When a callback is set for | |
200 | a table, the parsing function never returns information on an option in | |
201 | the table. Instead, options information must be retained via the callback | |
202 | or by having popt set a variable through the option's \fIarg\fR field. | |
203 | Option callbacks should match the following prototype: | |
204 | .sp | |
205 | .nf | |
206 | .BI "void poptCallbackType(poptContext con, | |
207 | .BI " const struct poptOption * opt, | |
208 | .BI " const char * arg, void * data); | |
209 | .fi | |
210 | .sp | |
211 | The first parameter is the context which is being parsed (see the next | |
212 | section for information on contexts), \fIopt\fR points to the option | |
213 | which triggered this callback, and \fIarg\fR is the option's argument. | |
214 | If the option does not take an argument, \fIarg\fR is \fBNULL\fR. The | |
215 | final parameter, \fIdata\fR is taken from the \fIdescrip\fR field | |
216 | of the option table entry which defined the callback. As \fIdescrip\fR | |
217 | is a pointer, this allows callback functions to be passed an arbitrary | |
218 | set of data (though a typecast will have to be used). | |
219 | .sp | |
220 | The option table entry which defines a callback has an \fIargInfo\fR of | |
221 | \fBPOPT_ARG_CALLBACK\fR, an \fIarg\fR which points to the callback | |
222 | function, and a \fIdescrip\fR field which specifies an arbitrary pointer | |
223 | to be passed to the callback. | |
224 | .SS "2. CREATING A CONTEXT" | |
225 | popt can interleave the parsing of multiple command-line sets. It allows | |
226 | this by keeping all the state information for a particular set of | |
227 | command-line arguments in a | |
228 | .BR poptContext " data structure, an opaque type that should not be " | |
229 | modified outside the popt library. | |
230 | .sp | |
231 | .RB "New popt contexts are created by " poptGetContext() ":" | |
232 | .sp | |
233 | .nf | |
234 | .BI "poptContext poptGetContext(char * " name ", int "argc ", | |
235 | .BI " char ** "argv ", | |
236 | .BI " struct poptOption * "options ", | |
237 | .BI " int "flags ");" | |
238 | .fi | |
239 | .sp | |
240 | The first parameter, | |
241 | .IR name ", is used only for alias handling (discussed later). It " | |
242 | should be the name of the application whose options are being parsed, | |
243 | .RB "or should be " NULL " if no option aliasing is desired. The next " | |
244 | two arguments specify the command-line arguments to parse. These are | |
245 | .RB "generally passed to " poptGetContext() " exactly as they were " | |
246 | .RB "passed to the program's " main() " function. The " | |
247 | .IR options " parameter points to the table of command-line options, " | |
248 | which was described in the previous section. The final parameter, | |
249 | .IR flags ",is not currently used but should always be specified as | |
250 | 0 for compatibility with future versions of the popt library. | |
251 | .sp | |
252 | .RB "A " poptContext " keeps track of which options have already been " | |
253 | parsed and which remain, among other things. If a program wishes to | |
254 | restart option processing of a set of arguments, it can reset the | |
255 | .BR poptContext " by passing the context as the sole argument to " | |
256 | .BR poptResetContext() . | |
257 | .sp | |
258 | When argument processing is complete, the process should free the | |
259 | .BR poptContext " as it contains dynamically allocated components. The " | |
260 | .BR poptFreeContext() " function takes a " | |
261 | .BR poptContext " as its sole argument and frees the resources the " | |
262 | context is using. | |
263 | .sp | |
264 | .RB "Here are the prototypes of both " poptResetContext() " and " | |
265 | .BR poptFreeContext() : | |
266 | .sp | |
267 | .nf | |
268 | .B #include <popt.h> | |
269 | .BI "void poptFreeContext(poptContext " con ");" | |
270 | .BI "void poptResetContext(poptContext " con ");" | |
271 | .fi | |
272 | .sp | |
273 | .SS "3. PARSING THE COMMAND LINE" | |
274 | .RB "After an application has created a " poptContext ", it may begin " | |
275 | .RB "parsing arguments. " poptGetNextOpt() " performs the actual " | |
276 | argument parsing. | |
277 | .sp | |
278 | .nf | |
279 | .B #include <popt.h> | |
280 | .BI "int poptGetNextOpt(poptContext " con ");" | |
281 | .fi | |
282 | .sp | |
283 | Taking the context as its sole argument, this function parses the next | |
284 | command-line argument found. After finding the next argument in the | |
285 | option table, the function fills in the object pointed to by the option | |
286 | .RI "table entry's " arg | |
287 | .RB "pointer if it is not " NULL ". If the val entry for the option is " | |
288 | non-0, the function then returns that value. Otherwise, | |
289 | .BR poptGetNextOpt() " continues on to the next argument." | |
290 | .sp | |
291 | .BR poptGetNextOpt() " returns -1 when the final argument has been " | |
292 | parsed, and other negative values when errors occur. This makes it a | |
293 | good idea to | |
294 | .RI "keep the " val " elements in the options table greater than 0." | |
295 | .sp | |
296 | .RI "If all of the command-line options are handled through " arg | |
297 | pointers, command-line parsing is reduced to the following line of code: | |
298 | .sp | |
299 | .nf | |
300 | rc = poptGetNextOpt(poptcon); | |
301 | .fi | |
302 | .sp | |
303 | Many applications require more complex command-line parsing than this, | |
304 | however, and use the following structure: | |
305 | .sp | |
306 | .nf | |
307 | while ((rc = poptGetNextOpt(poptcon)) > 0) { | |
308 | switch (rc) { | |
309 | /* specific arguments are handled here */ | |
310 | } | |
311 | } | |
312 | .fi | |
313 | .sp | |
314 | When returned options are handled, the application needs to know the | |
315 | value of any arguments that were specified after the option. There are two | |
316 | ways to discover them. One is to ask popt to fill in a variable with the | |
317 | .RI "value of the option through the option table's " arg " elements. The " | |
318 | .RB "other is to use " poptGetOptArg() ":" | |
319 | .sp | |
320 | .nf | |
321 | .B #include <popt.h> | |
322 | .BI "char * poptGetOptArg(poptContext " con ");" | |
323 | .fi | |
324 | .sp | |
325 | This function returns the argument given for the final option returned by | |
326 | .BR poptGetNextOpt() ", or it returns " NULL " if no argument was specified." | |
327 | .sp | |
328 | .SS "4. LEFTOVER ARGUMENTS" | |
329 | Many applications take an arbitrary number of command-line arguments, | |
330 | such as a list of file names. When popt encounters an argument that does | |
331 | not begin with a -, it assumes it is such an argument and adds it to a list | |
332 | of leftover arguments. Three functions allow applications to access such | |
333 | arguments: | |
334 | .nf | |
335 | .HP | |
336 | .BI "char * poptGetArg(poptContext " con ");" | |
337 | .fi | |
338 | This function returns the next leftover argument and marks it as | |
339 | processed. | |
340 | .PP | |
341 | .nf | |
342 | .HP | |
343 | .BI "char * poptPeekArg(poptContext " con ");" | |
344 | .fi | |
345 | The next leftover argument is returned but not marked as processed. | |
346 | This allows an application to look ahead into the argument list, | |
347 | without modifying the list. | |
348 | .PP | |
349 | .nf | |
350 | .HP | |
351 | .BI "char ** poptGetArgs(poptContext " con ");" | |
352 | .fi | |
353 | All the leftover arguments are returned in a manner identical to | |
354 | .IR argv ". The final element in the returned array points to " | |
355 | .BR NULL ", indicating the end of the arguments. | |
356 | .sp | |
357 | .SS "5. AUTOMATIC HELP MESSAGES" | |
358 | The \fBpopt\fR library can automatically generate help messages which | |
359 | describe the options a program accepts. There are two types of help | |
360 | messages which can be generated. Usage messages are a short messages | |
361 | which lists valid options, but does not describe them. Help messages | |
362 | describe each option on one (or more) lines, resulting in a longer, but | |
363 | more useful, message. Whenever automatic help messages are used, the | |
364 | \fBdescrip\fR and \fBargDescrip\fR fields \fBstruct poptOption\fR members | |
365 | should be filled in for each option. | |
366 | .sp | |
367 | The \fBPOPT_AUTOHELP\fR macro makes it easy to add \fB--usage\fR and | |
368 | \fB--help\fR messages to your program, and is described in part 1 | |
369 | of this man page. If more control is needed over your help messages, | |
370 | the following two functions are available: | |
371 | .sp | |
372 | .nf | |
373 | .B #include <popt.h> | |
374 | .BI "void poptPrintHelp(poptContext " con ", FILE * " f ", int " flags "); | |
375 | .BI "void poptPrintUsage(poptContext " con ", FILE * " f ", int " flags "); | |
376 | .fi | |
377 | .sp | |
378 | \fBpoptPrintHelp()\fR displays the standard help message to the stdio file | |
379 | descriptor f, while \fBpoptPrintUsage()\fR displays the shorter usage | |
380 | message. Both functions currently ignore the \fBflags\fR argument; it is | |
381 | there to allow future changes. | |
382 | .sp | |
383 | .SH "ERROR HANDLING" | |
384 | All of the popt functions that can return errors return integers. | |
385 | When an error occurs, a negative error code is returned. The | |
386 | following table summarizes the error codes that occur: | |
387 | .sp | |
388 | .nf | |
389 | .B " Error Description" | |
390 | .BR "POPT_ERROR_NOARG " "Argument missing for an option." | |
391 | .BR "POPT_ERROR_BADOPT " "Option's argument couldn't be parsed." | |
392 | .BR "POPT_ERROR_OPTSTOODEEP " "Option aliasing nested too deeply." | |
393 | .BR "POPT_ERROR_BADQUOTE " "Quotations do not match." | |
394 | .BR "POPT_ERROR_BADNUMBER " "Option couldn't be converted to number." | |
395 | .BR "POPT_ERROR_OVERFLOW " "A given number was too big or small." | |
396 | .fi | |
397 | .sp | |
398 | Here is a more detailed discussion of each error: | |
399 | .sp | |
400 | .TP | |
401 | .B POPT_ERROR_NOARG | |
402 | An option that requires an argument was specified on the command | |
403 | line, but no argument was given. This can be returned only by | |
404 | .BR poptGetNextOpt() . | |
405 | .sp | |
406 | .TP | |
407 | .B POPT_ERROR_BADOPT | |
408 | .RI "An option was specified in " argv " but is not in the option | |
409 | .RB "table. This error can be returned only from " poptGetNextOpt() . | |
410 | .sp | |
411 | .TP | |
412 | .B POPT_ERROR_OPTSTOODEEP | |
413 | A set of option aliases is nested too deeply. Currently, popt | |
414 | follows options only 10 levels to prevent infinite recursion. Only | |
415 | .BR poptGetNextOpt() " can return this error." | |
416 | .sp | |
417 | .TP | |
418 | .B POPT_ERROR_BADQUOTE | |
419 | A parsed string has a quotation mismatch (such as a single quotation | |
420 | .RB "mark). " poptParseArgvString() ", " poptReadConfigFile() ", or " | |
421 | .BR poptReadDefaultConfig() " can return this error." | |
422 | .sp | |
423 | .TP | |
424 | .B POPT_ERROR_BADNUMBER | |
425 | A conversion from a string to a number (int or long) failed due | |
426 | to the string containing nonnumeric characters. This occurs when | |
427 | .BR poptGetNextOpt() " is processing an argument of type " | |
428 | .BR POPT_ARG_INT " or " POPT_ARG_LONG . | |
429 | .sp | |
430 | .TP | |
431 | .B POPT_ERROR_OVERFLOW | |
432 | A string-to-number conversion failed because the number was too | |
433 | .RB "large or too small. Like " POPT_ERROR_BADNUMBER ", this error | |
434 | .RB "can occur only when " poptGetNextOpt() " is processing an " | |
435 | .RB "argument of type " POPT_ARG_INT " or " POPT_ARG_LONG . | |
436 | .sp | |
437 | .TP | |
438 | .B POPT_ERROR_ERRNO | |
439 | .RI "A system call returned with an error, and " errno " still | |
440 | contains the error from the system call. Both | |
441 | .BR poptReadConfigFile() " and " poptReadDefaultConfig() " can " | |
442 | return this error. | |
443 | .sp | |
444 | .PP | |
445 | Two functions are available to make it easy for applications to provide | |
446 | good error messages. | |
447 | .HP | |
448 | .nf | |
449 | .BI "const char * poptStrerror(const int " error ");" | |
450 | .fi | |
451 | This function takes a popt error code and returns a string describing | |
452 | .RB "the error, just as with the standard " strerror() " function." | |
453 | .PP | |
454 | .HP | |
455 | .nf | |
456 | .BI "char * poptBadOption(poptContext " con ", int " flags ");" | |
457 | .fi | |
458 | .RB "If an error occurred during " poptGetNextOpt() ", this function " | |
459 | .RI "returns the option that caused the error. If the " flags " argument" | |
460 | .RB "is set to " POPT_BADOPTION_NOALIAS ", the outermost option is " | |
461 | .RI "returned. Otherwise, " flags " should be 0, and the option that is " | |
462 | returned may have been specified through an alias. | |
463 | .PP | |
464 | These two functions make popt error handling trivial for most | |
465 | applications. When an error is detected from most of the functions, | |
466 | an error message is printed along with the error string from | |
467 | .BR poptStrerror() ". When an error occurs during argument parsing, " | |
468 | code similiar to the following displays a useful error message: | |
469 | .sp | |
470 | .nf | |
471 | fprintf(stderr, "%s: %s\\n", | |
472 | poptBadOption(optCon, POPT_BADOPTION_NOALIAS), | |
473 | poptStrerror(rc)); | |
474 | .fi | |
475 | .sp | |
476 | .SH "OPTION ALIASING" | |
477 | .RB "One of the primary benefits of using popt over " getopt() " is the " | |
478 | ability to use option aliasing. This lets the user specify options that | |
479 | popt expands into other options when they are specified. If the standard | |
480 | .RB "grep program made use of popt, users could add a " --text " option " | |
481 | .RB "that expanded to " "-i -n -E -2" " to let them more easily find " | |
482 | information in text files. | |
483 | .sp | |
484 | .SS "1. SPECIFYING ALIASES" | |
485 | .RI "Aliases are normally specified in two places: " /etc/popt | |
486 | .RB "and the " .popt " file in the user's home directory (found through " | |
487 | .RB "the " HOME " environment variable). Both files have the same format, " | |
488 | an arbitrary number of lines formatted like this: | |
489 | .sp | |
490 | .IB appname " alias " newoption "" " expansion" | |
491 | .sp | |
492 | .RI "The " appname " is the name of the application, which must be the " | |
493 | .RI "same as the " name " parameter passed to " | |
494 | .BR poptGetContext() ". This allows each file to specify aliases for " | |
495 | .RB "multiple programs. The " alias " keyword specifies that an alias is " | |
496 | being defined; currently popt configuration files support only aliases, but | |
497 | other abilities may be added in the future. The next option is the option | |
498 | that should be aliased, and it may be either a short or a long option. The | |
499 | rest of the line specifies the expansion for the alias. It is parsed | |
500 | similarly to a shell command, which allows \\, ", and ' to be used for | |
501 | quoting. If a backslash is the final character on a line, the next line | |
502 | in the file is assumed to be a logical continuation of the line containing | |
503 | the backslash, just as in shell. | |
504 | .sp | |
505 | .RB "The following entry would add a " --text " option to the grep command, " | |
506 | as suggested at the beginning of this section. | |
507 | .sp | |
508 | .B "grep alias --text -i -n -E -2" | |
509 | .SS "2. ENABLING ALIASES" | |
510 | .RB "An application must enable alias expansion for a " poptContext | |
511 | .RB "before calling " poptGetNextArg() " for the first time. There are " | |
512 | three functions that define aliases for a context: | |
513 | .HP | |
514 | .nf | |
515 | .BI "int poptReadDefaultConfig(poptContext " con ", int " flags ");" | |
516 | .fi | |
517 | .RI "This function reads aliases from " /etc/popt " and the " | |
518 | .BR .popt " file in the user's home directory. Currently, " | |
519 | .IR flags " should be " | |
520 | .BR NULL ", as it is provided only for future expansion." | |
521 | .PP | |
522 | .HP | |
523 | .nf | |
524 | .BI "int poptReadConfigFile(poptContext " con ", char * " fn ");" | |
525 | .fi | |
526 | .RI "The file specified by " fn " is opened and parsed as a popt " | |
527 | configuration file. This allows programs to use program-specific | |
528 | configuration files. | |
529 | .PP | |
530 | .HP | |
531 | .nf | |
532 | .BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ", | |
533 | .BI " int " flags ");" | |
534 | .fi | |
535 | Occasionally, processes want to specify aliases without having to | |
536 | read them from a configuration file. This function adds a new alias | |
537 | .RI "to a context. The " flags " argument should be 0, as it is " | |
538 | currently reserved for future expansion. The new alias is specified | |
539 | .RB "as a " "struct poptAlias" ", which is defined as:" | |
540 | .sp | |
541 | .nf | |
542 | struct poptAlias { | |
543 | char * longName; /* may be NULL */ | |
544 | char shortName; /* may be '\\0' */ | |
545 | int argc; | |
546 | char ** argv; /* must be free()able */ | |
547 | }; | |
548 | .fi | |
549 | .sp | |
550 | .RI "The first two elements, " longName " and " shortName ", specify " | |
551 | .RI "the option that is aliased. The final two, " argc " and " argv "," | |
552 | define the expansion to use when the aliases option is encountered. | |
553 | .PP | |
554 | .SH "PARSING ARGUMENT STRINGS" | |
555 | Although popt is usually used for parsing arguments already divided into | |
556 | .RI "an " argv "-style array, some programs need to parse strings that " | |
557 | are formatted identically to command lines. To facilitate this, popt | |
558 | provides a function that parses a string into an array of strings, | |
559 | using rules similiar to normal shell parsing. | |
560 | .sp | |
561 | .nf | |
562 | .B "#include <popt.h>" | |
563 | .BI "int poptParseArgvString(char * " s ", int * "argcPtr ", | |
564 | .BI " char *** " argvPtr ");" | |
565 | .fi | |
566 | .sp | |
567 | .RI "The string s is parsed into an " argv "-style array. The integer " | |
568 | .RI "pointed to by the second parameter, " argcPtr ", contains the number " | |
569 | of elements parsed, and the pointer pointed to by the final parameter is | |
570 | set to point to the newly created array. The array is dynamically | |
571 | .RB "allocated and should be " free() "ed when the application is finished " | |
572 | with it. | |
573 | .sp | |
574 | .RI "The " argvPtr | |
575 | .RB "created by " poptParseArgvString() " is suitable to pass directly " | |
576 | .RB "to " poptGetContext() . | |
577 | .SH "HANDLING EXTRA ARGUMENTS" | |
578 | Some applications implement the equivalent of option aliasing but need | |
579 | .RB "to do so through special logic. The " poptStuffArgs() " function " | |
580 | allows an application to insert new arguments into the current | |
581 | .BR poptContext . | |
582 | .sp | |
583 | .nf | |
584 | .B "#include <popt.h>" | |
585 | .BI "int poptStuffArgs(poptContext "con ", char ** " argv ");" | |
586 | .fi | |
587 | .sp | |
588 | .RI "The passed " argv | |
589 | .RB "must have a " NULL " pointer as its final element. When " | |
590 | .BR poptGetNextOpt() " is next called, the " | |
591 | "stuffed" arguments are the first to be parsed. popt returns to the | |
592 | normal arguments once all the stuffed arguments have been exhausted. | |
593 | .SH "EXAMPLE" | |
594 | The following example is a simplified version of the program "robin" | |
595 | which appears in Chapter 15 of the text cited below. Robin has | |
596 | been stripped of everything but its argument-parsing logic, slightly | |
597 | reworked, and renamed "parse." It may prove useful in illustrating | |
598 | at least some of the features of the extremely rich popt library. | |
599 | .sp | |
600 | .nf | |
601 | #include <popt.h> | |
602 | #include <stdio.h> | |
603 | ||
604 | void usage(poptContext optCon, int exitcode, char *error, char *addl) { | |
605 | poptPrintUsage(optCon, stderr, 0); | |
606 | if (error) fprintf(stderr, "%s: %s\n", error, addl); | |
607 | exit(exitcode); | |
608 | } | |
609 | ||
610 | int main(int argc, char *argv[]) { | |
611 | char c; /* used for argument parsing */ | |
612 | int i = 0; /* used for tracking options */ | |
613 | char *portname; | |
614 | int speed = 0; /* used in argument parsing to set speed */ | |
615 | int raw = 0; /* raw mode? */ | |
616 | int j; | |
617 | char buf[BUFSIZ+1]; | |
618 | poptContext optCon; /* context for parsing command-line options */ | |
619 | ||
620 | struct poptOption optionsTable[] = { | |
621 | { "bps", 'b', POPT_ARG_INT, &speed, 0, | |
622 | "signaling rate in bits-per-second", "BPS" }, | |
623 | { "crnl", 'c', 0, 0, 'c', | |
624 | "expand cr characters to cr/lf sequences" }, | |
625 | { "hwflow", 'h', 0, 0, 'h', | |
626 | "use hardware (RTS/CTS) flow control" }, | |
627 | { "noflow", 'n', 0, 0, 'n', | |
628 | "use no flow control" }, | |
629 | { "raw", 'r', 0, &raw, 0, | |
630 | "don't perform any character conversions" }, | |
631 | { "swflow", 's', 0, 0, 's', | |
632 | "use software (XON/XOF) flow control" } , | |
633 | POPT_AUTOHELP | |
634 | { NULL, 0, 0, NULL, 0 } | |
635 | }; | |
636 | ||
637 | optCon = poptGetContext(NULL, argc, argv, optionsTable, 0); | |
638 | poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>"); | |
639 | ||
640 | if (argc < 2) { | |
641 | poptPrintUsage(optCon, stderr, 0); | |
642 | exit(1); | |
643 | } | |
644 | ||
645 | /* Now do options processing, get portname */ | |
646 | while ((c = poptGetNextOpt(optCon)) >= 0) { | |
647 | switch (c) { | |
648 | case 'c': | |
649 | buf[i++] = 'c'; | |
650 | break; | |
651 | case 'h': | |
652 | buf[i++] = 'h'; | |
653 | break; | |
654 | case 's': | |
655 | buf[i++] = 's'; | |
656 | break; | |
657 | case 'n': | |
658 | buf[i++] = 'n'; | |
659 | break; | |
660 | } | |
661 | } | |
662 | portname = poptGetArg(optCon); | |
663 | if((portname == NULL) || !(poptPeekArg(optCon) == NULL)) | |
664 | usage(optCon, 1, "Specify a single port", ".e.g., /dev/cua0"); | |
665 | ||
666 | if (c < -1) { | |
667 | /* an error occurred during option processing */ | |
668 | fprintf(stderr, "%s: %s\\n", | |
669 | poptBadOption(optCon, POPT_BADOPTION_NOALIAS), | |
670 | poptStrerror(c)); | |
671 | return 1; | |
672 | } | |
673 | ||
674 | /* Print out options, portname chosen */ | |
675 | printf("Options chosen: "); | |
676 | for(j = 0; j < i ; j++) | |
677 | printf("-%c ", buf[j]); | |
678 | if(raw) printf("-r "); | |
679 | if(speed) printf("-b %d ", speed); | |
680 | printf("\\nPortname chosen: %s\\n", portname); | |
681 | ||
682 | poptFreeContext(optCon); | |
683 | exit(0); | |
684 | } | |
685 | .fi | |
686 | .sp | |
687 | RPM, a popular Linux package management program, makes heavy use | |
688 | of popt's features. Many of its command-line arguments are implemented | |
689 | through popt aliases, which makes RPM an excellent example of how to | |
690 | take advantage of the popt library. For more information on RPM, see | |
691 | http://www.rpm.org. The popt source code distribution includes test | |
692 | program(s) which use all of the features of the popt libraries in | |
693 | various ways. If a feature isn't working for you, the popt test code | |
694 | is the first place to look. | |
695 | .SH BUGS | |
696 | None presently known. | |
697 | .SH AUTHOR | |
698 | Erik W. Troan <ewt@redhat.com> | |
699 | .PP | |
700 | This man page is derived in part from | |
701 | .IR "Linux Application Development" | |
702 | by Michael K. Johnson and Erik W. Troan, Copyright (c) 1998 by Addison | |
703 | Wesley Longman, Inc., and included in the popt documentation with the | |
704 | permission of the Publisher and the appreciation of the Authors. | |
705 | .PP | |
706 | Thanks to Robert Lynch for his extensive work on this man page. | |
707 | .SH "SEE ALSO" | |
708 | .BR getopt (3) | |
709 | .sp | |
710 | .IR "Linux Application Development" ", by Michael K. Johnson and " | |
711 | Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24. | |
712 | .sp | |
713 | .BR popt.ps " is a Postscript version of the above cited book " | |
714 | chapter. It can be found in the source archive for popt available at: | |
715 | ftp://ftp.redhat.com/pub/redhat/code/popt |