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)