1. THE OPTION TABLE¶

Applications provide popt with information on their command-line options by means of an "option table," i.e., an array of struct poptOption structures:

#include <popt.h>

struct poptOption {


    const char * longName; /* may be NULL */


    char shortName;        /* may be '\0' */


    int argInfo;


    void * arg;            /* depends on argInfo */


    int val;               /* 0 means don't return, just update flag */


    char * descrip;        /* description for autohelp -- may be NULL */


    char * argDescrip;     /* argument description for autohelp */
};

Each member of the table defines a single option that may be passed to the program. Long and short options are considered a single option that may occur in two different forms. The first two members, longName and shortName, define the names of the option; the first is a long name, while the latter is a single character.

The argInfo member tells popt what type of argument is expected after the argument. If no option is expected, POPT_ARG_NONE should be used. The rest of the valid values are shown in the following table:

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.

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 arguments, but POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, and POPT_ARG_DOUBLE are converted to the appropriate type, and an error returned if the conversion fails.

POPT_ARG_VAL causes arg to be set to the (integer) value of val when the argument is found. This is most often useful for mutually-exclusive arguments in cases where it is not an error for multiple arguments to occur and where you want the last argument specified to win; for example, "rm -i -f". POPT_ARG_VAL causes the parsing function not to return a value, since the value of val has already been used.

If the argInfo value is bitwise or'd with POPT_ARGFLAG_OPTIONAL, the argument to the long option may be omitted. If the long option is used without an argument, a default value of zero or NULL will be saved (if the arg pointer is present), otherwise behavior will be identical to a long option with argument.

The next option, val, is the value popt's parsing function should return when the option is encountered. If it is 0, the parsing function does not return a value, instead parsing the next command-line argument.

The last two options, descrip and argDescrip are only required if automatic help messages are desired (automatic usage messages can be generated without them). descrip is a text description of the argument and argdescrip is a short summary of the type of arguments the option expects, or NULL if the option doesn't require any arguments.

If popt should automatically provide --usage and --help (-?) options, one line in the table should be the macro POPT_AUTOHELP. This macro includes another option table (via POPT_ARG_INCLUDE_TABLE; see below) in the main one which provides the table entries for these arguments. When --usage or --help are passed to programs which use popt's automatical 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 inital value of the arg will be shown in help output.

The final structure in the table should have all the pointer values set to NULL and all the arithmetic values set to 0, marking the end of the table. The macro POPT_TABLEEND is provided to do that.

There are two types of option table entries which do not specify command line options. When either of these types of entries are used, the longName element must be NULL and the shortName element must be '\0'.

The first of these special entry types allows the application to nest another option table in the current one; such nesting may extend quite deeply (the actual depth is limited by the program's stack). Including other option tables allows a library to provide a standard set of command-line options to every program which uses it (this is often done in graphical programming toolkits, for example). To do this, set the argInfo field to POPT_ARG_INCLUDE_TABLE and the arg field to point to the table which is being included. If automatic help generation is being used, the descrip field should contain a overall description of the option table being included.

The other special option table entry type tells popt to call a function (a callback) when any option in that table is found. This is especially usefull when included option tables are being used, as the program which provides the top-level option table doesn't need to be aware of the other options which are provided by the included table. When a callback is set for a table, the parsing function never returns information on an option in the table. Instead, options information must be retained via the callback or by having popt set a variable through the option's arg field. Option callbacks should match the following prototype:

void poptCallbackType(poptContext con, 
                      const struct poptOption * opt, 
                      const char * arg, void * data);

The first parameter is the context which is being parsed (see the next section for information on contexts), opt points to the option which triggered this callback, and arg is the option's argument. If the option does not take an argument, arg is NULL. The final parameter, data is taken from the descrip field of the option table entry which defined the callback. As descrip is a pointer, this allows callback functions to be passed an arbitrary set of data (though a typecast will have to be used).

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

2. CREATING A CONTEXT¶

popt can interleave the parsing of multiple command-line sets. It allows this by keeping all the state information for a particular set of command-line arguments in a poptContext data structure, an opaque type that should not be modified outside the popt library.

New popt contexts are created by poptGetContext():

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

The first parameter, name, is used only for alias handling (discussed later). It should be the name of the application whose options are being parsed, or should be NULL if no option aliasing is desired. The next two arguments specify the command-line arguments to parse. These are generally passed to poptGetContext() exactly as they were passed to the program's main() function. The options parameter points to the table of command-line options, which was described in the previous section. The final parameter, flags, can take one of three values:

A poptContext keeps track of which options have already been parsed and which remain, among other things. If a program wishes to restart option processing of a set of arguments, it can reset the poptContext by passing the context as the sole argument to poptResetContext().

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

Here are the prototypes of both poptResetContext() and poptFreeContext():

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

3. PARSING THE COMMAND LINE¶

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

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

Taking the context as its sole argument, this function parses the next command-line argument found. After finding the next argument in the option table, the function fills in the object pointed to by the option table entry's arg pointer if it is not NULL. If the val entry for the option is non-0, the function then returns that value. Otherwise, poptGetNextOpt() continues on to the next argument.

poptGetNextOpt() returns -1 when the final argument has been parsed, and other negative values when errors occur. This makes it a good idea to keep the val elements in the options table greater than 0.

If all of the command-line options are handled through arg pointers, command-line parsing is reduced to the following line of code:

rc = poptGetNextOpt(poptcon);

Many applications require more complex command-line parsing than this, however, and use the following structure:

while ((rc = poptGetNextOpt(poptcon)) > 0) {


     switch (rc) {


          /* specific arguments are handled here */


     }
}

When returned options are handled, the application needs to know the value of any arguments that were specified after the option. There are two ways to discover them. One is to ask popt to fill in a variable with the value of the option through the option table's arg elements. The other is to use poptGetOptArg():

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

This function returns the argument given for the final option returned by poptGetNextOpt(), or it returns NULL if no argument was specified. The calling function is responsible for deallocating this string.

4. LEFTOVER ARGUMENTS¶

Many applications take an arbitrary number of command-line arguments, such as a list of file names. When popt encounters an argument that does not begin with a -, it assumes it is such an argument and adds it to a list of leftover arguments. Three functions allow applications to access such arguments:

const char * poptGetArg(poptContext con);

const char * poptPeekArg(poptContext con);

const char ** poptGetArgs(poptContext con);

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.

1. SPECIFYING ALIASES¶

Aliases are normally specified in two places: /etc/popt and the .popt file in the user's home directory (found through the HOME environment variable). Both files have the same format, an arbitrary number of lines formatted like this:

appname alias newoption expansion

The appname is the name of the application, which must be the same as the name parameter passed to poptGetContext(). This allows each file to specify aliases for multiple programs. The alias keyword specifies that an alias is being defined; currently popt configuration files support only aliases, but other abilities may be added in the future. The next option is the option that should be aliased, and it may be either a short or a long option. The rest of the line specifies the expansion for the alias. It is parsed similarly to a shell command, which allows \, ", and ' to be used for quoting. If a backslash is the final character on a line, the next line in the file is assumed to be a logical continuation of the line containing the backslash, just as in shell.

The following entry would add a --text option to the grep command, as suggested at the beginning of this section.

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

2. ENABLING ALIASES¶

An application must enable alias expansion for a poptContext before calling poptGetNextArg() for the first time. There are three functions that define aliases for a context:

int poptReadDefaultConfig(poptContext con, int flags);

int poptReadConfigFile(poptContext con, char * fn);

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

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.