Linux man page for popt.3

popt(3) -- Linux man page

NAME

popt - Parse command line options

SYNOPSIS

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

DESCRIPTION

The popt library exists essentially for parsing command-line options. It is found superior in many ways when compared to parsing the argv array by hand or using the getopt functions getopt() and getopt_long() [see getopt(3)]. Some specific advantages of popt are: it does not utilize global variables, thus enabling multiple passes in parsing argv ; it can parse an arbitrary array of argv-style elements, allowing parsing of command-line-strings from any source; it provides a standard method of option aliasing (to be discussed at length below.); it can exec external option filters; and, finally, it can automatically generate help and usage messages for the application.

Like getopt_long(), the popt library supports short and long style options. Recall that a short option consists of a - character followed by a single alphanumeric character. A long option, common in GNU utilities, consists of two - characters followed by a string made up of letters, numbers and hyphens. Long options are optionally allowed to begin with a single -, primarily to allow command-line compatibility between popt applications and X toolkit applications. Either type of option may be followed by an argument. A space separates a short option from its arguments; either a space or an = separates a long option from an argument.

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

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

BASIC POPT USAGE

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,