Provided by: libpopt-dev_1.19+dfsg-1build1_amd64 bug

NAME

       popt - Parse command line options

SYNOPSIS

       #include <popt.h>

       poptContext poptGetContext(const char * name, int argc,
                                  const char ** argv,
                                  const struct poptOption * options,
                                  unsigned int flags);

       void poptFreeContext(poptContext con);

       void poptResetContext(poptContext con);

       int poptGetNextOpt(poptContext con);

       const char * poptGetOptArg(poptContext con);

       const char * poptGetArg(poptContext con);

       const char * poptPeekArg(poptContext con);

       const char ** poptGetArgs(poptContext con);

       const char *const poptStrerror(const int error);

       const char * poptBadOption(poptContext con, int flags);

       int poptReadDefaultConfig(poptContext con, int flags);

       int poptReadConfigFile(poptContext con, char * fn);

       int poptAddAlias(poptContext con, struct poptAlias alias,
                        int flags);

       int poptParseArgvString(char * s, int *  argcPtr,
                               const char *** argvPtr);

       int poptDupArgv(int argc, const char ** argv, int * argcPtr,
                               const char *** argvPtr);

       int poptStuffArgs(poptContext con, const char ** argv);

DESCRIPTION

       The popt library exists essentially for parsing command-line options. It is found superior
       in many ways when compared to parsing the argv array by hand or using the getopt functions
       getopt() and getopt_long() [see getopt(3)].  Some specific advantages of popt are: it does
       not utilize global variables, thus enabling multiple passes in parsing argv ; it can parse
       an  arbitrary  array of argv-style elements, allowing parsing of command-line-strings from
       any source; it provides a standard method of option aliasing (to be  discussed  at  length
       below.);  it can exec external option filters; and, finally, it can automatically generate
       help and usage messages for the application.

       Like getopt_long(), the popt library supports short and long style options.  Recall that a
       short  option  consists  of  a - character followed by a single alphanumeric character.  A
       long option, common in GNU utilities, consists of two - characters followed  by  a  string
       made  up  of  letters,  numbers and hyphens.  Long options are optionally allowed to begin
       with a single -, primarily to allow command-line compatibility between  popt  applications
       and  X  toolkit  applications.   Either  type of option may be followed by an argument.  A
       space separates a short option from its arguments; either a space or an = separates a long
       option from an argument.

       The  popt  library  is  highly portable and should work on any POSIX platform.  The latest
       version    is    distributed    with    rpm    and    is    always     available     from:
       ftp://ftp.rpm.org/pub/rpm/dist.

       It  may  be redistributed under the X consortium license, see the file COPYING in the popt
       source distribution for details.

