1POPT(3)                    Linux Programmer's Manual                   POPT(3)
2
3
4

NAME

6       popt - Parse command line options
7

SYNOPSIS

9       #include <popt.h>
10
11       poptContext poptGetContext(const char * name, int argc,
12                                  const char ** argv,
13                                  const struct poptOption * options,
14                                  int flags);
15
16       void poptFreeContext(poptContext con);
17
18       void poptResetContext(poptContext con);
19
20       int poptGetNextOpt(poptContext con);
21
22       const char * poptGetOptArg(poptContext con);
23
24       const char * poptGetArg(poptContext con);
25
26       const char * poptPeekArg(poptContext con);
27
28       const char ** poptGetArgs(poptContext con);
29
30       const char *const poptStrerror(const int error);
31
32       const char * poptBadOption(poptContext con, int flags);
33
34       int poptReadDefaultConfig(poptContext con, int flags);
35
36       int poptReadConfigFile(poptContext con, char * fn);
37
38       int poptAddAlias(poptContext con, struct poptAlias alias,
39                        int flags);
40
41       int poptParseArgvString(char * s, int *  argcPtr,
42                               const char *** argvPtr);
43
44       int poptDupArgv(int argc, const char ** argv, int * argcPtr,
45                               const char *** argvPtr);
46
47       int poptStuffArgs(poptContext con, const char ** argv);
48
49

DESCRIPTION

51       The  popt  library exists essentially for parsing command-line options.
52       It is found superior in many ways when compared  to  parsing  the  argv
53       array  by hand or using the getopt functions getopt() and getopt_long()
54       [see getopt(3)].  Some specific advantages of popt  are:  it  does  not
55       utilize global variables, thus enabling multiple passes in parsing argv
56       ; it can parse an arbitrary  array  of  argv-style  elements,  allowing
57       parsing of command-line-strings from any source; it provides a standard
58       method of option aliasing (to be discussed at length  below.);  it  can
59       exec external option filters; and, finally, it can automatically gener‐
60       ate help and usage messages for the application.
61
62       Like getopt_long(), the popt library  supports  short  and  long  style
63       options.  Recall that a short option consists of a - character followed
64       by a single alphanumeric character.  A long option, common in GNU util‐
65       ities,  consists  of  two  - characters followed by a string made up of
66       letters, numbers and hyphens.  Long options are optionally  allowed  to
67       begin  with  a  single -, primarily to allow command-line compatibility
68       between popt applications and X toolkit applications.  Either  type  of
69       option  may  be  followed  by  an  argument.  A space separates a short
70       option from its arguments; either a space or  an  =  separates  a  long
71       option from an argument.
72
73       The  popt library is highly portable and should work on any POSIX plat‐
74       form.  The latest version is distributed with rpm and is always  avail‐
75       able from: ftp://ftp.rpm.org/pub/rpm/dist.
76
77       It  may  be  redistributed under the X consortium license, see the file
78       COPYING in the popt source distribution for details.
79

BASIC POPT USAGE

