Product SiteDocumentation Site

Programming with popt

To use popt in your programs, you need to fill in a table of options and then call poptGetContext. The poptGetContext function parses the command-line options and returns a poptContext, an opaque data type that you need to pass as a parameter to a number of popt functions. The poptContext holds the state of your command-line processing. This allows you to call the popt library with multiple sets of arguments. Each set will have an associate poptContext to keep all the data separate.
The basic poptGetContext function signature follows:
poptContext poptGetContext (const char * name,
int argc,
const char ** argv,
const struct poptOption * options,
int flags );
All the popt functions require the popt.h include file:
#include <popt.h>
The flags should be a bitmask of any options you require, including those listed in Table 16-5.
Table 16-5 Flags for poptGetContext
Ignore executable expansions
Treat argv[0], the command name, as an option
Do not allow options to follow arguments
When done with a poptContext, you should free it by calling poptFreeContext:
poptContext poptFreeContext(poptContext context);
The call to poptFreeContext frees up the memory allocated for the context.
You can also fill in a poptContext from settings in a file with poptReadConfigFile:
int poptReadConfigFile(poptContext context,
const char * file_name);

Filling in the Options Table

You need to pass in a table that defines all the possible options. This table is an array of structures, where each structure defines one option. The format for a single option follows:
struct poptOption {
const char * longName;
char shortName;
int argInfo;
void * arg;
int val;
const char * descrip;
const char * argDescrip;
Going through this structure, the longName defines the long version of the option, such as "upgrade" for --upgrade. The shortName defines the short, one-character option, such as 'U' for an option of -U. You can place a null character, '\0', to specify no short option. With the rpm command, the --rebuilddb option has only a long name and not a short name, for example.
The longName is not preceded by the double minus sign. Similarly, the shortName is not preceded by the single minus sign.
The descrip field holds a short description of the option and the argDescrip field holds a description of the types of values it expects, or NULL if this option expects no values.
The argInfo field holds a flag that tells the popt library how to treat the option. At the very least, you need to define the type of the option. You can also define special processing flags. Table 16-6 lists the argument types in the options table.
Table 16-6 Popt option table argInfo argument types
No argument data, just the option such as -v
arg treated as string
arg treated as int
arg treated as long
arg points to a table
arg points to a callback function
sets translation domain
use value of val field for arg
arg treated as float
arg treated as double
Use these constants, from the include file popt.h, in place of the actual numbers.
Depending on the type you define in the argInfo field, popt will interpret the generic pointer field, arg, in different ways. Using a pointer allows the popt library to automatically update your program variables based on the command-line option settings.
You can pass NULL for the arg field. In this case, the popt library will not set any values for you.
The POPT_ARG_NONE type indicates that this option has no argument. For example, the -v verbose option has no data. On the other hand, the POPT_ARG_STRING type indicates that the user should provide a string. For example, the -f option to the rpm command is expected to include a string argument, the name of the file to look up.
If the argInfo argument type is POPT_ARG_NONE, the popt library will set arg to 1 if the option is present on the command line. You should pass a pointer to an int if you want this set for you.