Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

libpopt (3)

Name

libpopt - line options #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); The popt library parses command-line options. The popt library provides an alternative to parsing the argv array by hand, or using the getopt(3) functions getopt() and getopt_long(). The popt library has the following advantages: o popt does not use global variables, thus enabling multiple passes in parsing argv. o popt can parse an arbitrary array of argv-style elements, allowing parsing of command-line strings from any source. o popt provides a standard method of option aliasing. This feature is discussed in detail below. o popt can exec external option filters. o popt can automatically generate help and usage messages for the application. The popt library supports short and long options. A short option con- sists of a hyphen followed by a single alphanumeric character. A long option, common in GNU utilities, consists of two hyphens followed by a string composed of letters, numbers, and hyphens. Long options can optionally begin with a single hyphen, primarily to allow command-line compatibility between popt applications and X toolkit applications. Either type of option can be followed by an argument. A space separates a short option from its argument. Either a space or an equals sign sep- arates a long option from an argument. The popt library is highly portable and should work on any POSIX plat- form. The latest version is distributed with rpm and is available from: ftp://ftp.rpm.org/pub/rpm/dist. The popt library may be redistributed under the X consortium license, see the file COPYING in the popt source distribution for details. Option Tables Each application provides popt with information about the command-line options for the application, by means of an option table. An option ta- ble is an array of struct poptOption structures, with the following format: #include <popt.h> struct poptOption { const char * longName; /* may be NULL */ char shortName; /* may be ' ' */ int argInfo; void * arg; /* depends on argInfo */ int val; /* 0 means do not return, just update flag */ char * descrip; /* description for autohelp -- may be NULL */ char * argDescrip; /* argument description for autohelp */ }; Option Table Members Each member of the table defines a single option that may be passed to the program. Long and short options are considered to be a single option that can occur in two different forms. The option table members are as follows: longName Defines the name of the option in a long name. shortName Defines the name of the option in a single character. argInfo Tells popt what type of argument is expected after the option. Valid values are as follows: POPT_ARG_DOUBLE Double argument expected, arg type: double POPT_ARG_FLOAT Float argument expected, arg type: float POPT_ARG_INT Integer argument expected, arg type: int POPT_ARG_LONG Long integer expected, arg type: long POPT_ARG_NONE No argument expected, arg type: int POPT_ARG_STRING No type checking to be per- formed, arg type: char * POPT_ARG_VAL Integer value taken from val, arg type: int 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 is negated before saving. For the common operations of setting or clearing bits, POPT_BIT_SET and POPT_BIT_CLR have the appropriate flags set to perform bit operations. If the argInfovalue is bitwise or'd with POPT_ARGFLAG_ONEDASH, the long argument may be given with a single hyphen instead of two. For example, if --longopt is an option with POPT_ARGFLAG_ONEDASH, -longopt is also accepted. arg Allows popt to automatically update program variables. If arg is NULL, popt ignores arg and takes no special action. Otherwise, arg points to a variable of the appropriate type, as fol- lows: o If argInfo is POPT_ARG_NONE, the variable pointed to by arg is set to 1 when the option is used. o If the option takes an argument, the vari- able pointed to by arg is updated to reflect the value of the argument. Any string is acceptable for POPT_ARG_STRING arguments. POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, and POPT_ARG_DOUBLE argu- ments are converted to the appropriate type, and an error returned if the conver- sion fails. POPT_ARG_VAL causes arg to be set to the inte- ger value of val when the argument is found. This is 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 take precedence, for example, rm -i -f. POPT_ARG_VAL causes the parsing function not to return a value, because 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 is saved if the arg pointer is present. Otherwise, the behavior is identical to that of a long option with an argument. val The value returned by the popt parsing function when the option is encountered. If val is 0, the parsing function does not return a value. Instead, popt parses the next command-line argument. descrip Text description of the argument. Only required if automatic help messages are desired. Auto- matic usage messages can be generated without this argument. argDescrip Short summary of the type of arguments expected by the option, or NULL if the option does not require any arguments. Only required if auto- matic help messages are desired. Automatic usage messages can be generated without this argument. The final structure in the table should have all pointer values set to NULL and all arithmetic values set to 0, marking the end of the table. The macro POPT_TABLEEND performs these tasks. Help and Usage Output If popt should automatically provide --usage and --help options, one line in the option table should contain the macro POPT_AUTOHELP. This macro includes another option table, via POPT_ARG_INCLUDE_TABLE, which provides the table entries for these arguments. When the --usage or --help option is passed to applications that use popt automatic help, popt displays the appropriate message on stderr, and exits the applica- tion with a return code of 0. To use popt automatic help generation in a different way, you must explicitly add the option entries to the application's option table, instead of using POPT_AUTOHELP. If the argInfo value is bitwise or'd with POPT_ARGFLAG_DOC_HIDDEN, the argument is not shown in help output. If the argInfo value is bitwise or'd with POPT_ARGFLAG_SHOW_DEFAULT, the inital value of the arg is shown in help output. Special Option Table Entries Two types of option table entries do not specify command-line options. When either of these types of entries is 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 option table. Such nesting may extend quite deeply, the actual depth is limited by the application stack. Including other option tables allows a library to provide a standard set of command-line options to every application that uses the library. This is often done in graphical programming toolkits, for example. To nest another option table, set the argInfo field to POPT_ARG_INCLUDE_TABLE and the arg field to point to the table that is being included. If automatic help generation is 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 when any option in that table is found. This callback functionality is especially useful when included option tables are used, because the application that provides the top-level option table does not need to be aware of the other options that 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, option 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 callback uses the following parameters: con The context that is being parsed. See the next section for information on contexts. opt The option that triggered this callback. arg The argument for the opt option. If the option does not take an argument, arg is NULL. data Taken from the descrip field of the option table entry that defined the callback. As descrip is a pointer, this allows you to pass an arbitrary set of data to callback functions, though a typecast must be used. The option table entry that defines a callback has an argInfo of POPT_ARG_CALLBACK, an arg that points to the callback function, and a descrip field that specifies an arbitrary pointer to be passed to the callback. Creating a Context popt can interleave the parsing of multiple command-line sets. popt allows this by keeping all of 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 poptGetContext() function takes the following parameters: name Used only for alias handling. name should be the name of the application whose options are being parsed, or should be NULL if no option aliasing is desired. argc, argv Specifies the command-line arguments to parse. These arguments are generally passed to popt- GetContext() exactly as they were passed to the application's main() function. options Points to the table of command-line options. See the Option Tables section above. flags Can take one of the following values: POPT_CONTEXT_NO_EXEC Ignore exec expansions POPT_CONTEXT_KEEP_FIRST Do not ignore argv[0] POPT_CONTEXT_POSIXMEHARDOptions cannot follow arguments A poptContext keeps track of which options have already been parsed and which remain to be parsed. If an application wishes to restart process- ing the options of a set of arguments, the application can reset the poptContext by passing the context as the sole argument to poptReset- Context(). When argument processing is complete, the process should free the popt- Context, as it contains dynamically allocated components. The popt- FreeContext() function takes a poptContext as its sole argument and frees the resources that the context is using. Here are the prototypes of both poptResetContext() and poptFreeCon- text(): #include <popt.h> void poptFreeContext(poptContext con); void poptResetContext(poptContext con); Parsing the Command Line After an application has created a poptContext, the poptContext may begin parsing arguments. poptGetNextOpt() performs the actual argument parsing: #include <popt.h> int poptGetNextOpt(poptContext con); Taking the context as its sole argument, the poptGetNextOpt() function parses the next command-line argument found. When poptGetNextOpt() finds the next argument in the option table, the function populates the object pointed to by the option table entry's arg pointer, if the pointer is not NULL. If the val entry for the option is not zero, the function returns that value. Otherwise, poptGetNextOpt() continues to the next argument. poptGetNextOpt() returns -1 when the final argument has been parsed, and other negative values when errors occur. Therefore, you should ensure that the val elements in the option table are 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 these values: o Ask popt to populate a variable with the value of the option from the option table's arg elements. o Use poptGetOptArg(): #include <popt.h> const char * poptGetOptArg(poptContext con); The poptGetOptArg() function returns the argument given for the final option returned by poptGetNextOpt(), or returns NULL if no argument was specified. 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 hyphen, popt assumes that this is such an argu- ment, and adds the argument to a list of leftover arguments. Three functions allow applications to access such arguments: const char * poptGetArg(poptContext con); Returns the next leftover argument and marks the argument as pro- cessed. const char * poptPeekArg(poptContext con); Returns the next leftover argument but does not mark the argument as processed. This allows an application to look ahead into the argument list, without modifying the list. const char ** poptGetArgs(poptContext con); Returns all of the leftover arguments in a manner identical to argv. The final element in the returned array points to NULL, indi- cating the end of the arguments. Automatic Help Messages The popt library can automatically generate help messages that describe the options that an application accepts. Two types of help messages can be generated: o Usage messages are short messages that list valid options, but do not describe the options. o Help messages describe each option in one or more lines, resulting in a longer but more useful message. Whenever automatic help messages are used, the descrip and argDescrip members of the struct poptOption structure should be populated for each option. The POPT_AUTOHELP macro makes it easy to add usage and help messages to your application, as described earlier in this man page. If you need more control over your help messages, use the following functions: #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 mes- sage. Both functions currently ignore the flags argument, which is pro- vided for future functionality. Option Aliasing One of the primary benefits of popt is the ability to use option alias- ing. Option aliasing allows the user to specify options that popt expands into other options. For example. if the standard grep command made use of popt, users could add a --text option that expanded to -i -n -E -2, to allow users to more easily find information in text files. Specifying Aliases Aliases are normally specified in two places: o /etc/popt o $HOME/.popt Both files have the same format, that is, an arbitrary number of lines formatted as follows: appname alias newoption expansion An alias specification is composed of the following elements: appname Specifies 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. alias Specifies that an alias is being defined. Cur- rently, popt configuration files support only aliases, but other abilities may be added in the future. newoption Specifies the option that should be aliased, either a short option or a long option. expansion Specifies the expansion for the alias. The expansion is parsed in a similar way to a shell command: backslashes are allowed, and single quotation marks can 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 logi- cal continuation of the line containing the backslash, just as in a shell command. For example, the following entry would add to the grep command the --text option described earlier: grep alias --text -i -n -E -2 Enabling Aliases An application must enable alias expansion for a poptContext, before calling poptGetNextArg() for the first time. Three functions define aliases for a context: int poptReadDefaultConfig(poptContext con, int flags); Reads aliases from /etc/popt and $HOME/.popt. The flags argument should be NULL, it is provided only for future expansion. int poptReadConfigFile(poptContext con, char * fn); Opens the file specified by fn and parses the file as a popt con- figuration file. This allows applications to use application-spe- cific configuration files. int poptAddAlias(poptContext con, struct poptAlias alias, int flags); Adds a new alias to a context. This function is useful when pro- cesses want to specify aliases without having to read them from a configuration file. The flags argument should be 0, it is provided only for future expansion. The new alias is specified as a struct poptAlias, which is defined as follows: struct poptAlias { const char * longName; /* may be NULL */ char shortName; /* may be ' ' */ int argc; const char ** argv; /* must be free()able */ }; longName and shortName specify the option that is aliased. argc and argv define the expansion to use when the aliases option is encoun- tered. Parsing Argument Strings popt usually parses arguments that are already divided into an argv- style array. However, some applications need to parse strings that are formatted identically to command lines. To facilitate this, popt pro- vides a function that parses a string into an array of strings, using rules similar to those of 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() can be passed directly to poptGetContext(). Both routines return a single dynamically allocated contiguous block of storage and should be freed using free() when the application is finished with the storage. Handling Extra Arguments Some applications implement the equivalent of option aliasing but do so using 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 when all of the stuffed arguments have been exhausted. All of the popt functions that can return errors return integers. When an error occurs, a negative error code is returned. The following error codes can occur: POPT_ERROR_BADNUMBER A string-to-number conversion failed because the string contains nonnumeric characters. This occurs when poptGetNextOpt() is processing an argument of type POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOUBLE. 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_BADQUOTE A parsed string has a quotation mismatch, for example, a single quotation mark. popt- ParseArgvString(), 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 poptReadDefault- Config() can return this error. POPT_ERROR_NOARG An option that requires an argument was speci- fied on the command line, but no argument was given. This error can be returned only by popt- GetNextOpt(). POPT_ERROR_OPTSTOODEEP A set of option aliases is nested too deeply. Currently, popt follows options to only 10 lev- els, to prevent infinite recursion. Only popt- GetNextOpt() can return this error. POPT_ERROR_OVERFLOW A string-to-number conversion failed because the number is too large or too small. This error can occur only when poptGetNextOpt() is processing an argument of type POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOU- BLE. Two functions allow applications to provide good error messages: const char *const poptStrerror(const int error); 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); Returns the option that caused the error, if an error occurred dur- ing poptGetNextOpt(). 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 speci- fied through an alias. These two functions ensure that popt error handling is 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 poptStr- error(). When an error occurs during argument parsing, code similar to the following displays a useful error message: fprintf(stderr, "%s: %s0, poptBadOption(optCon, POPT_BADOPTION_NOALIAS), poptStrerror(rc)); Example 1: Parse Program Created From robin Program The following example is a simplified version of the robin program that appears in Chapter 15 of "Linux Application Development" by Michael K. Johnson and Erik W. Troan (copyright 1998 by Addison Wesley Longman, Inc.). The robin program has been stripped of everything but its argu- ment-parsing logic, slightly reworked, and renamed parse. This program illustrates 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); exit(exitcode); } 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" } , 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: %s0, 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("0ortname chosen: %s0, portname); poptFreeContext(optCon); exit(0); } RPM, a popular Linux package management application, uses several popt features. Many RPM command-line arguments are implemented using popt aliases, which makes RPM an excellent example of how to take advantage of the popt library. For more information about RPM, see http://www.rpm.org. The popt source code distribution includes test programs that use all of the features of the popt libraries in various ways. If a popt feature does not work for you, check the popt test code. The following files are used by this library: /usr/lib/libpopt.so Command Line Parser API shared library getopt(3), attributes(7) Updated by Erwann Chenede, Sun Microsystems Inc., 2003. Written by Erik W. Troan (ewt@redhat.com), Michael K. Johnson, and Robert Lynch.

