'\" te

.TH libpopt 3 "31 May 2004" "" ""

.SH "NAME"

libpopt \- parse

command-line options

.SH ""

.sp

.nf

\f(CW#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);\fR

.fi

.sp

.SH ""

.PP

The \fBpopt\fR library parses command-line options\&. The \fBpopt\fR library provides an alternative to parsing the \fBargv\fR array by hand, or using the \fBgetopt\fR(3) functions \fBgetopt()\fR and \fBgetopt_long()\fR\&. 

.PP

The \fBpopt\fR library has the following advantages:

.sp

.in +2

\(bu

.mk

.in +3

.rt

\fBpopt\fR does not use global variables, thus

enabling multiple passes in parsing \fBargv\fR\&.

.sp

.in -3

\(bu

.mk

.in +3

.rt

\fBpopt\fR can parse an arbitrary array of \fBargv\fR-style elements, allowing parsing of command-line strings from

any source\&.

.sp

.in -3

\(bu

.mk

.in +3

.rt

\fBpopt\fR provides a standard method of option

aliasing\&. This feature is discussed in detail below\&.

.sp

.in -3

\(bu

.mk

.in +3

.rt

\fBpopt\fR can exec external option filters\&.

.sp

.in -3

\(bu

.mk

.in +3

.rt

\fBpopt\fR can automatically generate help

and usage messages for the application\&.

.sp

.in -3

.in -2

.PP

The \fBpopt\fR library supports short and long options\&.

A short option consists of a hyphen followed by a single alphanumeric character\&.

A long option, common in GNU utilities, consists of two hyphens followed by

a string composed of letters, numbers, and hyphens\&. Long options can optionally

begin with a single hyphen, primarily to allow command-line compatibility

between \fBpopt\fR applications and X toolkit applications\&.

Either type of option can be followed by an argument\&. A space separates a

short option from its argument\&. Either a space or an equals sign separates

a long option from an argument\&.

.PP

The \fBpopt\fR library is highly portable and should

work on any POSIX platform\&. The latest version is distributed with \fBrpm\fR and is available from: \fBftp://ftp\&.rpm\&.org/pub/rpm/dist\fR\&.

.PP

The \fBpopt\fR library may be redistributed under the

X consortium license, see the file \fBCOPYING\fR in the \fBpopt\fR source distribution for details\&.

.SH ""

.SS "Option Tables"

.PP

Each application provides \fBpopt\fR with information

about the command-line options for the application, by means of an option

table\&. An option table is an array of \fBstruct poptOption\fR

structures, with the following format:

.sp

.nf

\f(CW#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 do not return, just update flag */

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

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

};\fR

.fi

.sp

.SS "Option Table Members"

.PP

Each member of the table defines a single option that may be passed

to the program\&. Long and short options are considered to be a single option

that can occur in two different forms\&. The option table members are as follows:

.sp

.ne 2

.mk

\fB\fBlongName\fR\fR

.in +24n

.rt

Defines

the name of the option in a long name\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fB\fBshortName\fR\fR

.in +24n

.rt

Defines

the name of the option in a single character\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fB\fBargInfo\fR\fR

.in +24n

.rt

Tells \fBpopt\fR what type of argument is expected after the option\&. Valid

values are as follows: 

.sp

.sp

.ne 2

.mk

\fBPOPT_ARG_DOUBLE\fR

.in +16n

.rt

Double argument

expected, \fBarg\fR type: \fBdouble\fR

.sp

.sp 2

.in -16n

.sp

.ne 2

.mk

\fBPOPT_ARG_FLOAT\fR

.in +16n

.rt

Float argument expected, \fBarg\fR type: \fBfloat\fR

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBPOPT_ARG_INT\fR

.in +16n

.rt

Integer argument expected, \fBarg\fR type: \fBint\fR

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBPOPT_ARG_LONG\fR

.in +16n

.rt

Long integer expected, \fBarg\fR type: \fBlong\fR

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBPOPT_ARG_NONE\fR

.in +16n

.rt

No argument expected, \fBarg\fR type: \fBint\fR

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBPOPT_ARG_STRING\fR

.in +16n

.rt

No type checking

to be performed, \fBarg\fR type: \fBchar *\fR

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBPOPT_ARG_VAL\fR

.in +16n

.rt

Integer value taken

from val, \fBarg\fR type: \fBint\fR

.sp

.sp 1

.in -16n

For numeric values, if the \fBargInfo\fR

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 \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_NOT, the value is negated

before saving\&. For the common operations of setting or clearing bits, POPT_BIT_SET

and POPT_BIT_CLR have the appropriate flags set to perform bit operations\&.

.sp

If the \fBargInfo\fRvalue is bitwise or\&'d with POPT_ARGFLAG_ONEDASH,

the long argument may be given with a single hyphen instead of two\&. For example,

if -\fB-longopt\fR is an option with POPT_ARGFLAG_ONEDASH, -\fBlongopt\fR is also accepted\&.

.sp

.sp 0

.in -24n

.sp

.ne 2

.mk

\fB\fBarg\fR\fR

.in +24n

.rt

Allows \fBpopt\fR to automatically update program variables\&. If \fBarg\fR is NULL, \fBpopt\fR ignores \fBarg\fR

and takes no special action\&. Otherwise, \fBarg\fR points to a

variable of the appropriate type, as follows: 

.sp

.in +2

\(bu

.mk

.in +3

.rt

If \fBargInfo\fR is POPT_ARG_NONE, the variable

pointed to by \fBarg\fR is set to 1 when the option is used\&. 

.sp

.in -3

\(bu

.mk

.in +3

.rt

If the option takes an argument, the variable pointed to by \fBarg\fR is updated to reflect the value of the argument\&. Any string

is acceptable for POPT_ARG_STRING arguments\&. POPT_ARG_INT, POPT_ARG_LONG,

POPT_ARG_FLOAT, and POPT_ARG_DOUBLE arguments are converted to the appropriate

type, and an error returned if the conversion fails\&.

.sp

.in -3

.in -2

.sp

POPT_ARG_VAL causes \fBarg\fR to be set to the integer

value of \fBval\fR when the argument is found\&. This is 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 take

precedence, for example, \fBrm -i -f\fR\&.  POPT_ARG_VAL causes

the parsing function not to return a value, because the value of \fBval\fR has already been used\&.

.sp

If the \fBargInfo\fR 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 is saved if the \fBarg\fR pointer is present\&. Otherwise, the behavior is identical to

that of a long option with an argument\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fB\fBval\fR\fR

.in +24n

.rt

The value

returned by the \fBpopt\fR parsing function when the option

is encountered\&. If \fBval\fR is 0, the parsing function does

not return a value\&. Instead, \fBpopt\fR parses the next command-line

argument\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fBdescrip\fR

.in +24n

.rt

Text description of the

argument\&. Only required if automatic help messages are desired\&. Automatic

usage messages can be generated without this argument\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fBargDescrip\fR

.in +24n

.rt

Short summary of the

type of arguments expected by the option, or NULL if the option does not require

any arguments\&. Only required if automatic help messages are desired\&. Automatic

usage messages can be generated without this argument\&.

.sp

.sp 1

.in -24n

.PP

The final structure in the table should have all pointer

values set to NULL and all arithmetic values set to 0, marking the end of

the table\&. The macro POPT_TABLEEND performs these tasks\&.

.SS "Help and Usage Output"

.PP

If \fBpopt\fR should automatically provide -\fB\(miusage\fR and -\fB\(mihelp\fR options, one  line in the option

table should contain the macro POPT_AUTOHELP\&. This macro includes another

option table, via POPT_ARG_INCLUDE_TABLE, which provides the table entries

for these arguments\&. When the -\fB\(miusage\fR or -\fB\(mihelp\fR option is passed to applications that use \fBpopt\fR

automatic help, \fBpopt\fR displays the appropriate message

on \fBstderr\fR, and exits the application with a return code

of 0\&.  To use \fBpopt\fR automatic help generation in a different

way, you must explicitly add the option entries to the application\&'s option

table, instead of using POPT_AUTOHELP\&.

.PP

If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_DOC_HIDDEN,

the argument is not shown in help output\&.

.PP

If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_SHOW_DEFAULT,

the inital value of the \fBarg\fR is shown in help output\&.

.SS "Special Option Table Entries"

.PP

Two types of option table entries do not specify command-line options\&.

When either of these types of entries is used, the \fBlongName\fR

element must be NULL and the \fBshortName\fR element must be \fB\\0\fR\&.

.PP

The first of these special entry types allows the application to nest

another option table in the current option table\&. Such nesting may extend

quite deeply, the actual depth is limited by the application stack\&. Including

other option tables allows a library to provide a standard set of command-line

options to every application that uses the library\&. This is often done in

graphical programming toolkits, for example\&. To nest another option table,

set the \fBargInfo\fR field to POPT_ARG_INCLUDE_TABLE and the \fBarg\fR field to point to the table that is being included\&. If automatic

help generation is used, the \fBdescrip\fR field should contain

an overall description of the option table being included\&.

.PP

The other special option table entry type tells \fBpopt\fR

to call a function when any option in that table is found\&. This callback functionality

is especially useful when included option tables are used, because the application

that provides the top-level option table does not need to be aware of the

other options that 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, option information must be retained via the callback

or by having \fBpopt\fR set a variable through the option\&'s \fBarg\fR field\&. Option callbacks should match the following prototype:

.sp

.nf

void poptCallbackType(poptContext con,

                      const struct poptOption * opt,

                      const char * arg, void * data);

.fi

.sp

.PP

The callback uses the following parameters:

.sp

.ne 2

.mk

\fB\fBcon\fR\fR

.in +16n

.rt

The context

that is being parsed\&. See the next section for information on contexts\&.

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fB\fBopt\fR\fR

.in +16n

.rt

The option

that triggered this callback\&.

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fB\fBarg\fR\fR

.in +16n

.rt

The argument

for the \fBopt\fR option\&. If the option does not take an argument, \fBarg\fR is NULL\&.

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fB\fBdata\fR\fR

.in +16n

.rt

Taken from

the \fBdescrip\fR field of the option table entry that defined

the callback\&. As \fBdescrip\fR is a pointer, this allows you

to pass an arbitrary set of data to callback functions, though a typecast

must be used\&.

.sp

.sp 1

.in -16n

.PP

The option table entry that defines a callback has an \fBargInfo\fR of POPT_ARG_CALLBACK, an \fBarg\fR that points

to the callback function, and a \fBdescrip\fR field that specifies

an arbitrary pointer to be passed to the callback\&.

.SS "Creating a Context"

.PP

\fBpopt\fR can interleave the parsing of multiple command-line

sets\&. \fBpopt\fR allows this by keeping all of the state information

for a particular set of command-line arguments in a \fBpoptContext\fR

data structure, an opaque type that should not be modified outside the \fBpopt\fR library\&.

.PP

New \fBpopt\fR contexts are created by \fBpoptGetContext()\fR:

.sp

.nf

\f(CWpoptContext poptGetContext(const char * name, int argc,

                           const char ** argv,

                           const struct poptOption * options,

                           int flags);\fR

.fi

.sp

.PP

The \fBpoptGetContext()\fR function takes the following

parameters:

.sp

.ne 2

.mk

\fB\fBname\fR\fR

.in +24n

.rt

Used only

for alias handling\&. \fBname\fR should be the name of the application

whose options are being parsed, or should be NULL if no option aliasing is

desired\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fB\fBargc\fR, \fBargv\fR\fR

.in +24n

.rt

Specifies the command-line arguments to parse\&. These arguments

are generally passed to \fBpoptGetContext()\fR exactly as they

were passed to the application\&'s \fBmain()\fR function\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fB\fBoptions\fR\fR

.in +24n

.rt

Points

to the table of command-line options\&. See the Option Tables section above\&.

.sp

.sp 1

.in -24n

.sp

.ne 2

.mk

\fB\fBflags\fR\fR

.in +24n

.rt

Can take

one of the following values:

.sp

.sp

.ne 2

.mk

\fBPOPT_CONTEXT_NO_EXEC\fR

.in +24n

.rt

Ignore \fBexec\fR expansions

.sp

.sp 2

.in -24n

.sp

.ne 2

.mk

\fBPOPT_CONTEXT_KEEP_FIRST\fR

.in +24n

.rt

Do not ignore \fBargv[0]\fR

.sp

.sp 1

.in -24n

.sp