81   1. THE OPTION TABLE
82       Applications  provide  popt  with  information  on  their  command-line
83       options by means of an "option table," i.e., an array of struct poptOp‐
84       tion structures:
85
86       #include <popt.h>
87
88       struct poptOption {
89           const char * longName; /* may be NULL */
90           char shortName;        /* may be '\0' */
91           int argInfo;
92           void * arg;            /* depends on argInfo */
93           int val;               /* 0 means don't return, just update flag */
94           char * descrip;        /* description for autohelp -- may be NULL */
95           char * argDescrip;     /* argument description for autohelp */
96       };
97
98       Each member of the table defines a single option that may be passed  to
99       the  program.   Long  and  short options are considered a single option
100       that may occur in two different forms.  The first two members, longName
101       and  shortName,  define  the  names  of the option; the first is a long
102       name, while the latter is a single character.
103
104       The argInfo member tells popt what type of argument is  expected  after
105       the  argument.  If no option is expected, POPT_ARG_NONE should be used.
106       The rest of the valid values are shown in the following table:
107
108
109       Value             Description                        arg Type
110       POPT_ARG_NONE     No argument expected               int
111       POPT_ARG_STRING   No type checking to be performed   char *
112       POPT_ARG_INT      An integer argument is expected    int
113       POPT_ARG_LONG     A long integer is expected         long
114       POPT_ARG_VAL      Integer value taken from val       int
115       POPT_ARG_FLOAT    An float argument is expected      float
116       POPT_ARG_DOUBLE   A double argument is expected      double
117
118       For numeric values, if the argInfo value is bitwise or'd  with  one  of
119       POPT_ARGFLAG_OR,  POPT_ARGFLAG_AND,  or  POPT_ARGFLAG_XOR, the value is
120       saved by performing an OR, AND, or XOR.  If the argInfo value  is  bit‐
121       wise  or'd with POPT_ARGFLAG_NOT, the value will be negated before sav‐
122       ing. For  the  common  operations  of  setting  and/or  clearing  bits,
123       POPT_BIT_SET and POPT_BIT_CLR have the appropriate flags set to perform
124       bit operations.
125
126       If the argInfo value is bitwise  or'd  with  POPT_ARGFLAG_ONEDASH,  the
127       long argument may be given with a single - instead of two. For example,
128       if --longopt is an  option  with  POPT_ARGFLAG_ONEDASH,  is  specified,
129       -longopt is accepted as well.
130
131       The  next  element,  arg,  allows  popt to automatically update program
132       variables when the option is used. If arg is NULL, it  is  ignored  and
133       popt  takes no special action.  Otherwise it should point to a variable
134       of the type indicated in the right-most column of the table above.
135
136       If the option takes no argument (argInfo is POPT_ARG_NONE),  the  vari‐
137       able  pointed to by arg is set to 1 when the option is used.  (Inciden‐
138       tally, it will perhaps not escape the attention of  hunt-and-peck  typ‐
139       ists that the value of POPT_ARG_NONE is 0.)  If the option does take an
140       argument, the variable that arg points to is  updated  to  reflect  the
141       value  of  the  argument.  Any string is acceptable for POPT_ARG_STRING
142       arguments,  but  POPT_ARG_INT,   POPT_ARG_LONG,   POPT_ARG_FLOAT,   and
143       POPT_ARG_DOUBLE  are  converted  to  the appropriate type, and an error
144       returned if the conversion fails.
145
146       POPT_ARG_VAL causes arg to be set to the (integer) value  of  val  when
147       the  argument  is found.  This is most often useful for mutually-exclu‐
148       sive arguments in cases where it is not an error for multiple arguments
149       to  occur  and  where  you want the last argument specified to win; for
150       example, "rm -i -f".  POPT_ARG_VAL causes the parsing function  not  to
151       return a value, since the value of val has already been used.
152
153       If  the  argInfo  value is bitwise or'd with POPT_ARGFLAG_OPTIONAL, the
154       argument to the long option may be omitted. If the long option is  used
155       without  an argument, a default value of zero or NULL will be saved (if
156       the arg pointer is present), otherwise behavior will be identical to  a
157       long option with argument.
158
159       The  next  option,  val,  is  the  value popt's parsing function should
160       return when the option is encountered.  If it is 0, the  parsing  func‐
161       tion  does  not  return  a value, instead parsing the next command-line
162       argument.
163
164       The last two options, descrip and argDescrip are only required if auto‐
165       matic help messages are desired (automatic usage messages can be gener‐
166       ated without them). descrip is a text description of the  argument  and
167       argdescrip  is  a  short  summary  of  the type of arguments the option
168       expects, or NULL if the option doesn't require any arguments.
169
170       If popt should automatically provide --usage and --help (-?)   options,
171       one  line  in  the table should be the macro POPT_AUTOHELP.  This macro
172       includes another option table (via POPT_ARG_INCLUDE_TABLE;  see  below)
173       in  the  main one which provides the table entries for these arguments.
174       When --usage or --help are passed to programs which use popt's automat‐
175       ical  help,  popt displays the appropriate message on stderr as soon as
176       it finds the option, and exits the program with a return code of 0.  If
177       you  want  to  use popt's automatic help generation in a different way,
178       you need to explicitly add the option entries to your  programs  option
179       table instead of using POPT_AUTOHELP.
180
181       If  the argInfo value is bitwise or'd with POPT_ARGFLAG_DOC_HIDDEN, the
182       argument will not be shown in help output.
183
184       If the argInfo value is bitwise  or'd  with  POPT_ARGFLAG_SHOW_DEFAULT,
185       the inital value of the arg will be shown in help output.
186
187       The final structure in the table should have all the pointer values set
188       to NULL and all the arithmetic values set to 0, marking the end of  the
189       table. The macro POPT_TABLEEND is provided to do that.
190
191       There  are  two types of option table entries which do not specify com‐
192       mand line options. When either of these types of entries are used,  the
193       longName element must be NULL and the shortName element must be '\0'.
194
195       The  first  of these special entry types allows the application to nest
196       another option table in the current one; such nesting may extend  quite
197       deeply  (the actual depth is limited by the program's stack). Including
198       other option tables allows a library to provide a standard set of  com‐
199       mand-line options to every program which uses it (this is often done in
200       graphical programming toolkits, for  example).  To  do  this,  set  the
201       argInfo  field  to POPT_ARG_INCLUDE_TABLE and the arg field to point to
202       the table which is being included.  If  automatic  help  generation  is
203       being  used,  the descrip field should contain a overall description of
204       the option table being included.
205
206       The other special option table entry type tells popt to call a function
207       (a callback) when any option in that table is found. This is especially
208       usefull when included option tables are  being  used,  as  the  program
209       which  provides  the top-level option table doesn't need to be aware of
210       the other options which are provided by  the  included  table.  When  a
211       callback  is set for a table, the parsing function never returns infor‐
212       mation on an option in the table. Instead, options information must  be
213       retained  via the callback or by having popt set a variable through the
214       option's arg field.  Option callbacks should match the following proto‐
215       type:
216
217       void poptCallbackType(poptContext con,
218                             const struct poptOption * opt,
219                             const char * arg, void * data);
220
221       The  first parameter is the context which is being parsed (see the next
222       section for information on contexts), opt points to  the  option  which
223       triggered  this  callback,  and  arg  is the option's argument.  If the
224       option does not take an argument, arg is NULL.   The  final  parameter,
225       data  is  taken  from the descrip field of the option table entry which
226       defined the callback. As descrip is a  pointer,  this  allows  callback
227       functions to be passed an arbitrary set of data (though a typecast will
228       have to be used).
229
230       The option table entry which defines  a  callback  has  an  argInfo  of
231       POPT_ARG_CALLBACK,  an arg which points to the callback function, and a
232       descrip field which specifies an arbitrary pointer to be passed to  the
233       callback.
234
235   2. CREATING A CONTEXT
236       popt  can  interleave  the  parsing  of  multiple command-line sets. It
237       allows this by keeping all the state information for a  particular  set
238       of  command-line  arguments  in a poptContext data structure, an opaque
239       type that should not be modified outside the popt library.
240
241       New popt contexts are created by poptGetContext():
242
243       poptContext poptGetContext(const char * name, int argc,
244                                  const char ** argv,
245                                  const struct poptOption * options,
246                                  int flags);
247
248       The first parameter, name, is used only for alias  handling  (discussed
249       later).  It  should  be  the  name of the application whose options are
250       being parsed, or should be NULL if no option aliasing is  desired.  The
251       next  two  arguments specify the command-line arguments to parse. These
252       are generally passed to poptGetContext() exactly as they were passed to
253       the  program's main() function. The options parameter points to the ta‐
254       ble of command-line options, which was described in the  previous  sec‐
255       tion. The final parameter, flags, can take one of three values:
256
257       Value                        Description
258       POPT_CONTEXT_NO_EXEC         Ignore exec expansions
259       POPT_CONTEXT_KEEP_FIRST      Do not ignore argv[0]
260       POPT_CONTEXT_POSIXMEHARDER   Options cannot follow arguments
261
262       A poptContext keeps track of which options have already been parsed and
263       which remain, among other things. If a program wishes to restart option
264       processing of a set of arguments, it can reset the poptContext by pass‐
265       ing the context as the sole argument to poptResetContext().
266
267       When argument processing is complete, the process should free the popt‐
268       Context  as  it  contains  dynamically  allocated components. The popt‐
269       FreeContext() function takes a poptContext as  its  sole  argument  and
270       frees the resources the context is using.
271
272       Here  are  the  prototypes  of both poptResetContext() and poptFreeCon‐
273       text():
274
275       #include <popt.h>
276       void poptFreeContext(poptContext con);
277       void poptResetContext(poptContext con);
278
279
280   3. PARSING THE COMMAND LINE
281       After an application has created a poptContext, it  may  begin  parsing
282       arguments. poptGetNextOpt() performs the actual argument parsing.
283
284       #include <popt.h>
285       int poptGetNextOpt(poptContext con);
286
287       Taking  the context as its sole argument, this function parses the next
288       command-line argument found. After finding the  next  argument  in  the
289       option table, the function fills in the object pointed to by the option
290       table entry's arg pointer if it is not NULL. If the val entry  for  the
291       option is non-0, the function then returns that value. Otherwise, popt‐
292       GetNextOpt() continues on to the next argument.
293
294       poptGetNextOpt() returns -1 when the final argument  has  been  parsed,
295       and  other negative values when errors occur. This makes it a good idea
296       to keep the val elements in the options table greater than 0.
297
298       If all of the command-line options are handled  through  arg  pointers,
299       command-line parsing is reduced to the following line of code:
300
301       rc = poptGetNextOpt(poptcon);
302
303       Many  applications require more complex command-line parsing than this,
304       however, and use the following structure:
305
306       while ((rc = poptGetNextOpt(poptcon)) > 0) {
307            switch (rc) {
308                 /* specific arguments are handled here */
309            }
310       }
311
312       When returned options are handled, the application needs  to  know  the
313       value  of any arguments that were specified after the option. There are
314       two ways to discover them. One is to ask popt to  fill  in  a  variable
315       with  the  value of the option through the option table's arg elements.
316       The other is to use poptGetOptArg():
317
318       #include <popt.h>
319       char * poptGetOptArg(poptContext con);
320
321       This function returns the argument given for the final option  returned
322       by  poptGetNextOpt(),  or it returns NULL if no argument was specified.
323       The calling function is responsible for deallocating this string.
324
325
326   4. LEFTOVER ARGUMENTS
327       Many applications take an arbitrary number of  command-line  arguments,
328       such  as  a  list  of file names. When popt encounters an argument that
329       does not begin with a -, it assumes it is such an argument and adds  it
330       to  a list of leftover arguments. Three functions allow applications to
331       access such arguments:
332
333       const char * poptGetArg(poptContext con);
334              This function returns the next leftover argument and marks it as
335              processed.
336
337       const char * poptPeekArg(poptContext con);
338              The  next  leftover  argument is returned but not marked as pro‐
339              cessed.  This allows an application to look ahead into the argu‐
340              ment list, without modifying the list.
341
342       const char ** poptGetArgs(poptContext con);
343              All the leftover arguments are returned in a manner identical to
344              argv.  The final element in the returned array points  to  NULL,
345              indicating the end of the arguments.
346
347
348   5. AUTOMATIC HELP MESSAGES
349       The  popt  library  can  automatically  generate  help  messages  which
350       describe the options a program accepts. There are  two  types  of  help
351       messages  which  can  be generated. Usage messages are a short messages
352       which lists valid options, but does not describe  them.  Help  messages
353       describe each option on one (or more) lines, resulting in a longer, but
354       more useful, message. Whenever automatic help messages  are  used,  the
355       descrip  and  argDescrip  fields  struct  poptOption  members should be
356       filled in for each option.
357
358       The POPT_AUTOHELP macro makes it easy to add --usage  and  --help  mes‐
359       sages  to your program, and is described in part 1 of this man page. If
360       more control is needed over your help messages, the following two func‐
361       tions are available:
362
363       #include <popt.h>
364       void poptPrintHelp(poptContext con, FILE * f, int flags);
365       void poptPrintUsage(poptContext con, FILE * f, int flags);
366
367       poptPrintHelp()  displays  the  standard help message to the stdio file
368       descriptor f, while poptPrintUsage() displays the  shorter  usage  mes‐
369       sage.  Both  functions currently ignore the flags argument; it is there
370       to allow future changes.
371
372

ERROR HANDLING

374       All of the popt functions that can return errors return integers.  When
375       an error occurs, a negative error code is returned. The following table
376       summarizes the error codes that occur:
377
378            Error                      Description
379       POPT_ERROR_NOARG       Argument missing for an option.
380       POPT_ERROR_BADOPT      Option's argument couldn't be parsed.
381       POPT_ERROR_OPTSTOODEEP Option aliasing nested too deeply.
382       POPT_ERROR_BADQUOTE    Quotations do not match.
383       POPT_ERROR_BADNUMBER   Option couldn't be converted to number.
384       POPT_ERROR_OVERFLOW    A given number was too big or small.
385
386       Here is a more detailed discussion of each error:
387
388
389       POPT_ERROR_NOARG
390              An option that requires an argument was specified on the command
391              line,  but  no  argument was given. This can be returned only by
392              poptGetNextOpt().
393
394
395       POPT_ERROR_BADOPT
396              An option was specified in argv but is not in the option  table.
397              This error can be returned only from poptGetNextOpt().
398
399
400       POPT_ERROR_OPTSTOODEEP
401              A  set  of  option aliases is nested too deeply. Currently, popt
402              follows options only 10 levels to  prevent  infinite  recursion.
403              Only poptGetNextOpt() can return this error.
404
405
406       POPT_ERROR_BADQUOTE
407              A  parsed string has a quotation mismatch (such as a single quo‐
408              tation mark).  poptParseArgvString(),  poptReadConfigFile(),  or
409              poptReadDefaultConfig() can return this error.
410
411
412       POPT_ERROR_BADNUMBER
413              A  conversion from a string to a number (int or long) failed due
414              to the string containing nonnumeric characters. This occurs when
415              poptGetNextOpt() is processing an argument of type POPT_ARG_INT,
416              POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOUBLE.
417
418
419       POPT_ERROR_OVERFLOW
420              A string-to-number conversion failed because the number was  too
421              large  or  too  small. Like POPT_ERROR_BADNUMBER, this error can
422              occur only when poptGetNextOpt() is processing  an  argument  of
423              type    POPT_ARG_INT,    POPT_ARG_LONG,    POPT_ARG_FLOAT,    or
424              POPT_ARG_DOUBLE.
425
426
427       POPT_ERROR_ERRNO
428              A system call returned with an error, and errno  still  contains
429              the  error  from  the system call. Both poptReadConfigFile() and
430              poptReadDefaultConfig() can return this error.
431
432
433       Two functions are available to make it easy for applications to provide
434       good error messages.
435
436
437              const char *const poptStrerror(const int error);
438              This  function  takes  a  popt  error  code and returns a string
439              describing the error, just as with the standard strerror() func‐
440              tion.
441
442
443              const char * poptBadOption(poptContext con, int flags);
444              If  an  error  occurred  during  poptGetNextOpt(), this function
445              returns the option that caused the error. If the flags  argument
446              is  set  to  POPT_BADOPTION_NOALIAS,  the  outermost  option  is
447              returned. Otherwise, flags should be 0, and the option  that  is
448              returned may have been specified through an alias.
449
450       These  two functions make popt error handling trivial for most applica‐
451       tions. When an error is detected from most of the functions,  an  error
452       message  is  printed  along  with the error string from poptStrerror().
453       When an error occurs during argument parsing, code similiar to the fol‐
454       lowing displays a useful error message:
455
456       fprintf(stderr, "%s: %s\n",
457               poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
458               poptStrerror(rc));
459
460

OPTION ALIASING

462       One  of the primary benefits of using popt over getopt() is the ability
463       to use option aliasing. This lets the user specify  options  that  popt
464       expands  into  other  options  when they are specified. If the standard
465       grep program made use of popt, users could add  a  --text  option  that
466       expanded  to  -i  -n  -E -2 to let them more easily find information in
467       text files.
468
469
470   1. SPECIFYING ALIASES
471       Aliases are normally specified in two places: /etc/popt and  the  .popt
472       file  in  the user's home directory (found through the HOME environment
473       variable). Both files have the same  format,  an  arbitrary  number  of
474       lines formatted like this:
475
476       appname alias newoption expansion
477
478       The  appname  is the name of the application, which must be the same as
479       the name parameter passed to poptGetContext(). This allows each file to
480       specify aliases for multiple programs. The alias keyword specifies that
481       an alias is being defined; currently popt configuration  files  support
482       only  aliases, but other abilities may be added in the future. The next
483       option is the option that should be aliased, and it  may  be  either  a
484       short  or  a  long option. The rest of the line specifies the expansion
485       for the alias. It is parsed similarly to a shell command, which  allows
486       \, ", and ' to be used for quoting. If a backslash is the final charac‐
487       ter on a line, the next line in the file is assumed  to  be  a  logical
488       continuation of the line containing the backslash, just as in shell.
489
490       The  following  entry would add a --text option to the grep command, as
491       suggested at the beginning of this section.
492
493       grep alias --text -i -n -E -2
494
495   2. ENABLING ALIASES
496       An application must enable alias expansion  for  a  poptContext  before
497       calling  poptGetNextArg() for the first time. There are three functions
498       that define aliases for a context:
499
500
501              int poptReadDefaultConfig(poptContext con, int flags);
502              This function reads aliases from /etc/popt and the .popt file in
503              the  user's  home directory. Currently, flags should be NULL, as
504              it is provided only for future expansion.
505
506
507              int poptReadConfigFile(poptContext con, char * fn);
508              The file specified by fn is opened and parsed as a popt configu‐
509              ration  file.  This allows programs to use program-specific con‐
510              figuration files.
511
512
513              int poptAddAlias(poptContext con, struct poptAlias alias,
514                               int flags);
515              Occasionally, processes want to specify aliases  without  having
516              to read them from a configuration file. This function adds a new
517              alias to a context. The flags argument should be  0,  as  it  is
518              currently reserved for future expansion. The new alias is speci‐
519              fied as a struct poptAlias, which is defined as:
520
521              struct poptAlias {
522                   const char * longName; /* may be NULL */
523                   char shortName; /* may be '\0' */
524                   int argc;
525                   const char ** argv; /* must be free()able */
526              };
527
528              The first two elements,  longName  and  shortName,  specify  the
529              option that is aliased. The final two, argc and argv, define the
530              expansion to use when the aliases option is encountered.
531