Synopsis

Please see following description for synopsis

Description

libpopt(3)                                                          libpopt(3)



NAME
       libpopt - parse command-line options


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



       The popt library parses command-line options. The popt library provides
       an alternative to  parsing  the  argv  array  by  hand,  or  using  the
       getopt(3) functions getopt() and getopt_long().

       The popt library has the following advantages:

         o  popt  does not use global variables, thus enabling multiple passes
            in parsing argv.

         o  popt can parse an arbitrary array of argv-style elements, allowing
            parsing of command-line strings from any source.

         o  popt  provides  a standard method of option aliasing. This feature
            is discussed in detail below.

         o
            popt can exec external option filters.

         o  popt can automatically generate help and usage  messages  for  the
            application.


       The  popt library supports short and long options.  A short option con-
       sists of a hyphen followed by a single alphanumeric character.  A  long
       option,  common in GNU utilities, consists of two hyphens followed by a
       string composed of letters, numbers,  and  hyphens.  Long  options  can
       optionally  begin with a single hyphen, primarily to allow command-line
       compatibility between popt applications  and  X  toolkit  applications.
       Either type of option can be followed by an argument. A space separates
       a short option from its argument. Either a space or an equals sign sep-
       arates a long option from an argument.

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

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


   Option Tables
       Each application provides popt with information about the  command-line
       options for the application, by means of an option table. An option ta-
       ble is an array of struct poptOption  structures,  with  the  following
       format:

       #include <popt.h>

       struct poptOption {
           const char * longName; /* may be NULL */
           char shortName;        /* may be ' ' */
           int argInfo;
           void * arg;            /* depends on argInfo */
           int val;               /* 0 means do not return, just update flag */
           char * descrip;        /* description for autohelp -- may be NULL */
           char * argDescrip;     /* argument description for autohelp */
       };


   Option Table Members
       Each  member of the table defines a single option that may be passed to
       the program. Long and short options  are  considered  to  be  a  single
       option  that can occur in two different forms. The option table members
       are as follows:

       longName                Defines the name of the option in a long name.



       shortName               Defines the name of  the  option  in  a  single
                               character.



       argInfo                 Tells  popt  what  type of argument is expected
                               after the option. Valid values are as follows:


                               POPT_ARG_DOUBLE Double argument  expected,  arg
                                               type: double



                               POPT_ARG_FLOAT  Float  argument  expected,  arg
                                               type: float



                               POPT_ARG_INT    Integer argument expected,  arg
                                               type: int



                               POPT_ARG_LONG   Long   integer   expected,  arg
                                               type: long



                               POPT_ARG_NONE   No argument expected, arg type:
                                               int



                               POPT_ARG_STRING No  type  checking  to  be per-
                                               formed, arg type: char *



                               POPT_ARG_VAL    Integer value taken  from  val,
                                               arg type: int


                               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 is  negated  before
                               saving. For the common operations of setting or
                               clearing bits,  POPT_BIT_SET  and  POPT_BIT_CLR
                               have  the  appropriate flags set to perform bit
                               operations.

                               If  the  argInfovalue  is  bitwise  or'd   with
                               POPT_ARGFLAG_ONEDASH,  the long argument may be
                               given with a single hyphen instead of two.  For
                               example,   if   --longopt  is  an  option  with
                               POPT_ARGFLAG_ONEDASH,    -longopt    is    also
                               accepted.


       arg                     Allows  popt  to  automatically  update program
                               variables. If arg is NULL, popt ignores arg and
                               takes  no special action. Otherwise, arg points
                               to a variable of the appropriate type, as  fol-
                               lows:

                                 o  If  argInfo is POPT_ARG_NONE, the variable
                                    pointed to by arg is set  to  1  when  the
                                    option is used.

                                 o  If the option takes an argument, the vari-
                                    able pointed  to  by  arg  is  updated  to
                                    reflect  the  value  of  the argument. Any
                                    string is acceptable  for  POPT_ARG_STRING
                                    arguments.   POPT_ARG_INT,  POPT_ARG_LONG,
                                    POPT_ARG_FLOAT, and POPT_ARG_DOUBLE  argu-
                                    ments  are  converted  to  the appropriate
                                    type, and an error returned if the conver-
                                    sion fails.


                               POPT_ARG_VAL  causes arg to be set to the inte-
                               ger value of val when the  argument  is  found.
                               This is 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  take  precedence,  for
                               example,  rm  -i  -f.   POPT_ARG_VAL causes the
                               parsing function not to return a value, because
                               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  is  saved if the arg pointer is
                               present. Otherwise, the behavior  is  identical
                               to that of a long option with an argument.



       val                     The value returned by the popt parsing function
                               when the option is encountered. If  val  is  0,
                               the  parsing  function does not return a value.
                               Instead,  popt  parses  the  next  command-line
                               argument.



       descrip                 Text description of the argument. Only required
                               if automatic help messages are  desired.  Auto-
                               matic  usage  messages can be generated without
                               this argument.



       argDescrip              Short summary of the type of arguments expected
                               by  the  option, or NULL if the option does not
                               require any arguments. Only required  if  auto-
                               matic  help  messages  are  desired.  Automatic
                               usage messages can be  generated  without  this
                               argument.



       The  final structure in the table should have all pointer values set to
       NULL and all arithmetic values set to 0, marking the end of the  table.
       The macro POPT_TABLEEND performs these tasks.

   Help and Usage Output
       If  popt  should  automatically provide --usage and --help options, one
       line in the option table should contain the macro  POPT_AUTOHELP.  This
       macro  includes another option table, via POPT_ARG_INCLUDE_TABLE, which
       provides the table entries for these arguments.  When  the  --usage  or
       --help  option  is passed to applications that use popt automatic help,
       popt displays the appropriate message on stderr, and exits the applica-
       tion with a return code of 0.  To use popt automatic help generation in
       a different way, you must explicitly add  the  option  entries  to  the
       application's option table, instead of using POPT_AUTOHELP.

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

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

   Special Option Table Entries
       Two  types of option table entries do not specify command-line options.
       When either of these types of entries is  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  option  table.  Such  nesting  may
       extend  quite  deeply,  the  actual depth is limited by the application
       stack. Including other option tables allows  a  library  to  provide  a
       standard set of command-line options to every application that uses the
       library. This is often done  in  graphical  programming  toolkits,  for
       example.  To  nest  another  option  table,  set  the  argInfo field to
       POPT_ARG_INCLUDE_TABLE and the arg field to point to the table that  is
       being included. If automatic help generation is 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
       when any option in that table is found. This callback functionality  is
       especially  useful  when  included  option tables are used, because the
       application that provides the top-level option table does not  need  to
       be  aware of the other options that 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, option 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 callback uses the following parameters:

       con             The context that is being parsed. See the next  section
                       for information on contexts.



       opt             The option that triggered this callback.



       arg             The argument for the opt option. If the option does not
                       take an argument, arg is NULL.



       data            Taken from the descrip field of the option table  entry
                       that  defined  the  callback.  As descrip is a pointer,
                       this allows you to pass an arbitrary  set  of  data  to
                       callback functions, though a typecast must be used.



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

   Creating a Context
       popt can interleave the parsing of  multiple  command-line  sets.  popt
       allows  this  by  keeping all of 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 poptGetContext() function takes the following parameters:

       name                    Used  only  for  alias handling. name should be
                               the name of the application whose  options  are
                               being  parsed,  or  should be NULL if no option
                               aliasing is desired.



       argc, argv              Specifies the command-line arguments to  parse.
                               These  arguments  are generally passed to popt-
                               GetContext() exactly as they were passed to the
                               application's main() function.



       options                 Points  to  the  table of command-line options.
                               See the Option Tables section above.



       flags                   Can take one of the following values:


                               POPT_CONTEXT_NO_EXEC    Ignore exec expansions




                               POPT_CONTEXT_KEEP_FIRST Do not ignore argv[0]



                               POPT_CONTEXT_POSIXMEHARDOptions  cannot  follow
                                                       arguments



       A poptContext keeps track of which options have already been parsed and
       which remain to be parsed. If an application wishes to restart process-
       ing  the  options  of a set of arguments, the application can reset the
       poptContext by passing the context as the sole argument  to  poptReset-
       Context().

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

       Here are the prototypes of  both  poptResetContext()  and  poptFreeCon-
       text():

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


   Parsing the Command Line
       After  an  application  has  created a poptContext, the poptContext may
       begin parsing arguments. poptGetNextOpt() performs the actual  argument
       parsing:

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


       Taking  the context as its sole argument, the poptGetNextOpt() function
       parses the next  command-line  argument  found.  When  poptGetNextOpt()
       finds the next argument in the option table, the function populates the
       object pointed to by the option  table  entry's  arg  pointer,  if  the
       pointer  is  not NULL. If the val entry for the option is not zero, the
       function returns that value. Otherwise, poptGetNextOpt()  continues  to
       the next argument.

       poptGetNextOpt()  returns  -1  when the final argument has been parsed,
       and other negative values when  errors  occur.  Therefore,  you  should
       ensure that the val elements in the option table are 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 these values:

         o  Ask  popt to populate a variable with the value of the option from
            the option table's arg elements.

         o  Use poptGetOptArg():

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



       The poptGetOptArg() function returns the argument given for  the  final
       option returned by poptGetNextOpt(), or returns NULL if no argument was
       specified.

   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 hyphen, popt assumes that this is such  an  argu-
       ment,  and  adds  the  argument  to a list of leftover arguments. Three
       functions allow applications to access such arguments:

       const char * poptGetArg(poptContext con);

           Returns the next leftover argument and marks the argument  as  pro-
           cessed.



       const char * poptPeekArg(poptContext con);

           Returns  the  next leftover argument but does not mark the argument
           as processed. This allows an application to  look  ahead  into  the
           argument list, without modifying the list.



       const char ** poptGetArgs(poptContext con);

           Returns  all  of  the  leftover  arguments in a manner identical to
           argv. The final element in the returned array points to NULL, indi-
           cating the end of the arguments.



   Automatic Help Messages
       The popt library can automatically generate help messages that describe
       the options that an application accepts. Two types of help messages can
       be generated:

         o  Usage  messages are short messages that list valid options, but do
            not describe the options.

         o  Help messages describe each option in one or more lines, resulting
            in a longer but more useful message.


       Whenever  automatic  help messages are used, the descrip and argDescrip
       members of the struct poptOption structure should be populated for each
       option.

       The POPT_AUTOHELP macro makes it easy to add usage and help messages to
       your application, as described earlier in this man page.  If  you  need
       more control over your help messages, use the following functions:

       #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  mes-
       sage. Both functions currently ignore the flags argument, which is pro-
       vided for future functionality.

   Option Aliasing
       One of the primary benefits of popt is the ability to use option alias-
       ing.  Option  aliasing  allows  the  user  to specify options that popt
       expands into other options. For example. if the standard  grep  command
       made  use  of popt, users could add a --text option that expanded to -i
       -n -E -2, to allow users to more easily find information in text files.

   Specifying Aliases
       Aliases are normally specified in two places:

         o  /etc/popt

         o  $HOME/.popt


       Both files have the same format, that is, an arbitrary number of  lines
       formatted as follows:

       appname alias newoption expansion

       An alias specification is composed of the following elements:

       appname                 Specifies  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.



       alias                   Specifies that an alias is being defined.  Cur-
                               rently,  popt  configuration files support only
                               aliases, but other abilities may  be  added  in
                               the future.



       newoption               Specifies  the  option  that should be aliased,
                               either a short option or a long option.



       expansion               Specifies the  expansion  for  the  alias.  The
                               expansion is parsed in a similar way to a shell
                               command: backslashes are  allowed,  and  single
                               quotation  marks  can 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 logi-
                               cal continuation of  the  line  containing  the
                               backslash, just as in a shell command.




       For  example,  the  following  entry  would add to the grep command the
       --text option described earlier:

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

   Enabling Aliases
       An application must enable alias expansion for  a  poptContext,  before
       calling  poptGetNextArg()  for  the  first time. Three functions define
       aliases for a context:

       int poptReadDefaultConfig(poptContext con, int flags);

           Reads aliases from /etc/popt and $HOME/.popt.  The  flags  argument
           should be NULL, it is provided only for future expansion.



       int poptReadConfigFile(poptContext con, char * fn);

           Opens  the  file specified by fn and parses the file as a popt con-
           figuration file. This allows applications to  use  application-spe-
           cific configuration files.



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

           Adds  a  new  alias to a context. This function is useful when pro-
           cesses want to specify aliases without having to read them  from  a
           configuration  file. The flags argument should be 0, it is provided
           only for future expansion. The new alias is specified as  a  struct
           poptAlias, which is defined as follows:


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

           longName and shortName specify the option that is aliased. argc and
           argv define the expansion to use when the aliases option is encoun-
           tered.



   Parsing Argument Strings
       popt  usually  parses  arguments that are already divided into an argv-
       style array. However, some applications need to parse strings that  are
       formatted  identically  to command lines. To facilitate this, popt pro-
       vides a function that parses a string into an array of  strings,  using
       rules similar to those of 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() can be
       passed directly to poptGetContext().  Both  routines  return  a  single
       dynamically  allocated  contiguous block of storage and should be freed
       using free() when the application is finished with the storage.

   Handling Extra Arguments
       Some applications implement the equivalent of option aliasing but do so
       using 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  when  all  of  the
       stuffed arguments have been exhausted.


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

       POPT_ERROR_BADNUMBER    A  string-to-number  conversion  failed because
                               the string contains nonnumeric characters. This
                               occurs  when  poptGetNextOpt() is processing an
                               argument of type  POPT_ARG_INT,  POPT_ARG_LONG,
                               POPT_ARG_FLOAT, or POPT_ARG_DOUBLE.



       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_BADQUOTE     A  parsed  string has a quotation mismatch, for
                               example,  a  single   quotation   mark.   popt-
                               ParseArgvString(),   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  poptReadDefault-
                               Config() can return this error.



       POPT_ERROR_NOARG        An  option that requires an argument was speci-
                               fied on the command line, but no  argument  was
                               given. This error can be returned only by popt-
                               GetNextOpt().



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



       POPT_ERROR_OVERFLOW     A  string-to-number  conversion  failed because
                               the number is too  large  or  too  small.  This
                               error  can occur only when  poptGetNextOpt() is
                               processing an argument  of  type  POPT_ARG_INT,
                               POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOU-
                               BLE.



       Two functions allow applications to provide good error messages:

       const char *const poptStrerror(const int error);

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

           Returns the option that caused the error, if an error occurred dur-
           ing poptGetNextOpt(). 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  speci-
           fied through an alias.



       These two functions ensure that popt error handling is 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 poptStr-
       error(). When an error occurs during argument parsing, code similar  to
       the following displays a useful error message:

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



       Example 1: Parse Program Created From robin Program

       The following example is a simplified version of the robin program that
       appears in Chapter 15 of "Linux Application Development" by Michael  K.
       Johnson  and  Erik  W. Troan (copyright 1998 by Addison Wesley Longman,
       Inc.). The robin program has been stripped of everything but its  argu-
       ment-parsing  logic, slightly reworked, and renamed parse. This program
       illustrates 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);
           exit(exitcode);
       }

       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" } ,
                                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: %s0,
                    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("0ortname chosen: %s0, portname);

         poptFreeContext(optCon);
         exit(0);
       }


       RPM, a popular Linux package management application, uses several  popt
       features.  Many  RPM  command-line arguments are implemented using popt
       aliases, which makes RPM an excellent example of how to take  advantage
       of   the   popt   library.   For   more   information  about  RPM,  see
       http://www.rpm.org. The popt source  code  distribution  includes  test
       programs  that use all of the features of the popt libraries in various
       ways.  If a popt feature does not work for you,  check  the  popt  test
       code.


       The following files are used by this library:

       /usr/lib/libpopt.so     Command Line Parser API shared library




       getopt(3), attributes(7)


       Updated by Erwann Chenede, Sun Microsystems Inc., 2003. Written by Erik
       W. Troan (ewt@redhat.com), Michael K. Johnson, and Robert Lynch.



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | library/popt     |
       +---------------+------------------+
       |Stability      | Volatile         |
       +---------------+------------------+
NOTES
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  https://launchpad.net/popt/head/1.16/+down-
       load/popt-1.16.tar.gz

       Further information about this software can be found on the open source
       community website at http://freecode.com/projects/popt/.



                                  31 May 2004                       libpopt(3)