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
Flag
Meaning
POPT_CONTEXT_NO_EXEC
Ignore executable expansions
POPT_CONTEXT_KEEP_FIRST
Treat argv[0], the command name, as an option
POPT_CONTEXT_POSIXMEHARDER
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.
Note
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.
Note
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
Type
Value
Meaning
POPT_ARG_NONE
0
No argument data, just the option such as -v
POPT_ARG_STRING
1
arg treated as string
POPT_ARG_INT
2
arg treated as int
POPT_ARG_LONG
3
arg treated as long
POPT_ARG_INCLUDE_TABLE
4
arg points to a table
POPT_ARG_CALLBACK
5
arg points to a callback function
POPT_ARG_INTL_DOMAIN
6
sets translation domain
POPT_ARG_VAL
7
use value of val field for arg
POPT_ARG_FLOAT
8
arg treated as float
POPT_ARG_DOUBLE
9
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.
Note
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.
Note
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.