PARSING ARGUMENT STRINGS

533       Although popt is usually used for  parsing  arguments  already  divided
534       into  an argv-style array, some programs need to parse strings that are
535       formatted identically to command lines. To facilitate this,  popt  pro‐
536       vides  a  function that parses a string into an array of strings, using
537       rules similiar to normal shell parsing.
538
539       #include <popt.h>
540       int poptParseArgvString(char * s, int * argcPtr,
541                               char *** argvPtr);
542       int poptDupArgv(int argc, const char ** argv, int * argcPtr,
543                               const char *** argvPtr);
544
545       The string s is parsed into an argv-style array. The integer pointed to
546       by  the  argcPtr  parameter contains the number of elements parsed, and
547       the final argvPtr parameter contains the address of the  newly  created
548       array.   The  routine  poptDupArgv()  can  be used to make a copy of an
549       existing argument array.
550
551       The argvPtr created by poptParseArgvString() or poptDupArgv() is  suit‐
552       able to pass directly to poptGetContext().  Both routines return a sin‐
553       gle dynamically allocated contiguous block of  storage  and  should  be
554       free()ed when the application is finished with the storage.
555

HANDLING EXTRA ARGUMENTS

557       Some  applications implement the equivalent of option aliasing but need
558       to do so through special logic. The poptStuffArgs() function allows  an
559       application to insert new arguments into the current poptContext.
560
561       #include <popt.h>
562       int poptStuffArgs(poptContext con, const char ** argv);
563
564       The  passed  argv  must  have a NULL pointer as its final element. When
565       poptGetNextOpt() is next called, the "stuffed" arguments are the  first
566       to be parsed. popt returns to the normal arguments once all the stuffed
567       arguments have been exhausted.
568