BASIC POPT USAGE

   1. THE OPTION TABLE
       Applications provide popt with information on their command-line options by  means  of  an
       "option table," i.e., an array of struct poptOption structures:

       #include <popt.h>

       struct poptOption {
           const char * longName;   /* may be NULL */
           char shortName;          /* may be '\0' */
           unsigned int argInfo;    /* type of argument expected after the option */
           void * arg;              /* depends on argInfo */
           int val;                 /* 0 means don't return, just update arg */
           const char * descrip;    /* description for autohelp -- may be NULL */
           const char * argDescrip; /* argument description for autohelp -- may be NULL*/
       };

       Each  member of the table defines a single option that may be passed to the program.  Long
       and short options are considered a single option that may occur in  two  different  forms.
       The  first  two members, longName and shortName, define the names of the option; the first
       is a long name, while the latter is a single character.

       The argInfo member tells popt what type of argument is expected after the option.   If  no
       argument is expected, POPT_ARG_NONE should be used.  The valid values of argInfo are shown
       in the following table:

       Value               Description                        arg Type
       POPT_ARG_NONE       No argument expected               int
       POPT_ARG_STRING     No type checking to be performed   char *
       POPT_ARG_ARGV       No type checking to be performed   char **
       POPT_ARG_SHORT      A short argument is expected       short
       POPT_ARG_INT        An integer argument is expected    int
       POPT_ARG_LONG       A long integer is expected         long
       POPT_ARG_LONGLONG   A long long integer is expected    long long
       POPT_ARG_VAL        Integer value taken from val       int
       POPT_ARG_FLOAT      A float argument is expected       float
       POPT_ARG_DOUBLE     A double argument is expected      double

       For numeric values, if the argInfo value is bitwise  or'd  with  one  of  POPT_ARGFLAG_OR,
       POPT_ARGFLAG_AND,  or  POPT_ARGFLAG_XOR,  the  value is saved by performing an OR, AND, or
       XOR.  If the argInfo value is bitwise  or'd  with  POPT_ARGFLAG_NOT,  the  value  will  be
       negated  before  saving.  For  the  common  operations  of  setting  and/or clearing bits,
       POPT_BIT_SET and POPT_BIT_CLR have the appropriate flags set to perform bit operations.

       If the argInfo value is bitwise or'd with POPT_ARGFLAG_ONEDASH, the long argument  may  be
       given  with  a  single  -  instead  of  two.  For  example, if --longopt is an option with
       POPT_ARGFLAG_ONEDASH, is specified, -longopt is accepted as well.

       The next element, arg, allows popt to automatically  update  program  variables  when  the
       option is used. If arg is NULL, it is ignored and popt takes no special action.  Otherwise
       it should point to a variable of the type indicated in the right-most column of the  table
       above.  A  POPT_ARG_ARGV arg will (re-)allocate an array of char * string pointers, append
       the string argument, and add a NULL sentinel at the end  of  the  array  as  needed.   The
       target char ** address of a POPT_ARG_ARGV arg should be initialized to NULL.

       If the option takes no argument (argInfo is POPT_ARG_NONE), the variable pointed to by arg
       is set to 1 when the option is used.   (Incidentally,  it  will  perhaps  not  escape  the
       attention  of  hunt-and-peck typists that the value of POPT_ARG_NONE is 0.)  If the option
       does take an argument, the variable that arg points to is updated to reflect the value  of
       the  argument.   Any string is acceptable for POPT_ARG_STRING and POPT_ARG_ARGV arguments,
       but POPT_ARG_INT, POPT_ARG_SHORT, POPT_ARG_LONG,  POPT_ARG_LONGLONG,  POPT_ARG_FLOAT,  and
       POPT_ARG_DOUBLE  are  converted  to  the  appropriate  type,  and an error returned if the
       conversion fails.

       POPT_ARG_VAL causes arg to be set to the (integer) value  of  val  when  the  argument  is
       found.   This  is  most often useful for mutually-exclusive arguments in cases where it is
       not an error for multiple arguments  to  occur  and  where  you  want  the  last  argument
       specified  to  win; for example, "rm -i -f".  POPT_ARG_VAL causes the parsing function not
       to return a value, since the value of val has already been used.

       If the argInfo value is bitwise or'd with POPT_ARGFLAG_OPTIONAL, the argument to the  long
       option  may be omitted. If the long option is used without an argument, a default value of
       zero or NULL will be saved (if the arg pointer is present),  otherwise  behavior  will  be
       identical to a long option with argument.

       The  next  option, val, is the value popt's parsing function should return when the option
       is encountered.  If it is 0, the parsing function does not return a value, instead parsing
       the next command-line argument.

       The  last two options, descrip and argDescrip are only required if automatic help messages
       are desired (automatic usage messages can be generated without them). descrip  is  a  text
       description of the argument and argDescrip is a short summary of the type of arguments the
       option expects, or NULL if the option doesn't require any arguments.

       If popt should automatically provide --usage and --help (-?)  options,  one  line  in  the
       table  should  be  the macro POPT_AUTOHELP.  This macro includes another option table (via
       POPT_ARG_INCLUDE_TABLE ; see below) in the main one which provides the table  entries  for
       these  arguments. When --usage or --help are passed to programs which use popt's automatic
       help, popt displays the appropriate message on stderr as soon as it finds the option,  and
       exits  the  program  with  a  return  code  of 0. If you want to use popt's automatic help
       generation in a different way, you need to explicitly  add  the  option  entries  to  your
       programs option table instead of using POPT_AUTOHELP.

       If  the  argInfo value is bitwise or'd with POPT_ARGFLAG_DOC_HIDDEN, the argument will not
       be shown in help output.

       If the argInfo value is bitwise or'd with POPT_ARGFLAG_SHOW_DEFAULT, the initial value  of
       the arg will be shown in help output.

       The  final  structure  in the table should have all the pointer values set to NULL and all
       the arithmetic values set to 0, marking the end of the table. The macro  POPT_TABLEEND  is
       provided to do that.

       There  are  two  types  of option table entries which do not specify command line options.
       When either of these types of entries are used, the longName element must be NULL and  the
       shortName element must be '\0'.

       The first of these special entry types allows the application to nest another option table
       in the current one; such nesting may extend quite deeply (the actual depth is  limited  by
       the program's stack). Including other option tables allows a library to provide a standard
       set of command-line options to every  program  which  uses  it  (this  is  often  done  in
       graphical  programming  toolkits,  for  example).  To  do  this,  set the argInfo field to
       POPT_ARG_INCLUDE_TABLE and the arg field to point to the table which is being included. If
       automatic  help  generation  is  being  used,  the descrip field should contain an overall
       description of the option table being included.

       The other special option table entry type tells popt to call a function (a callback)  when
       any  option  in that table is found. This is especially useful when included option tables
       are being used, as the program which provides the top-level option table doesn't  need  to
       be aware of the other options which are provided by the included table. When a callback is
       set for a table, the parsing function never returns information on an option in the table.
       Instead,  options  information  must  be retained via the callback or by having popt set a
       variable through the option's arg field.  Option  callbacks  should  match  the  following
       prototype:

       void poptCallbackType(poptContext con,
                             const struct poptOption * opt,
                             const char * arg, void * data);

       The  first  parameter  is  the  context  which  is  being parsed (see the next section for
       information on contexts), opt points to the option which triggered this callback, and  arg
       is  the  option's  argument.   If  the option does not take an argument, arg is NULL.  The
       final parameter, data is taken from the descrip field of  the  option  table  entry  which
       defined the callback. As descrip is a pointer, this allows callback functions to be passed
       an arbitrary set of data (though a typecast will have to be used).

       The option table entry which defines a callback has an argInfo  of  POPT_ARG_CALLBACK,  an
       arg  which  points  to  the  callback  function,  and  a  descrip field which specifies an
       arbitrary pointer to be passed to the callback.

   2. CREATING A CONTEXT
       popt can interleave the parsing of multiple command-line sets. It allows this  by  keeping
       all  the state information for a particular set of command-line arguments in a poptContext
       data structure, an opaque type that should not be modified outside the popt library.

       New popt contexts are created by poptGetContext():

       poptContext poptGetContext(const char * name, int argc,
                                  const char ** argv,
                                  const struct poptOption * options,
                                  unsigned int flags);

       The first parameter, name, is used only for alias handling (discussed later). It should be
       the name of the application whose options are being parsed, or should be NULL if no option
       aliasing is desired. The next two arguments specify the command-line arguments  to  parse.
       These  are  generally  passed  to  poptGetContext()  exactly  as  they  were passed to the
       program's main() function. The options parameter  points  to  the  table  of  command-line
       options,  which  was described in the previous section. The final parameter, flags, can be
       any bitwise or combination of the following four values:

       Value                        Description
       POPT_CONTEXT_NO_EXEC         Ignore exec expansions
       POPT_CONTEXT_KEEP_FIRST      Do not ignore argv[0]
       POPT_CONTEXT_POSIXMEHARDER   Options cannot follow arguments
       POPT_CONTEXT_ARG_OPTS        Return the arguments as options of value 0

       A poptContext keeps track of which options have already  been  parsed  and  which  remain,
       among  other  things.  If  a  program  wishes  to  restart  option  processing of a set of
       arguments, it can reset the poptContext by passing the context as  the  sole  argument  to
       poptResetContext().

       When  argument  processing  is  complete,  the  process  should free the poptContext as it
       contains  dynamically  allocated  components.  The  poptFreeContext()  function  takes   a
       poptContext as its sole argument and frees the resources the context is using.

       Here are the prototypes of both poptResetContext() and poptFreeContext():

       #include <popt.h>
       void poptFreeContext(poptContext con);
       void poptResetContext(poptContext con);

   3. PARSING THE COMMAND LINE
       After  an  application  has  created  a  poptContext,  it  may  begin  parsing  arguments.
       poptGetNextOpt() performs the actual argument parsing.

       #include <popt.h>
       int poptGetNextOpt(poptContext con);

       Taking the context as its sole  argument,  this  function  parses  the  next  command-line
       argument found. After finding the next argument in the option table, the function fills in
       the object pointed to by the option table entry's arg pointer if it is not  NULL.  If  the
       val  entry  for  the  option  is  non-0,  the function then returns that value. Otherwise,
       poptGetNextOpt() continues on to the next argument.

       poptGetNextOpt() returns -1 when the final argument has been parsed,  and  other  negative
       values  when  errors  occur.  This  makes  it  a good idea to keep the val elements in the
       options table greater than 0.

       If all of the command-line options are handled through arg pointers, command-line  parsing
       is reduced to the following line of code:

       rc = poptGetNextOpt(poptcon);

       Many  applications  require  more complex command-line parsing than this, however, and use
       the following structure:

       while ((rc = poptGetNextOpt(poptcon)) > 0) {
            switch (rc) {
                 /* specific arguments are handled here */
            }
       }

       When returned options are handled,  the  application  needs  to  know  the  value  of  any
       arguments  that  were specified after the option. There are two ways to discover them. One
       is to ask popt to fill in a variable with the value  of  the  option  through  the  option
       table's arg elements. The other is to use poptGetOptArg():

       #include <popt.h>
       char * poptGetOptArg(poptContext con);

       This   function   returns   the   argument   given   for  the  final  option  returned  by
       poptGetNextOpt(), or it returns NULL if no argument was specified.  The  calling  function
       is responsible for deallocating this string.

   4. LEFTOVER ARGUMENTS
       Many  applications  take  an arbitrary number of command-line arguments, such as a list of
       file names. When popt encounters an argument that does not begin with a -, it  assumes  it
       is  such  an  argument  and adds it to a list of leftover arguments. Three functions allow
       applications to access such arguments:

       const char * poptGetArg(poptContext con);
              This function returns the next leftover argument and marks it as processed.

       const char * poptPeekArg(poptContext con);
              The next leftover argument is returned but not marked as processed.  This allows an
              application to look ahead into the argument list, without modifying the list.

       const char ** poptGetArgs(poptContext con);
              All  the  leftover arguments are returned in a manner identical to argv.  The final
              element in the returned array points to NULL, indicating the end of the arguments.

   5. AUTOMATIC HELP MESSAGES
       The popt library can automatically generate help messages which  describe  the  options  a
       program  accepts.  There  are  two  types  of  help messages which can be generated. Usage
       messages are a short messages which lists valid options, but does not describe them.  Help
       messages  describe  each  option  on  one (or more) lines, resulting in a longer, but more
       useful, message. Whenever automatic help messages are used,  the  descrip  and  argDescrip
       fields struct poptOption members should be filled in for each option.

       The  POPT_AUTOHELP macro makes it easy to add --usage and --help messages to your program,
       and is described in part 1 of this man page. If more control  is  needed  over  your  help
       messages, the following two functions are available:

       #include <popt.h>
       void poptPrintHelp(poptContext con, FILE * f, int flags);
       void poptPrintUsage(poptContext con, FILE * f, int flags);

       poptPrintHelp()  displays  the standard help message to the stdio file descriptor f, while
       poptPrintUsage() displays the shorter usage message. Both functions currently  ignore  the
       flags argument; it is there to allow future changes.

ERROR HANDLING

       All of the popt functions that can return errors return integers.  When an error occurs, a
       negative error code is returned. The following  table  summarizes  the  error  codes  that
       occur:

       Error                     Description
       POPT_ERROR_NOARG          Argument missing for an option.
       POPT_ERROR_BADOPT         Option's argument couldn't be parsed.
       POPT_ERROR_UNWANTEDARG    Option does not take an argument.
       POPT_ERROR_OPTSTOODEEP    Option aliasing nested too deeply.
       POPT_ERROR_BADQUOTE       Quotations do not match.
       POPT_ERROR_ERRNO          errno set, use strerror(errno).
       POPT_ERROR_BADNUMBER      Option couldn't be converted to number.
       POPT_ERROR_OVERFLOW       A given number was too big or small.
       POPT_ERROR_BADOPERATION   Mutually exclusive logical operations requested.
       POPT_ERROR_NULLARG        opt->arg should not be NULL.
       POPT_ERROR_MALLOC         Memory allocation failed.
       POPT_ERROR_BADCONFIG      Config file failed sanity test.

       Here is a more detailed discussion of each error:

       POPT_ERROR_NOARG
              An  option  that  requires  an  argument  was specified on the command line, but no
              argument was given. This can be returned only by poptGetNextOpt().

       POPT_ERROR_BADOPT
              An option was specified in argv but is not in the option table. This error  can  be
              returned only from poptGetNextOpt().

       POPT_ERROR_OPTSTOODEEP
              A  set of option aliases is nested too deeply. Currently, popt follows options only
              10 levels (POPT_OPTION_DEPTH) to prevent infinite recursion. Only  poptGetNextOpt()
              can return this error.

       POPT_ERROR_BADQUOTE
              A  parsed  string  has  a  quotation  mismatch  (such  as a single quotation mark).
              poptParseArgvString(), poptReadConfigFile(), or poptReadDefaultConfig() can  return
              this error.

       POPT_ERROR_ERRNO
              A  system  call returned with an error, and errno still contains the error from the
              system call. Both poptReadConfigFile() and poptReadDefaultConfig() can return  this
              error.

       POPT_ERROR_BADNUMBER
              A  conversion  from  a  string  to  a number (int or long) failed due to the string
              containing non-numeric characters. This occurs when poptGetNextOpt() is  processing
              an argument of type POPT_ARG_INT, POPT_ARG_SHORT, POPT_ARG_LONG, POPT_ARG_LONGLONG,
              POPT_ARG_FLOAT, or POPT_ARG_DOUBLE.

       POPT_ERROR_OVERFLOW
              A string-to-number conversion failed because the number was too large or too small.
              Like  POPT_ERROR_BADNUMBER,  this  error  can  occur  only when poptGetNextOpt() is
              processing  an  argument  of  type  POPT_ARG_INT,  POPT_ARG_SHORT,   POPT_ARG_LONG,
              POPT_ARG_LONGLONG, POPT_ARG_FLOAT, or POPT_ARG_DOUBLE.

       POPT_ERROR_BADOPERATION
              More  than  one  logical  operation  (AND, OR, XOR) was specified for an option, or
              POPT_ARGFLAG_RANDOM was specified but the platform does not  support  the  random()
              function.   This  can  be  returned  only  by  poptSaveLongLong(),  poptSaveLong(),
              poptSaveInt(), poptSaveShort() and poptGetNextOpt().

       POPT_ERROR_NULLARG
              An operation was invoked  on  a  null  target  arg  (including  zero-length  string
              arguments). In the poptBitsArgs() case, this includes an empty leftover argv array.
              This  can  only  be  returned  by  the  poptBits*()  and   poptSave*()   functions,
              poptConfigFileToString() and poptGetNextOpt().

       POPT_ERROR_MALLOC
              Memory   allocation   failed.   This   can  only  be  returned  by  poptReadFile(),
              poptDupArgv(),      poptParseArgvString(),       poptConfigFileToString()       and
              poptGetNextOpt().

       POPT_ERROR_BADCONFIG
              The  popt  configuration  files  are  corrupted.  This  can  only  be  returned  by
              poptReadConfigFile() and poptReadConfigFiles().

       Two functions are available to make  it  easy  for  applications  to  provide  good  error
       messages.

              const char *const poptStrerror(const int error);
              This  function  takes  a popt error code and returns a string describing the error,
              just as with the standard strerror() function.

              const char * poptBadOption(poptContext con, int flags);
              If an error occurred during poptGetNextOpt(), this function returns the option that
              caused  the  error.  If  the  flags  argument is set to POPT_BADOPTION_NOALIAS, the
              outermost option is returned. Otherwise, flags should be 0, and the option that  is
              returned may have been specified through an alias.

       These  two functions make popt error handling trivial for most applications. When an error
       is detected from most of the functions, an error message is printed along with  the  error
       string  from poptStrerror(). When an error occurs during argument parsing, code similar to
       the following displays a useful error message:

       fprintf(stderr, "%s: %s\n",
               poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
               poptStrerror(rc));

OPTION ALIASING

       One of the primary benefits of using popt over getopt()  is  the  ability  to  use  option
       aliasing.  This  lets  the  user specify options that popt expands into other options when
       they are specified. If the standard grep program made use  of  popt,  users  could  add  a
       --text  option  that  expanded  to -i -n -E -2 to let them more easily find information in
       text files.

   1. SPECIFYING ALIASES
       Aliases are normally specified in two places: /etc/popt and the .popt file in  the  user's
       home  directory  (found  through  the HOME environment variable). Both files have the same
       format, an arbitrary number of lines formatted like this:

       appname alias newoption expansion

       The appname is the name of the application, which must be the same as the  name  parameter
       passed  to  poptGetContext().  This  allows  each  file  to  specify  aliases for multiple
       programs. The alias keyword specifies that an  alias  is  being  defined;  currently  popt
       configuration  files support only aliases, but other abilities may be added in the future.
       The next option is the option that should be aliased, and it may be either a  short  or  a
       long  option.  The  rest  of  the line specifies the expansion for the alias. It is parsed
       similarly to a shell command, which allows \, ", and '  to  be  used  for  quoting.  If  a
       backslash  is  the final character on a line, the next line in the file is assumed to be a
       logical continuation of the line containing the backslash, just as in shell.

       The following entry would add a --text option to the grep command,  as  suggested  at  the
       beginning of this section.

       grep alias --text -i -n -E -2

   2. ENABLING ALIASES
       An   application   must   enable   alias   expansion  for  a  poptContext  before  calling
       poptGetNextArg() for the first time. There are three functions that define aliases  for  a
       context:

              int poptReadDefaultConfig(poptContext con, int flags);
              This  function  reads  aliases from /etc/popt and the .popt file in the user's home
              directory. Currently, flags should be NULL, as  it  is  provided  only  for  future
              expansion.

              int poptReadConfigFile(poptContext con, char * fn);
              The  file  specified  by fn is opened and parsed as a popt configuration file. This
              allows programs to use program-specific configuration files.

              int poptAddAlias(poptContext con, struct poptAlias alias,
                               int flags);
              Occasionally, processes want to specify aliases without having to read them from  a
              configuration file. This function adds a new alias to a context. The flags argument
              should be 0, as it is currently reserved for future expansion.  The  new  alias  is
              specified as a struct poptAlias, which is defined as:

              struct poptAlias {
                   const char * longName; /* may be NULL */
                   char shortName; /* may be '\0' */
                   int argc;
                   const char ** argv; /* must be free()able */
              };

              The first two elements, longName and shortName, specify the option that is aliased.
              The final two, argc and argv, define the expansion to use when the  aliases  option
              is encountered.

PARSING ARGUMENT STRINGS

       Although  popt  is  usually  used for parsing arguments already divided into an argv-style
       array, some programs need to parse strings  that  are  formatted  identically  to  command
       lines.  To facilitate this, popt provides a function that parses a string into an array of
       strings, using rules similar to normal shell parsing.

       #include <popt.h>
       int poptParseArgvString(char * s, int * argcPtr,
                               char *** argvPtr);
       int poptDupArgv(int argc, const char ** argv, int * argcPtr,
                               const char *** argvPtr);

       The string s is parsed into an argv-style array. The integer pointed  to  by  the  argcPtr
       parameter contains the number of elements parsed, and the final argvPtr parameter contains
       the address of the newly created array.  The routine poptDupArgv() can be used to  make  a
       copy of an existing argument array.

       The argvPtr created by poptParseArgvString() or poptDupArgv() is suitable to pass directly
       to poptGetContext().  Both routines return a single dynamically allocated contiguous block
       of storage and should be free()ed when the application is finished with the storage.

HANDLING EXTRA ARGUMENTS

       Some  applications  implement  the equivalent of option aliasing but need to do so through
       special logic. The poptStuffArgs() function allows an application to insert new  arguments
       into the current poptContext.

       #include <popt.h>
       int poptStuffArgs(poptContext con, const char ** argv);

       The  passed  argv  must have a NULL pointer as its final element. When poptGetNextOpt() is
       next called, the "stuffed" arguments are the first to  be  parsed.  popt  returns  to  the
       normal arguments once all the stuffed arguments have been exhausted.

EXAMPLE

       The  following  example  is  a  simplified version of the program "robin" which appears in
       Chapter 15 of the text cited below.   Robin  has  been  stripped  of  everything  but  its
       argument-parsing  logic,  slightly  reworked,  and renamed "parse." It may prove useful in
       illustrating at least some of the features of the extremely rich popt library.

       #include <popt.h>
       #include <stdio.h>
       #include <stdlib.h>

       void usage(poptContext optCon, int exitcode, char *error, char *addl) {
           poptPrintUsage(optCon, stderr, 0);
           if (error) fprintf(stderr, "%s: %s\n", error, addl);
           exit(exitcode);
       }

       int main(int argc, char *argv[]) {
          int     c;            /* used for argument parsing */
          int     i = 0;        /* used for tracking options */
          int     speed = 0;    /* used in argument parsing to set speed */
          int     raw = 0;      /* raw mode? */
          int     j;
          char    buf[BUFSIZ+1];
          const char *portname;
          poptContext optCon;   /* context for parsing command-line options */

          struct poptOption optionsTable[] = {
             { "bps", 'b', POPT_ARG_INT, &speed, 0,
                              "signaling rate in bits-per-second", "BPS" },
             { "crnl", 'c', 0, 0, 'c',
                              "expand cr characters to cr/lf sequences", NULL },
             { "hwflow", 'h', 0, 0, 'h',
                              "use hardware (RTS/CTS) flow control", NULL },
             { "noflow", 'n', 0, 0, 'n',
                              "use no flow control", NULL },
             { "raw", 'r', 0, &raw, 0,
                              "don't perform any character conversions", NULL },
             { "swflow", 's', 0, 0, 's',
                              "use software (XON/XOF) flow control", NULL } ,
             POPT_AUTOHELP
             { NULL, 0, 0, NULL, 0 }
           };

          optCon = poptGetContext(NULL, argc, argv, optionsTable, 0);
          poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");

          if (argc < 2) {
                              poptPrintUsage(optCon, stderr, 0);
                              exit(1);
          }

          /* Now do options processing, get portname */
          while ((c = poptGetNextOpt(optCon)) >= 0) {
             switch (c) {
              case 'c':
                 buf[i++] = 'c';
                 break;
              case 'h':
                 buf[i++] = 'h';
                 break;
              case 's':
                 buf[i++] = 's';
                 break;
              case 'n':
                 buf[i++] = 'n';
                 break;
             }
          }
          portname = poptGetArg(optCon);
          if((portname == NULL) || !(poptPeekArg(optCon) == NULL))
             usage(optCon, 1, "Specify a single port", ".e.g., /dev/cua0");

          if (c < -1) {
             /* an error occurred during option processing */
             fprintf(stderr, "%s: %s\n",
                     poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
                     poptStrerror(c));
             return 1;
          }

          /* Print out options, portname chosen */
          printf("Options  chosen: ");
          for(j = 0; j < i ; j++)
             printf("-%c ", buf[j]);
          if(raw) printf("-r ");
          if(speed) printf("-b %d ", speed);
          printf("\nPortname chosen: %s\n", portname);

          poptFreeContext(optCon);
          exit(0);
       }

       RPM, a popular Linux package management program, makes heavy use of popt's features.  Many
       of  its  command-line  arguments  are implemented through popt aliases, which makes RPM an
       excellent example of how to take advantage of the popt library. For  more  information  on
       RPM,  see  http://www.rpm.org.  The popt source code distribution includes test program(s)
       which use all of the features of the popt libraries in various ways. If  a  feature  isn't
       working for you, the popt test code is the first place to look.

BUGS

       None presently known.

AUTHOR

       Erik W. Troan <ewt@redhat.com>

       This  man page is derived in part from Linux Application Development by Michael K. Johnson
       and Erik W. Troan, Copyright (c) 1998 by Addison Wesley Longman, Inc., and included in the
       popt  documentation  with  the  permission  of  the  Publisher and the appreciation of the
       Authors.

       Thanks to Robert Lynch for his extensive work on this man page.

SEE ALSO

       getopt(3)

       Linux Application Development, by Michael K. Johnson and Erik  W.  Troan  (Addison-Wesley,
       1998; ISBN 0-201-30821-5), Chapter 24.

       popt.ps  is  a  Postscript version of the above cited book chapter. It can be found in the
       source archive for popt available at: ftp://ftp.rpm.org/pub/rpm.

                                          June 30, 1998                                   POPT(3)