Applications provide popt with information on their command-line options through an array of struct poptOption structures.

#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;        /* optional description of the option */
    char * argDescrip;     /* optional argument description */
};

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, and 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 summarized in Table 26.1.^[2]

The next element, arg, allows popt to update program variables automatically 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 Table 26.1.

If the option takes no argument (argInfo is POPT_ARG_NONE), the variable pointed to by arg is set to one when the option is used. 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 arguments are converted to the appropriate type, and an error is returned if the conversion fails.

If POPT_ARG_VAL is used, then no argument is expected. Instead, popt copies the integer value stored in the val member into the address pointed to by arg. This is useful when a program has a set of mutually exclusive arguments, and the last one specified wins. By specifying different val values for each option, having each option’s arg member point to the same integer, and specifying POPT_ARG_VAL for each one, it is easy to know which of those options was the last one specified. If you need to give an error if more than one of the options was given, this does not work.

The val member specifies the value popt’s parsing function should return when the option is encountered, unless POPT_ARG_VAL is used. If it is zero, the parsing function continues parsing with the next command-line argument rather than return.

The last two members are optional, and should be set to NULL if they are not needed.^[3] The first of these, descrip, is a string describing the option. It is used by popt when it generates a help message describing all of the options available. The descrip member provides a sample argument for the option that is also used to display help. Help message generation is described on pages 606-608.

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.

Let’s look at how an option table would be defined for a common application. Here is the options table for a simple version of grep utility:^[4]

const char * pattern = NULL;
int mode = MODE_REGEXP;
int ignoreCase = 0;
int maxCount = -1;

struct poptOption optionsTable[] = {
    { "extended-regexp", 'E', POPT_ARG_VAL, &mode, MODE_EXTENDED,
        "pattern for match is an extended regular expression", NULL },
    { "fixed-strings", 'F', POPT_ARG_VAL, &mode, MODE_FIXED,
        "pattern for match is a basic string (not a "
        "regular expression)", NULL },
    { "basic-regexp", 'G', POPT_ARG_VAL, &mode, MODE_REGEXP,
        "pattern for match is a basic regular expression" },
    { "ignore-case", 'i', POPT_ARG_NONE, &ignoreCase, 0,
        "perform case insensitive search", NULL },
    { "max-count", 'm', POPT_ARG_INT, &maxCount, 0,
        "terminate after N matches", "N" },
    { "regexp", 'e', POPT_ARG_STRING, &pattern, 0,
        "regular expression to search for", "pattern" },
    { NULL, '', POPT_ARG_NONE, NULL, 0, NULL, NULL }
};

The retry argument does not take an argument, so popt sets the retry variable to one if --retry is specified. The bytes and lines options both take integer arguments, which are stored in the identically named variables. The final option, follow, may be either the literal name or descriptor. The followType variable is set to point to whatever value is given on the command line, and needs to be checked for correctness. By setting it to point to "descriptor" initially, a useful default value is provided.

Some libraries provide implementation of some common command-line options. For example, one of the original X Windows toolkits handled the -geometry and -display options for applications, giving most X Windows programs a standard set of command-line options for controlling basic behaviors. Unfortunately, there is not an easy way of doing this. Passing argc and argv to an initialization function in the library lets the library handle the appropriate options, but the application has to know to ignore those options when it parses argv. To prevent this problem, XtAppInitialize() took argc and argv as parameters and returned new values for each of them with the options handled by the library removed. This approach, while workable, becomes cumbersome as the number of libraries increases.

To address this, popt allows the nesting of option tables. This lets libraries define the options they want to handle (which could include further nesting), and the main program can provide those options by nesting the libraries option table within its own.

An option table that is going to be nested is defined just like any other one. To include it in another table, a new option is created with empty longName and shortName options. The argInfo field must be set to POPT_ARG_INCLUDE_TABLE and the arg member points to the table to be nested. Here is an example of an option table that includes another:

struct poptOption nestedArgs[] = {
     { "option1", 'a', POPT_ARG_NONE, NULL, 'a' },
     { "option2", 'b', POPT_ARG_NONE, NULL, 'b' },
     { NULL, '', POPT_ARG_NONE, NULL, 0 }
};

struct poptOption mainArgs[] = {
     { "anoption", 'o', POPT_ARG_NONE, NULL, 'o' },
     { NULL, '', POPT_ARG_INCLUDE_TABLE, nestedArgs, 0 },
     { NULL, '', POPT_ARG_NONE, NULL, 0 }
};

In this example, the application ends up providing three options, --option1, --option2, and --anoption. A more complete example of nested option tables appears on pages 610-612.