EXAMPLE

570       The following example is a simplified version of  the  program  "robin"
571       which  appears  in  Chapter 15 of the text cited below.  Robin has been
572       stripped  of  everything  but  its  argument-parsing  logic,   slightly
573       reworked,  and  renamed "parse." It may prove useful in illustrating at
574       least some of the features of the extremely rich popt library.
575
576       #include <popt.h>
577       #include <stdio.h>
578
579       void usage(poptContext optCon, int exitcode, char *error, char *addl) {
580           poptPrintUsage(optCon, stderr, 0);
581           if (error) fprintf(stderr, "%s: %s0, error, addl);
582           exit(exitcode);
583       }
584
585       int main(int argc, char *argv[]) {
586          char    c;            /* used for argument parsing */
587          int     i = 0;        /* used for tracking options */
588          char    *portname;
589          int     speed = 0;    /* used in argument parsing to set speed */
590          int     raw = 0;      /* raw mode? */
591          int     j;
592          char    buf[BUFSIZ+1];
593          poptContext optCon;   /* context for parsing command-line options */
594
595          struct poptOption optionsTable[] = {
596                                     { "bps", 'b', POPT_ARG_INT, &speed, 0,
597                                                                   "signaling rate in bits-per-second", "BPS" },
598                                     { "crnl", 'c', 0, 0, 'c',
599                                                                   "expand cr characters to cr/lf sequences" },
600                                     { "hwflow", 'h', 0, 0, 'h',
601                                                                   "use hardware (RTS/CTS) flow control" },
602                                     { "noflow", 'n', 0, 0, 'n',
603                                                                   "use no flow control" },
604                                     { "raw", 'r', 0, &raw, 0,
605                                                                   "don't perform any character conversions" },
606                                     { "swflow", 's', 0, 0, 's',
607                                                                   "use software (XON/XOF) flow control" } ,
608                                     POPT_AUTOHELP
609                                     { NULL, 0, 0, NULL, 0 }
610          };
611
612          optCon = poptGetContext(NULL, argc, argv, optionsTable, 0);
613          poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");
614
615          if (argc < 2) {
616                                 poptPrintUsage(optCon, stderr, 0);
617                                 exit(1);
618          }
619
620          /* Now do options processing, get portname */
621          while ((c = poptGetNextOpt(optCon)) >= 0) {
622             switch (c) {
623                case 'c':
624                   buf[i++] = 'c';
625                   break;
626                case 'h':
627                   buf[i++] = 'h';
628                   break;
629                case 's':
630                   buf[i++] = 's';
631                   break;
632                case 'n':
633                   buf[i++] = 'n';
634                   break;
635             }
636          }
637          portname = poptGetArg(optCon);
638          if((portname == NULL) || !(poptPeekArg(optCon) == NULL))
639             usage(optCon, 1, "Specify a single port", ".e.g., /dev/cua0");
640
641          if (c < -1) {
642             /* an error occurred during option processing */
643             fprintf(stderr, "%s: %s\n",
644                     poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
645                     poptStrerror(c));
646             return 1;
647          }
648
649          /* Print out options, portname chosen */
650          printf("Options  chosen: ");
651          for(j = 0; j < i ; j++)
652             printf("-%c ", buf[j]);
653          if(raw) printf("-r ");
654          if(speed) printf("-b %d ", speed);
655          printf("\nPortname chosen: %s\n", portname);
656
657          poptFreeContext(optCon);
658          exit(0);
659       }
660
661       RPM, a popular Linux package management program,  makes  heavy  use  of
662       popt's  features.  Many  of  its command-line arguments are implemented
663       through popt aliases, which makes RPM an excellent example  of  how  to
664       take  advantage  of  the popt library. For more information on RPM, see
665       http://www.rpm.org. The popt source  code  distribution  includes  test
666       program(s) which use all of the features of the popt libraries in vari‐
667       ous ways. If a feature isn't working for you, the popt test code is the
668       first place to look.
669

BUGS

671       None presently known.
672

AUTHOR

674       Erik W. Troan <ewt@redhat.com>
675
676       This  man page is derived in part from Linux Application Development by
677       Michael K. Johnson and Erik W. Troan, Copyright  (c)  1998  by  Addison
678       Wesley  Longman,  Inc., and included in the popt documentation with the
679       permission of the Publisher and the appreciation of the Authors.
680
681       Thanks to Robert Lynch for his extensive work on this man page.
682

SEE ALSO

684       getopt(3)
685
686       Linux Application Development, by Michael K. Johnson and Erik W.  Troan
687       (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24.
688
689       popt.ps is a Postscript version of the above cited book chapter. It can
690       be   found   in   the   source   archive   for   popt   available   at:
691       ftp://ftp.rpm.org/pub/rpm.
692
693
694
695                                 June 30, 1998                         POPT(3)
Impressum