Provided by: libpopt-dev_1.16-12_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,
                                  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' */
           int argInfo;
           void * arg;            /* depends on argInfo */
           int val;               /* 0 means don't return, just update flag */
           char * descrip;        /* description for autohelp -- may be NULL */
           char * argDescrip;     /* argument description for autohelp */
       };

       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 rest of the valid values 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      An 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      An 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 a 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,
                                  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 take
       one of three 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

       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_OPTSTOODEEP Option aliasing nested too deeply.
       POPT_ERROR_BADQUOTE    Quotations do not match.
       POPT_ERROR_BADNUMBER   Option couldn't be converted to number.
       POPT_ERROR_OVERFLOW    A given number was too big or small.

       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 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_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_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.

       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)