popt can interleave the parsing of multiple command-line sets. It does 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().

#include <popt.h>

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

The first parameter, name, is used for alias handling and in help messages, and should be the name of the application whose options are being parsed. 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.^[5] The options parameter points to the table of command-line options, which was described in the previous section. The final parameter, flags, modifies how options are parsed, and consists of the following flags (which may be logically OR’ed together):

POPT_CONTEXT_KEEP_FIRST

POPT_CONTEXT_POSIXMEHARDER

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

After an application has created a poptContext, it may begin parsing arguments. The 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 nonzero, 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 option table greater than zero.

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.

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:

char * poptGetArg(poptContext con);

char * poptPeekArg(poptContext con);

char ** poptGetArgs(poptContext con);

One of the benefits of using popt is its ability to generate help and usage messages automatically. Help messages list each command-line option along with a reasonably detailed description of that option, while usage messages provide a concise list of the available options without any descriptive text. popt provides a function to create each type of message.

#include <popt.h>

void poptPrintHelp(poptContext con, FILE * f, int flags);
void poptPrintUsage(poptContext con, FILE * f, int flags);

These two functions behave almost identically, writing the appropriate type of message to the file f. The flags argument is not currently used by either function, and should be set to zero for compatibility with future versions of popt.

Since the help message is normally provided by the --help option, and the usage message by the --usage option, popt provides an easy way of adding those two options to your program. The POPT_AUTOHELP macro can be used in the option table to add these options,^[7] which displays the appropriate messages on STDOUT and exit with a return code of 0.^[8] This example shows the option table in grep.c with the single line we need to add to the option table for grep to enable automatic help text:

 95:     struct poptOption optionsTable[] = {
 96:             { "extended-regexp", 'E', POPT_ARG_VAL,
 97:               &mode, MODE_EXTENDED,
 98:               "pattern for match is an extended regular "
 99:               "expression" },
100:             { "fixed-strings", 'F', POPT_ARG_VAL,
101:               &mode, MODE_FIXED,
102:               "pattern for match is a basic string (not a "
103:               "regular expression)", NULL },
104:             { "basic-regexp", 'G', POPT_ARG_VAL,
105:               &mode, MODE_REGEXP,
106:               "pattern for match is a basic regular expression" },
107:             { "ignore-case", 'i', POPT_ARG_NONE, &ignoreCase, 0,
108:               "perform case insensitive search", NULL },
109:             { "max-count", 'm', POPT_ARG_INT, &maxCount, 0,
110:               "terminate after N matches", "N" },
111:             { "regexp", 'e', POPT_ARG_STRING, &pattern, 0,
112:               "regular expression to search for", "pattern" },
113:             POPT_AUTOHELP
114:             { NULL, '', POPT_ARG_NONE, NULL, 0, NULL, NULL }
115:     };

Here is what the help message generated by this table looks like:

Usage: grep [OPTION...]
  -E,  --extended-regexp      pattern for match is an extended regular
expression
  -F, --fixed-strings        pattern for match is a basic string (not a
regular
                            expression)
  -G, --basic-regexp      pattern for match is a basic regular expression
   -i, --ignore-case        perform case insensitive search
   -m, --max-count=N        terminate after N matches
   -e, --regexp=pattern     regular expression to search for

Help options:
  -?, --help               Show this help message
  --usage                  Display brief usage message

While this looks quite good, it is not quite right. The first line does not mention that the command expects file names on the command line. The [OPTION...] text that does appear there is popt’s default, and this can be changed to be more descriptive through the poptSetOtherOptionHelp() function.

#include <popt.h>

poptSetOtherOptionHelp(poptContext con, const char * text);

The context is the first parameter and the second specifies the text that should appear after the program’s name. Adding this call

poptSetOtherOptionHelp(optCon, "<pattern> <file list>");

changes the first line of our help message to

Usage: grep <pattern> <file list>

which is much nicer.

The final nicety of help message generation is how nested tables are handled. Look again at the help message for our grep program; the help options are in their own section of the help message. When a POPT_ARG_INCLUDE_TABLE option table entry provides a descrip member, that string is used as a description for all of the options in the nested table, and those options are displayed in their own section of the help message (like the help options for tail). If the descrip is NULL, the options for the nested table are displayed with the options from the main table rather than in their own section.

Occasionally, programs provide options that probably should not be used; they may be there for support with legacy applications or designed for testing only. Automatic help message generation for that option can be suppressed by logically OR’ing POPT_ARGFLAG_DOC_HIDDEN with the arg member of the the struct poptOption that defines that option.

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

An application must enable alias expansion for a poptContext before calling poptGetNextOpt() 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);