1 .TH POPT 3 "June 30, 1998" "" "Linux Programmer's Manual"
3 popt \- Parse command line options
8 .BI "poptContext poptGetContext(const char * " name ", int " argc ,
9 .BI " const char ** "argv ,
10 .BI " const struct poptOption * " options ,
13 .BI "void poptFreeContext(poptContext " con );
15 .BI "void poptResetContext(poptContext " con );
17 .BI "int poptGetNextOpt(poptContext " con );
19 .BI "const char * poptGetOptArg(poptContext " con );
21 .BI "const char * poptGetArg(poptContext " con );
23 .BI "const char * poptPeekArg(poptContext " con );
25 .BI "const char ** poptGetArgs(poptContext " con );
27 .BI "const char *const poptStrerror(const int " error );
29 .BI "const char * poptBadOption(poptContext " con ", int " flags );
31 .BI "int poptReadDefaultConfig(poptContext " con ", int " flags );
33 .BI "int poptReadConfigFile(poptContext " con ", char * " fn );
35 .BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ,
38 .BI "int poptParseArgvString(char * " s ", int * " argcPtr ,
39 .BI " const char *** " argvPtr );
41 .BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ",
42 .BI " const char *** " argvPtr ");"
44 .BI "int poptStuffArgs(poptContext " con ", const char ** " argv );
48 The popt library exists essentially for parsing command-line
49 options. It is found superior in many ways when compared to
50 parsing the argv array by hand or using the getopt functions
56 Some specific advantages of popt are: it does not utilize global
57 .RI "variables, thus enabling multiple passes in parsing " argv
58 .RI "; it can parse an arbitrary array of " argv "-style elements, "
59 allowing parsing of command-line-strings from any source;
60 it provides a standard method of option aliasing (to be
61 discussed at length below.); it can exec external option filters; and,
62 finally, it can automatically generate help and usage messages for
67 the popt library supports short and long style options. Recall
70 consists of a - character followed by a single alphanumeric character.
73 common in GNU utilities, consists of two - characters followed by a
74 string made up of letters, numbers and hyphens. Long options are
75 optionally allowed to begin with a single -, primarily to allow command-line
76 compatibility between popt applications and X toolkit applications.
77 Either type of option may be followed by an argument. A space separates a
78 short option from its arguments; either a space or an = separates a long
79 option from an argument.
81 The popt library is highly portable and should work on any POSIX
82 platform. The latest version is distributed with rpm and is always available
83 from: ftp://ftp.rpm.org/pub/rpm/dist.
85 It may be redistributed under the X consortium license, see the file COPYING
86 in the popt source distribution for details.
87 .SH "BASIC POPT USAGE"
88 .SS "1. THE OPTION TABLE"
89 Applications provide popt with information on their command-line
90 options by means of an "option table," i.e., an array of
98 const char * longName; /* may be NULL */
99 char shortName; /* may be '\\0' */
101 void * arg; /* depends on argInfo */
102 int val; /* 0 means don't return, just update flag */
103 char * descrip; /* description for autohelp -- may be NULL */
104 char * argDescrip; /* argument description for autohelp */
108 Each member of the table defines a single option that may be
109 passed to the program. Long and short options are considered
110 a single option that may occur in two different forms. The
112 .IR longName " and " shortName ", define the names of the option;"
113 the first is a long name, while the latter is a single character.
116 .IR argInfo " member tells popt what type of argument is expected"
117 after the option. If no argument is expected,
120 The rest of the valid values are shown in the following table:
125 Value Description arg Type
126 POPT_ARG_NONE No argument expected int
127 POPT_ARG_STRING No type checking to be performed char *
128 POPT_ARG_ARGV No type checking to be performed char **
129 POPT_ARG_SHORT An short argument is expected short
130 POPT_ARG_INT An integer argument is expected int
131 POPT_ARG_LONG A long integer is expected long
132 POPT_ARG_LONGLONG A long long integer is expected long long
133 POPT_ARG_VAL Integer value taken from \f(CWval\fR int
134 POPT_ARG_FLOAT An float argument is expected float
135 POPT_ARG_DOUBLE A double argument is expected double
138 For numeric values, if the \fIargInfo\fR value is bitwise or'd with one of
139 \fBPOPT_ARGFLAG_OR\fR, \fBPOPT_ARGFLAG_AND\fR, or \fBPOPT_ARGFLAG_XOR\fR,
140 the value is saved by performing an OR, AND, or XOR.
141 If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_NOT\fR,
142 the value will be negated before saving. For the common operations of
143 setting and/or clearing bits, \fBPOPT_BIT_SET\fR and \fBPOPT_BIT_CLR\fR
144 have the appropriate flags set to perform bit operations.
146 If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_ONEDASH\fR,
147 the long argument may be given with a single - instead of two. For example,
148 if \fB--longopt\fR is an option with \fBPOPT_ARGFLAG_ONEDASH\fR, is
149 specified, \fB-longopt\fR is accepted as well.
151 .RI "The next element, " arg ", allows popt to automatically update "
152 .RI "program variables when the option is used. If " arg " is "
153 .BR NULL ", it is ignored and popt takes no special action. "
154 Otherwise it should point to a variable of the type indicated in the
155 .RB "right-most column of the table above. A " POPT_ARG_ARGV " arg will
156 (re-)allocate an array of char * string pointers, append the string argument, and add a
157 .BR NULL " sentinel at the end of the array as needed."
158 .RB "The target char ** address of a " POPT_ARG_ARGV " arg should be initialized to " NULL "."
160 .RI "If the option takes no argument (" argInfo " is "
161 .BR POPT_ARG_NONE "), the variable pointed to by "
162 .IR arg " is set to 1 when the option is used. (Incidentally, it "
163 will perhaps not escape the attention of hunt-and-peck typists that
164 .RB "the value of " POPT_ARG_NONE " is 0.) If the option does take "
165 an argument, the variable that
166 .IR arg " points to is updated to reflect the value of the argument."
167 .RB "Any string is acceptable for " POPT_ARG_STRING " and " POPT_ARG_ARGV " arguments, but "
168 .BR POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", " POPT_ARG_FLOAT ", and "
169 .BR POPT_ARG_DOUBLE " are converted to the appropriate type, and an "
170 error returned if the conversion fails.
172 \fBPOPT_ARG_VAL\fR causes \fIarg\fP to be set to the (integer) value of
173 \fIval\fP when the argument is found. This is most often useful for
174 mutually-exclusive arguments in cases where it is not an error for
175 multiple arguments to occur and where you want the last argument
176 specified to win; for example, "rm -i -f". \fBPOPT_ARG_VAL\fP causes
177 the parsing function not to return a value, since the value of \fIval\fP
178 has already been used.
180 If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_OPTIONAL\fR,
181 the argument to the long option may be omitted. If the long option
182 is used without an argument, a default value of zero or NULL will be saved
183 (if the arg pointer is present), otherwise behavior will be identical to
184 a long option with argument.
186 .RI "The next option, " val ", is the value popt's parsing function
187 should return when the option is encountered. If it is 0, the parsing
188 function does not return a value, instead parsing the next
189 command-line argument.
191 .RI "The last two options, " descrip " and " argDescrip " are only required
192 if automatic help messages are desired (automatic usage messages can
193 .RI "be generated without them). " descrip " is a text description of the
194 .RI "argument and " argdescrip " is a short summary of the type of arguments
195 .RI "the option expects, or NULL if the option doesn't require any
198 .RB "If popt should automatically provide " --usage " and " --help " (" -? ")
199 .RB "options, one line in the table should be the macro " POPT_AUTOHELP ".
200 .RB "This macro includes another option table (via " POPT_ARG_INCLUDE_TABLE
201 ; see below) in the main one which provides the table entries for these
202 .RB "arguments. When " --usage " or " --help " are passed to programs which
203 use popt's automatical help, popt displays the appropriate message on
204 stderr as soon as it finds the option, and exits the program with a
205 return code of 0. If you want to use popt's automatic help generation in
206 a different way, you need to explicitly add the option entries to your programs
207 .RB "option table instead of using " POPT_AUTOHELP ".
209 If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_DOC_HIDDEN\fR,
210 the argument will not be shown in help output.
212 If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_SHOW_DEFAULT\fR,
213 the inital value of the arg will be shown in help output.
215 The final structure in the table should have all the pointer values set
216 .RB "to " NULL " and all the arithmetic values set to 0, marking the "
217 .RB "end of the table. The macro " POPT_TABLEEND " is provided to do that.
219 There are two types of option table entries which do not specify command
220 line options. When either of these types of entries are used, the
221 \fIlongName\fR element must be \fBNULL\fR and the \fBshortName\fR element
224 The first of these special entry types allows the application to nest
225 another option table in the current one; such nesting may extend quite
226 deeply (the actual depth is limited by the program's stack). Including
227 other option tables allows a library to provide a standard set of
228 command-line options to every program which uses it (this is often done
229 in graphical programming toolkits, for example). To do this, set
230 the \fIargInfo\fR field to \fBPOPT_ARG_INCLUDE_TABLE\fR and the
231 \fRarg\fR field to point to the table which is being included. If
232 automatic help generation is being used, the \fIdescrip\fR field should
233 contain a overall description of the option table being included.
235 The other special option table entry type tells popt to call a function (a
236 callback) when any option in that table is found. This is especially usefull
237 when included option tables are being used, as the program which provides
238 the top-level option table doesn't need to be aware of the other options
239 which are provided by the included table. When a callback is set for
240 a table, the parsing function never returns information on an option in
241 the table. Instead, options information must be retained via the callback
242 or by having popt set a variable through the option's \fIarg\fR field.
243 Option callbacks should match the following prototype:
246 .BI "void poptCallbackType(poptContext con,
247 .BI " const struct poptOption * opt,
248 .BI " const char * arg, void * data);
251 The first parameter is the context which is being parsed (see the next
252 section for information on contexts), \fIopt\fR points to the option
253 which triggered this callback, and \fIarg\fR is the option's argument.
254 If the option does not take an argument, \fIarg\fR is \fBNULL\fR. The
255 final parameter, \fIdata\fR is taken from the \fIdescrip\fR field
256 of the option table entry which defined the callback. As \fIdescrip\fR
257 is a pointer, this allows callback functions to be passed an arbitrary
258 set of data (though a typecast will have to be used).
260 The option table entry which defines a callback has an \fIargInfo\fR of
261 \fBPOPT_ARG_CALLBACK\fR, an \fIarg\fR which points to the callback
262 function, and a \fIdescrip\fR field which specifies an arbitrary pointer
263 to be passed to the callback.
264 .SS "2. CREATING A CONTEXT"
265 popt can interleave the parsing of multiple command-line sets. It allows
266 this by keeping all the state information for a particular set of
267 command-line arguments in a
268 .BR poptContext " data structure, an opaque type that should not be "
269 modified outside the popt library.
271 .RB "New popt contexts are created by " poptGetContext() ":"
274 .BI "poptContext poptGetContext(const char * " name ", int "argc ",
275 .BI " const char ** "argv ",
276 .BI " const struct poptOption * "options ",
277 .BI " int "flags ");"
281 .IR name ", is used only for alias handling (discussed later). It "
282 should be the name of the application whose options are being parsed,
283 .RB "or should be " NULL " if no option aliasing is desired. The next "
284 two arguments specify the command-line arguments to parse. These are
285 .RB "generally passed to " poptGetContext() " exactly as they were "
286 .RB "passed to the program's " main() " function. The "
287 .IR options " parameter points to the table of command-line options, "
288 which was described in the previous section. The final parameter,
290 can take one of three values:
296 POPT_CONTEXT_NO_EXEC Ignore exec expansions
297 POPT_CONTEXT_KEEP_FIRST Do not ignore argv[0]
298 POPT_CONTEXT_POSIXMEHARDER Options cannot follow arguments
301 .RB "A " poptContext " keeps track of which options have already been "
302 parsed and which remain, among other things. If a program wishes to
303 restart option processing of a set of arguments, it can reset the
304 .BR poptContext " by passing the context as the sole argument to "
305 .BR poptResetContext() .
307 When argument processing is complete, the process should free the
308 .BR poptContext " as it contains dynamically allocated components. The "
309 .BR poptFreeContext() " function takes a "
310 .BR poptContext " as its sole argument and frees the resources the "
313 .RB "Here are the prototypes of both " poptResetContext() " and "
314 .BR poptFreeContext() :
318 .BI "void poptFreeContext(poptContext " con ");"
319 .BI "void poptResetContext(poptContext " con ");"
322 .SS "3. PARSING THE COMMAND LINE"
323 .RB "After an application has created a " poptContext ", it may begin "
324 .RB "parsing arguments. " poptGetNextOpt() " performs the actual "
329 .BI "int poptGetNextOpt(poptContext " con ");"
332 Taking the context as its sole argument, this function parses the next
333 command-line argument found. After finding the next argument in the
334 option table, the function fills in the object pointed to by the option
335 .RI "table entry's " arg
336 .RB "pointer if it is not " NULL ". If the val entry for the option is "
337 non-0, the function then returns that value. Otherwise,
338 .BR poptGetNextOpt() " continues on to the next argument."
340 .BR poptGetNextOpt() " returns -1 when the final argument has been "
341 parsed, and other negative values when errors occur. This makes it a
343 .RI "keep the " val " elements in the options table greater than 0."
345 .RI "If all of the command-line options are handled through " arg
346 pointers, command-line parsing is reduced to the following line of code:
349 rc = poptGetNextOpt(poptcon);
352 Many applications require more complex command-line parsing than this,
353 however, and use the following structure:
356 while ((rc = poptGetNextOpt(poptcon)) > 0) {
358 /* specific arguments are handled here */
363 When returned options are handled, the application needs to know the
364 value of any arguments that were specified after the option. There are two
365 ways to discover them. One is to ask popt to fill in a variable with the
366 .RI "value of the option through the option table's " arg " elements. The "
367 .RB "other is to use " poptGetOptArg() ":"
371 .BI "char * poptGetOptArg(poptContext " con ");"
374 This function returns the argument given for the final option returned by
375 .BR poptGetNextOpt() ", or it returns " NULL " if no argument was specified."
376 The calling function is responsible for deallocating this string.
378 .SS "4. LEFTOVER ARGUMENTS"
379 Many applications take an arbitrary number of command-line arguments,
380 such as a list of file names. When popt encounters an argument that does
381 not begin with a -, it assumes it is such an argument and adds it to a list
382 of leftover arguments. Three functions allow applications to access such
386 .BI "const char * poptGetArg(poptContext " con ");"
388 This function returns the next leftover argument and marks it as
393 .BI "const char * poptPeekArg(poptContext " con ");"
395 The next leftover argument is returned but not marked as processed.
396 This allows an application to look ahead into the argument list,
397 without modifying the list.
401 .BI "const char ** poptGetArgs(poptContext " con ");"
403 All the leftover arguments are returned in a manner identical to
404 .IR argv ". The final element in the returned array points to "
405 .BR NULL ", indicating the end of the arguments.
407 .SS "5. AUTOMATIC HELP MESSAGES"
408 The \fBpopt\fR library can automatically generate help messages which
409 describe the options a program accepts. There are two types of help
410 messages which can be generated. Usage messages are a short messages
411 which lists valid options, but does not describe them. Help messages
412 describe each option on one (or more) lines, resulting in a longer, but
413 more useful, message. Whenever automatic help messages are used, the
414 \fBdescrip\fR and \fBargDescrip\fR fields \fBstruct poptOption\fR members
415 should be filled in for each option.
417 The \fBPOPT_AUTOHELP\fR macro makes it easy to add \fB--usage\fR and
418 \fB--help\fR messages to your program, and is described in part 1
419 of this man page. If more control is needed over your help messages,
420 the following two functions are available:
424 .BI "void poptPrintHelp(poptContext " con ", FILE * " f ", int " flags ");
425 .BI "void poptPrintUsage(poptContext " con ", FILE * " f ", int " flags ");
428 \fBpoptPrintHelp()\fR displays the standard help message to the stdio file
429 descriptor f, while \fBpoptPrintUsage()\fR displays the shorter usage
430 message. Both functions currently ignore the \fBflags\fR argument; it is
431 there to allow future changes.
434 All of the popt functions that can return errors return integers.
435 When an error occurs, a negative error code is returned. The
436 following table summarizes the error codes that occur:
439 .B " Error Description"
440 .BR "POPT_ERROR_NOARG " "Argument missing for an option."
441 .BR "POPT_ERROR_BADOPT " "Option's argument couldn't be parsed."
442 .BR "POPT_ERROR_OPTSTOODEEP " "Option aliasing nested too deeply."
443 .BR "POPT_ERROR_BADQUOTE " "Quotations do not match."
444 .BR "POPT_ERROR_BADNUMBER " "Option couldn't be converted to number."
445 .BR "POPT_ERROR_OVERFLOW " "A given number was too big or small."
448 Here is a more detailed discussion of each error:
452 An option that requires an argument was specified on the command
453 line, but no argument was given. This can be returned only by
454 .BR poptGetNextOpt() .
458 .RI "An option was specified in " argv " but is not in the option
459 .RB "table. This error can be returned only from " poptGetNextOpt() .
462 .B POPT_ERROR_OPTSTOODEEP
463 A set of option aliases is nested too deeply. Currently, popt
464 follows options only 10 levels to prevent infinite recursion. Only
465 .BR poptGetNextOpt() " can return this error."
468 .B POPT_ERROR_BADQUOTE
469 A parsed string has a quotation mismatch (such as a single quotation
470 .RB "mark). " poptParseArgvString() ", " poptReadConfigFile() ", or "
471 .BR poptReadDefaultConfig() " can return this error."
474 .B POPT_ERROR_BADNUMBER
475 A conversion from a string to a number (int or long) failed due
476 to the string containing nonnumeric characters. This occurs when
477 .BR poptGetNextOpt() " is processing an argument of type "
478 .BR POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", "
479 .RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."
482 .B POPT_ERROR_OVERFLOW
483 A string-to-number conversion failed because the number was too
484 .RB "large or too small. Like " POPT_ERROR_BADNUMBER ", this error
485 .RB "can occur only when " poptGetNextOpt() " is processing an "
486 .RB "argument of type " POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", "
487 .RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."
491 .RI "A system call returned with an error, and " errno " still
492 contains the error from the system call. Both
493 .BR poptReadConfigFile() " and " poptReadDefaultConfig() " can "
497 Two functions are available to make it easy for applications to provide
501 .BI "const char *const poptStrerror(const int " error ");"
503 This function takes a popt error code and returns a string describing
504 .RB "the error, just as with the standard " strerror() " function."
508 .BI "const char * poptBadOption(poptContext " con ", int " flags ");"
510 .RB "If an error occurred during " poptGetNextOpt() ", this function "
511 .RI "returns the option that caused the error. If the " flags " argument"
512 .RB "is set to " POPT_BADOPTION_NOALIAS ", the outermost option is "
513 .RI "returned. Otherwise, " flags " should be 0, and the option that is "
514 returned may have been specified through an alias.
516 These two functions make popt error handling trivial for most
517 applications. When an error is detected from most of the functions,
518 an error message is printed along with the error string from
519 .BR poptStrerror() ". When an error occurs during argument parsing, "
520 code similiar to the following displays a useful error message:
523 fprintf(stderr, "%s: %s\\n",
524 poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
528 .SH "OPTION ALIASING"
529 .RB "One of the primary benefits of using popt over " getopt() " is the "
530 ability to use option aliasing. This lets the user specify options that
531 popt expands into other options when they are specified. If the standard
532 .RB "grep program made use of popt, users could add a " --text " option "
533 .RB "that expanded to " "-i -n -E -2" " to let them more easily find "
534 information in text files.
536 .SS "1. SPECIFYING ALIASES"
537 .RI "Aliases are normally specified in two places: " /etc/popt
538 .RB "and the " .popt " file in the user's home directory (found through "
539 .RB "the " HOME " environment variable). Both files have the same format, "
540 an arbitrary number of lines formatted like this:
542 .IB appname " alias " newoption "" " expansion"
544 .RI "The " appname " is the name of the application, which must be the "
545 .RI "same as the " name " parameter passed to "
546 .BR poptGetContext() ". This allows each file to specify aliases for "
547 .RB "multiple programs. The " alias " keyword specifies that an alias is "
548 being defined; currently popt configuration files support only aliases, but
549 other abilities may be added in the future. The next option is the option
550 that should be aliased, and it may be either a short or a long option. The
551 rest of the line specifies the expansion for the alias. It is parsed
552 similarly to a shell command, which allows \\, ", and ' to be used for
553 quoting. If a backslash is the final character on a line, the next line
554 in the file is assumed to be a logical continuation of the line containing
555 the backslash, just as in shell.
557 .RB "The following entry would add a " --text " option to the grep command, "
558 as suggested at the beginning of this section.
560 .B "grep alias --text -i -n -E -2"
561 .SS "2. ENABLING ALIASES"
562 .RB "An application must enable alias expansion for a " poptContext
563 .RB "before calling " poptGetNextArg() " for the first time. There are "
564 three functions that define aliases for a context:
567 .BI "int poptReadDefaultConfig(poptContext " con ", int " flags ");"
569 .RI "This function reads aliases from " /etc/popt " and the "
570 .BR .popt " file in the user's home directory. Currently, "
571 .IR flags " should be "
572 .BR NULL ", as it is provided only for future expansion."
576 .BI "int poptReadConfigFile(poptContext " con ", char * " fn ");"
578 .RI "The file specified by " fn " is opened and parsed as a popt "
579 configuration file. This allows programs to use program-specific
584 .BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ",
585 .BI " int " flags ");"
587 Occasionally, processes want to specify aliases without having to
588 read them from a configuration file. This function adds a new alias
589 .RI "to a context. The " flags " argument should be 0, as it is "
590 currently reserved for future expansion. The new alias is specified
591 .RB "as a " "struct poptAlias" ", which is defined as:"
595 const char * longName; /* may be NULL */
596 char shortName; /* may be '\\0' */
598 const char ** argv; /* must be free()able */
602 .RI "The first two elements, " longName " and " shortName ", specify "
603 .RI "the option that is aliased. The final two, " argc " and " argv ","
604 define the expansion to use when the aliases option is encountered.
606 .SH "PARSING ARGUMENT STRINGS"
607 Although popt is usually used for parsing arguments already divided into
608 .RI "an " argv "-style array, some programs need to parse strings that "
609 are formatted identically to command lines. To facilitate this, popt
610 provides a function that parses a string into an array of strings,
611 using rules similiar to normal shell parsing.
614 .B "#include <popt.h>"
615 .BI "int poptParseArgvString(char * " s ", int * " argcPtr ",
616 .BI " char *** " argvPtr ");"
617 .BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ",
618 .BI " const char *** " argvPtr ");"
621 .RI "The string s is parsed into an " argv "-style array. The integer "
622 .RI "pointed to by the " argcPtr " parameter contains the number of elements "
623 .RI "parsed, and the final " argvPtr " parameter contains the address of the"
625 .RB "The routine " poptDupArgv() " can be used to make a copy of an existing "
629 .RB "created by " poptParseArgvString() " or " poptDupArgv() " is suitable to pass directly "
630 .RB "to " poptGetContext() .
631 Both routines return a single dynamically allocated contiguous
632 .RB "block of storage and should be " free() "ed when the application is"
633 finished with the storage.
634 .SH "HANDLING EXTRA ARGUMENTS"
635 Some applications implement the equivalent of option aliasing but need
636 .RB "to do so through special logic. The " poptStuffArgs() " function "
637 allows an application to insert new arguments into the current
641 .B "#include <popt.h>"
642 .BI "int poptStuffArgs(poptContext "con ", const char ** " argv ");"
645 .RI "The passed " argv
646 .RB "must have a " NULL " pointer as its final element. When "
647 .BR poptGetNextOpt() " is next called, the "
648 "stuffed" arguments are the first to be parsed. popt returns to the
649 normal arguments once all the stuffed arguments have been exhausted.
651 The following example is a simplified version of the program "robin"
652 which appears in Chapter 15 of the text cited below. Robin has
653 been stripped of everything but its argument-parsing logic, slightly
654 reworked, and renamed "parse." It may prove useful in illustrating
655 at least some of the features of the extremely rich popt library.
661 void usage(poptContext optCon, int exitcode, char *error, char *addl) {
662 poptPrintUsage(optCon, stderr, 0);
663 if (error) fprintf(stderr, "%s: %s\n", error, addl);
667 int main(int argc, char *argv[]) {
668 char c; /* used for argument parsing */
669 int i = 0; /* used for tracking options */
671 int speed = 0; /* used in argument parsing to set speed */
672 int raw = 0; /* raw mode? */
675 poptContext optCon; /* context for parsing command-line options */
677 struct poptOption optionsTable[] = {
678 { "bps", 'b', POPT_ARG_INT, &speed, 0,
679 "signaling rate in bits-per-second", "BPS" },
680 { "crnl", 'c', 0, 0, 'c',
681 "expand cr characters to cr/lf sequences", NULL },
682 { "hwflow", 'h', 0, 0, 'h',
683 "use hardware (RTS/CTS) flow control", NULL },
684 { "noflow", 'n', 0, 0, 'n',
685 "use no flow control", NULL },
686 { "raw", 'r', 0, &raw, 0,
687 "don't perform any character conversions", NULL },
688 { "swflow", 's', 0, 0, 's',
689 "use software (XON/XOF) flow control", NULL } ,
691 { NULL, 0, 0, NULL, 0 }
694 optCon = poptGetContext(NULL, argc, argv, optionsTable, 0);
695 poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");
698 poptPrintUsage(optCon, stderr, 0);
702 /* Now do options processing, get portname */
703 while ((c = poptGetNextOpt(optCon)) >= 0) {
719 portname = poptGetArg(optCon);
720 if((portname == NULL) || !(poptPeekArg(optCon) == NULL))
721 usage(optCon, 1, "Specify a single port", ".e.g., /dev/cua0");
724 /* an error occurred during option processing */
725 fprintf(stderr, "%s: %s\\n",
726 poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
731 /* Print out options, portname chosen */
732 printf("Options chosen: ");
733 for(j = 0; j < i ; j++)
734 printf("-%c ", buf[j]);
735 if(raw) printf("-r ");
736 if(speed) printf("-b %d ", speed);
737 printf("\\nPortname chosen: %s\\n", portname);
739 poptFreeContext(optCon);
744 RPM, a popular Linux package management program, makes heavy use
745 of popt's features. Many of its command-line arguments are implemented
746 through popt aliases, which makes RPM an excellent example of how to
747 take advantage of the popt library. For more information on RPM, see
748 http://www.rpm.org. The popt source code distribution includes test
749 program(s) which use all of the features of the popt libraries in
750 various ways. If a feature isn't working for you, the popt test code
751 is the first place to look.
753 None presently known.
755 Erik W. Troan <ewt@redhat.com>
757 This man page is derived in part from
758 .IR "Linux Application Development"
759 by Michael K. Johnson and Erik W. Troan, Copyright (c) 1998 by Addison
760 Wesley Longman, Inc., and included in the popt documentation with the
761 permission of the Publisher and the appreciation of the Authors.
763 Thanks to Robert Lynch for his extensive work on this man page.
767 .IR "Linux Application Development" ", by Michael K. Johnson and "
768 Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24.
770 .BR popt.ps " is a Postscript version of the above cited book "
771 chapter. It can be found in the source archive for popt available at:
772 ftp://ftp.rpm.org/pub/rpm.