packages icon



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

                                June 30, 1998



 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()



                                    - 1 -       Formatted:  December 5, 2024






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

                                June 30, 1998



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



                                    - 2 -       Formatted:  December 5, 2024






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

                                June 30, 1998



      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:

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



                                    - 3 -       Formatted:  December 5, 2024






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

                                June 30, 1998



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




                                    - 4 -       Formatted:  December 5, 2024






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

                                June 30, 1998



      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,



                                    - 5 -       Formatted:  December 5, 2024






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

                                June 30, 1998



                                 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:
      lfB lfB lfB lfR.  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.



                                    - 6 -       Formatted:  December 5, 2024






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

                                June 30, 1998



      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.



                                    - 7 -       Formatted:  December 5, 2024






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

                                June 30, 1998



      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:

      lfB lfB lfB lfR.  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.




                                    - 8 -       Formatted:  December 5, 2024






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

                                June 30, 1998



      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_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_FLOAT,
           or POPT_ARG_DOUBLE.


      POPT_ERROR_BADOPERATION



                                    - 9 -       Formatted:  December 5, 2024






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

                                June 30, 1998



           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),



                                   - 10 -       Formatted:  December 5, 2024






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

                                June 30, 1998



              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

      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);



                                   - 11 -       Formatted:  December 5, 2024






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

                                June 30, 1998



           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



                                   - 12 -       Formatted:  December 5, 2024






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

                                June 30, 1998



      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 },



                                   - 13 -       Formatted:  December 5, 2024






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

                                June 30, 1998



            { "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);



                                   - 14 -       Formatted:  December 5, 2024






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

                                June 30, 1998



         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.















                                   - 15 -       Formatted:  December 5, 2024