POPT(3)             Linux Programmer's Manual             POPT(3)

       popt - Parse command line options

       #include <popt.h>

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

       void poptFreeContext(poptContext con);

       void poptResetContext(poptContext con);

       int poptGetNextOpt(poptContext con);

       char * poptGetOptArg(poptContext con);

       char * poptGetArg(poptContext con);

       char * poptPeekArg(poptContext con);

       char ** poptGetArgs(poptContext con);

       const char * poptStrerror(const int error);

       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,
                               char *** argvPtr);

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

       The  popt  library exists essentially for parsing command-
       line options. It is found superior in many ways when  com-
       pared  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 auto-
       matically generate help and usage messages for the  appli-

       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 charac-
       ter.  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 argu-
       ments; 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 always available
       from: ftp://ftp.redhat.com/pub/redhat/code/popt.

       It may be redistributed under either the GNU General  Pub-
       lic  License or the GNU Library General Public License, at
       the distributor's discretion.

       Applications provide popt with information on  their  com-
       mand-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 con-
       sidered 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 argument.  If no  option  is  expected,
       POPT_ARG_NONE  should be used.  The rest of the valid val-
       ues 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_INT      An integer argument is expected    int
       POPT_ARG_LONG     A long integer is expected         long
       POPT_ARG_VAL      Integer value taken from val       int

       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.

       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  accept-
       able  for  POPT_ARG_STRING arguments, but POPT_ARG_INT and
       POPT_ARG_LONG 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

       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
       automatical help, popt displays the appropriate message on
       stderr  as soon as it finds the option, and exits the pro-
       gram 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.

       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.

       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 applica-
       tion to nest another option table in the current one; such
       nesting may extend quite deeply (the actual depth is  lim-
       ited  by  the  program's  stack).  Including  other option
       tables allows a library to provide a standard set of  com-
       mand-line  options to every program which uses it (this is
       often done in graphical programming  toolkits,  for  exam-
       ple).   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 genera-
       tion 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 usefull 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.

       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 popt-
       Context data structure, an opaque type that should not  be
       modified outside the popt library.

       New popt contexts are created by poptGetContext():

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

       The first parameter, name, is used only for alias handling
       (discussed later). It should be the name of  the  applica-
       tion  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,is not currently used but  should  always
       be  specified  as 0 for compatibility with future versions
       of the popt library.

       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  popt-
       Context  as  its sole argument and frees the resources the
       context is using.

       Here are the prototypes  of  both  poptResetContext()  and

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

       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  pars-
       ing 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.

       Many applications take an arbitrary number of command-line
       arguments, such as a list of file names. When popt encoun-
       ters 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:

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

       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  modify-
              ing the list.

       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.

       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.

       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:

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

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

              A  set of option aliases is nested too deeply. Cur-
              rently, popt follows options only 10 levels to pre-
              vent  infinite recursion. Only poptGetNextOpt() can
              return this error.

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

              A  conversion  from  a  string  to a number (int or
              long) failed due to the  string  containing  nonnu-
              meric characters. This occurs when poptGetNextOpt()
              is processing an argument of type  POPT_ARG_INT  or

              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 or POPT_ARG_LONG.

              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  applica-
       tions to provide good error messages.

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

       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_BADOP-
              TION_NOALIAS, the  outermost  option  is  returned.
              Otherwise,  flags  should be 0, and the option that
              is returned may  have  been  specified  through  an

       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 similiar to the following
       displays a useful error message:

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

       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.

       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 pro-
       grams.  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

       An application must enable alias expansion for a  poptCon-
       text  before  calling poptGetNextArg() for the first time.
       There are three functions that define aliases for  a  con-

       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

              struct poptAlias {
                   char * longName; /* may be NULL */
                   char shortName; /* may be '\0' */
                   int argc;
                   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.

       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  func-
       tion  that parses a string into an array of strings, using
       rules similiar to normal shell parsing.

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

       The string s is parsed into an argv-style array. The inte-
       ger  pointed to by the second parameter, argcPtr, contains
       the number of elements parsed, and the pointer pointed  to
       by  the  final parameter is set to point to the newly cre-
       ated array. The array is dynamically allocated and  should
       be free()ed when the application is finished with it.

       The  argvPtr  created by poptParseArgvString() is suitable
       to pass directly to poptGetContext().

       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, char ** argv);

       The passed argv must have a NULL pointer as its final ele-
       ment. 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

       The  following example is a simplified version of the pro-
       gram "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>

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

       int main(int argc, char *argv[]) {
          char    c;            /* used for argument parsing */
          int     i = 0;        /* used for tracking options */
          char    *portname;
          int     speed = 0;    /* used in argument parsing to set speed */
          int     raw = 0;      /* raw mode? */
          int     j;
          char    buf[BUFSIZ+1];
          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" },
                          { "hwflow", 'h', 0, 0, 'h',
                                                         "use hardware (RTS/CTS) flow control" },
                          { "noflow", 'n', 0, 0, 'n',
                                                         "use no flow control" },
                          { "raw", 'r', 0, &raw, 0,
                                                         "don't perform any character conversions" },
                          { "swflow", 's', 0, 0, 's',
                                                         "use software (XON/XOF) flow control" } ,
                          { NULL, 0, 0, NULL, 0 }

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

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

          /* Now do options processing, get portname */
          while ((c = poptGetNextOpt(optCon)) >= 0) {
             switch (c) {
                case 'c':
                   buf[i++] = 'c';
                case 'h':
                   buf[i++] = 'h';
                case 's':
                   buf[i++] = 's';
                case 'n':
                   buf[i++] = 'n';
          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),
             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);


       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

       None presently known.

       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, Copy-
       right  (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


       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.redhat.com/pub/redhat/code/popt

                          June 30, 1998                         1