popt.3

'\" t
.
.TH POPT 3  "June 30, 1998" "" "Linux Programmer's Manual"
.SH NAME
popt \- Parse command line options
.SH SYNOPSIS
.nf
.B #include <popt.h>
.sp
.BI "poptContext poptGetContext(const char * " name ", int " argc ,
.BI "                           const char ** "argv ,
.BI "                           const struct poptOption * " options ,
.BI "                           unsigned int " flags );
.sp
.BI "poptContext poptFreeContext(poptContext " con );
.sp
.BI "void poptResetContext(poptContext " con );
.sp
.BI "int poptGetNextOpt(poptContext " con );
.sp
.BI "const char * poptGetOptArg(poptContext " con );
.sp
.BI "const char * poptGetArg(poptContext " con );
.sp
.BI "const char * poptPeekArg(poptContext " con );
.sp
.BI "const char ** poptGetArgs(poptContext " con );
.sp
.BI "const char *const poptStrerror(const int " error );
.sp
.BI "const char * poptBadOption(poptContext " con ", int " flags );
.sp
.BI "int poptReadDefaultConfig(poptContext " con ", int " flags );
.sp
.BI "int poptReadConfigFile(poptContext " con ", char * " fn );
.sp
.BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias , 
.BI "                 int " flags );
.sp
.BI "int poptParseArgvString(char * " s ", int *  " argcPtr , 
.BI "                        const char *** " argvPtr );
.sp
.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ",
.BI "                        const char *** " argvPtr ");"
.sp
.BI "int poptStuffArgs(poptContext " con ", const char ** " argv );
.sp
.fi
.SH 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 
.B getopt()
and 
.B getopt_long()
[see 
.BR getopt "(3)]."  
Some specific advantages of popt are: it does not utilize global 
.RI "variables, thus enabling multiple passes in parsing " argv
.RI "; 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.
.sp
Like
.BR getopt_long() ,
the popt library supports short and long style options.  Recall 
that a 
.B short option
consists of a - character followed by a single alphanumeric character.
A 
.BR "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. 
.sp
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: http://ftp.rpm.org/popt/releases/.
.sp
It may be redistributed under the MIT license, see the file COPYING
in the popt source distribution for details.
.SH "BASIC POPT USAGE"
.SS "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 
.B struct poptOption 
structures:
.sp
#include <popt.h>
.sp
.nf
struct poptOption {
    const char * longName;   /* may be NULL */
    char shortName;          /* may be '\\0' */
    unsigned int argInfo;    /* type of argument expected after the option */
    void * arg;              /* depends on argInfo */
    int val;                 /* 0 means don't return, just update arg */
    const char * descrip;    /* description for autohelp -- may be NULL */
    const char * argDescrip; /* argument description for autohelp -- may be NULL*/
};
.fi
.sp
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, 
.IR longName " and " shortName ", define the names of the option;"
the first is a long name, while the latter is a single character.
.sp
The 
.IR argInfo " member tells popt what type of argument is expected" 
after the option.  If no argument is expected,
.B POPT_ARG_NONE
should be used.
The valid values of
.IR argInfo
are shown in the following table:
.sp
.TS
lfB lfB lfB
lfB lfR lfR.
Value	Description	arg Type
POPT_ARG_NONE	No argument expected	int
POPT_ARG_STRING	No type checking to be performed	char *
POPT_ARG_ARGV	No type checking to be performed	char **
POPT_ARG_SHORT	A short argument is expected	short
POPT_ARG_INT	An integer argument is expected	int
POPT_ARG_LONG	A long integer is expected	long
POPT_ARG_LONGLONG	A long long integer is expected	long long
POPT_ARG_VAL	Integer value taken from \f(CWval\fR	int
POPT_ARG_FLOAT	A float argument is expected	float
POPT_ARG_DOUBLE	A double argument is expected	double
.TE
.sp
For numeric values, if the \fIargInfo\fR value is bitwise or'd with one of
\fBPOPT_ARGFLAG_OR\fR, \fBPOPT_ARGFLAG_AND\fR, or \fBPOPT_ARGFLAG_XOR\fR,
the value is saved by performing an OR, AND, or XOR.
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_NOT\fR,
the value will be negated before saving. For the common operations of
setting and/or clearing bits, \fBPOPT_BIT_SET\fR and \fBPOPT_BIT_CLR\fR
have the appropriate flags set to perform bit operations.
.sp
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_ONEDASH\fR,
the long argument may be given with a single - instead of two. For example,
if \fB--longopt\fR is an option with \fBPOPT_ARGFLAG_ONEDASH\fR, is
specified, \fB-longopt\fR is accepted as well.
.sp
.RI "The next element, " arg ", allows popt to automatically update "
.RI "program variables when the option is used. If " arg " is " 
.BR NULL ", it is ignored and popt takes no special action. " 
Otherwise it should point to a variable of the type indicated in the 
.RB "right-most column of the table above. A " POPT_ARG_ARGV " arg will
(re-)allocate an array of char * string pointers, append the string argument, and add a
.BR NULL " sentinel at the end of the array as needed."
.RB "The target char ** address of a " POPT_ARG_ARGV " arg should be initialized to " NULL "."
.sp
.RI "If the option takes no argument (" argInfo " is " 
.BR POPT_ARG_NONE "), the variable pointed to by " 
.IR arg " is set to 1 when the option is used.  (Incidentally, it "
will perhaps not escape the attention of hunt-and-peck typists that 
.RB "the value of " POPT_ARG_NONE " is 0.)  If the option does take "
an argument, the variable that 
.IR arg " points to is updated to reflect the value of the argument." 
.RB "Any string is acceptable for " POPT_ARG_STRING " and " POPT_ARG_ARGV " arguments, but "
.BR POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", " POPT_ARG_FLOAT ", and "
.BR POPT_ARG_DOUBLE " are converted to the appropriate type, and an "
error returned if the conversion fails.
.sp
\fBPOPT_ARG_VAL\fR causes \fIarg\fP to be set to the (integer) value of
\fIval\fP when the argument is found.  This is most often 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 win; for example, "rm -i -f".  \fBPOPT_ARG_VAL\fP causes
the parsing function not to return a value, since the value of \fIval\fP
has already been used.
.sp
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_OPTIONAL\fR,
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 will be saved
(if the arg pointer is present), otherwise behavior will be identical to
a long option with argument.
.sp
.RI "The next option, " val ", is the value popt's parsing function 
should return when the option is encountered.  If it is 0, the parsing
function does not return a value, instead parsing the next 
command-line argument.
.sp
.RI "The last two options, " descrip " and " argDescrip " are only required
if automatic help messages are desired (automatic usage messages can
.RI "be generated without them). " descrip " is a text description of the
.RI "argument and " argDescrip " is a short summary of the type of arguments
.RI "the option expects, or NULL if the option doesn't require any 
arguments.
.sp
.RB "If popt should automatically provide " --usage " and " --help " (" -? ")
.RB "options, one line in the table should be the macro " POPT_AUTOHELP ".
.RB "This macro includes another option table (via " POPT_ARG_INCLUDE_TABLE
; see below) in the main one which provides the table entries for these
.RB "arguments. When " --usage " or " --help " are passed to programs which
use popt's automatic help, popt displays the appropriate message on
stderr as soon as it finds the option, and exits the program with a
return code of 0. If you want to use popt's automatic help generation in
a different way, you need to explicitly add the option entries to your programs 
.RB "option table instead of using " POPT_AUTOHELP ".
.sp
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_DOC_HIDDEN\fR,
the argument will not be shown in help output.
.sp
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_SHOW_DEFAULT\fR,
the initial value of the arg will be shown in help output.
.sp
The final structure in the table should have all the pointer values set
.RB "to " NULL " and all the arithmetic values set to 0, marking the "
.RB "end of the table. The macro " POPT_TABLEEND " is provided to do that.
.sp
There are two types of option table entries which do not specify command
line options. When either of these types of entries are used, the
\fIlongName\fR element must be \fBNULL\fR and the \fBshortName\fR element
must be \fB'\\0'\fR.
.sp
The first of these special entry types allows the application to nest
another option table in the current one; such nesting may extend quite
deeply (the actual depth is limited by the program's stack). Including
other option tables allows a library to provide a standard set of
command-line options to every program which uses it (this is often done
in graphical programming toolkits, for example). To do this, set
the \fIargInfo\fR field to \fBPOPT_ARG_INCLUDE_TABLE\fR and the
\fRarg\fR field to point to the table which is being included. If
automatic help generation is being used, the \fIdescrip\fR field should
contain an overall description of the option table being included.
.sp
The other special option table entry type tells popt to call a function (a
callback) when any option in that table is found. This is especially useful
when included option tables are being used, as the program which provides
the top-level option table doesn't need to be aware of the other options
which 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, options information must be retained via the callback
or by having popt set a variable through the option's \fIarg\fR field.
Option callbacks should match the following prototype:
.sp
.nf
.BI "void poptCallbackType(poptContext con, 
.BI "                      enum poptCallbackReason reason,
.BI "                      const struct poptOption * opt, 
.BI "                      const char * arg, const void * data);
.fi
.sp
The first parameter is the context which is being parsed (see the next
section for information on contexts). \fIreason\fR is
\fBPOPT_CALLBACK_REASON_PRE\fR, \fBPOPT_CALLBACK_REASON_POST\fR, or
\fBPOPT_CALLBACK_REASON_OPTION\fR. \fIopt\fR points to the option
which triggered this callback, and \fIarg\fR is the option's argument.
If the option does not take an argument, \fIarg\fR is \fBNULL\fR.  The
final parameter, \fIdata\fR is taken from the \fIdescrip\fR field
of the option table entry which defined the callback. As \fIdescrip\fR
is a pointer, this allows callback functions to be passed an arbitrary
set of data (though a typecast will have to be used).
.sp
The option table entry which defines a callback has an \fIargInfo\fR of
\fBPOPT_ARG_CALLBACK\fR, an \fIarg\fR which points to the callback
function, and a \fIdescrip\fR field which specifies an arbitrary pointer
to be passed to the callback.
.SS "2. CREATING A CONTEXT"
popt can interleave the parsing of multiple command-line sets. It allows
this by keeping all the state information for a particular set of
command-line arguments in a 
.BR poptContext " data structure, an opaque type that should not be "
modified outside the popt library.
.sp
.RB "New popt contexts are created by " poptGetContext() ":"
.sp
.nf
.BI "poptContext poptGetContext(const char * " name ", int "argc ",
.BI "                           const char ** "argv ",
.BI "                           const struct poptOption * "options ",
.BI "                           unsigned int "flags ");"
.fi
.sp
The first parameter, 
.IR name ", is used only for alias handling (discussed later). It "
should be the name of the application whose options are being parsed,
.RB "or should be " NULL " if no option aliasing is desired. The next "
two arguments specify the command-line arguments to parse. These are 
.RB "generally passed to " poptGetContext() " exactly as they were "
.RB "passed to the program's " main() " function. The " 
.IR options " parameter points to the table of command-line options, "
which was described in the previous section. The final parameter, 
.IR flags ,
can be any bitwise or combination of the following four values:
.br
.TS
lfB lfB
lfB lfR.
Value	Description
POPT_CONTEXT_NO_EXEC	Ignore exec expansions
POPT_CONTEXT_KEEP_FIRST	Do not ignore argv[0]
POPT_CONTEXT_POSIXMEHARDER	Options cannot follow arguments
POPT_CONTEXT_ARG_OPTS	Return the arguments as options of value 0
.TE
.sp
Here is a more detailed discussion of each flag:
.sp
.TP
.B POPT_CONTEXT_NO_EXEC
This bit disables all uses of
.BR exec "(2) from within the given popt context."
.sp
.TP
.B POPT_CONTEXT_KEEP_FIRST
By default, popt ignores the value in
.I argv[0]
as it is typically the name of the program being run rather than a command-line
argument. Specifying this flag causes popt to treat
.I argv[0]
as an option.
.sp
.TP
.B POPT_CONTEXT_POSIXMEHARDER
When this flag is set, it is required that all options is placed before any
arguments. This flag is also in effect if any of the environment variables
.B POSIXLY_CORRECT
or
.B POSIX_ME_HARDER
is set.
.sp
.TP
.B POPT_CONTEXT_ARG_OPTS
When this flag is set, all non-option arguments will get the value 0. This means
that
.B poptGetNextOpt()
returns 0 for all non-option arguments, while
.BR poptGetArg() " returns " NULL .
.sp
.PP
.RB "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 
.BR poptContext " by passing the context as the sole argument to "
.BR poptResetContext() .
.sp
When argument processing is complete, the process should free the 
.BR poptContext " as it contains dynamically allocated components. The "
.BR poptFreeContext() " function takes a " 
.BR poptContext " as its sole argument and frees the resources the "
context is using. It always returns NULL for convenience.
.sp
.RB "Here are the prototypes of both " poptResetContext() " and "
.BR poptFreeContext() :
.sp
.nf
.B #include <popt.h>
.BI "poptContext poptFreeContext(poptContext " con ");"
.BI "void poptResetContext(poptContext " con ");"
.fi
.sp
.SS "3. PARSING THE COMMAND LINE"
.RB "After an application has created a " poptContext ", it may begin "
.RB "parsing arguments. " poptGetNextOpt() " performs the actual "
argument parsing.
.sp
.nf
.B #include <popt.h>
.BI "int poptGetNextOpt(poptContext " con ");"
.fi
.sp
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 
.RI "table entry's " arg 
.RB "pointer if it is not " NULL ". If the val entry for the option is "
non-0, the function then returns that value. Otherwise, 
.BR poptGetNextOpt() " continues on to the next argument."
.sp
.BR poptGetNextOpt() " returns -1 when the final argument has been "
parsed, and other negative values when errors occur. This makes it a 
good idea to 
.RI "keep the " val " elements in the options table greater than 0."
.sp
.RI "If all of the command-line options are handled through " arg 
pointers, command-line parsing is reduced to the following line of code:
.sp
.nf
rc = poptGetNextOpt(poptcon);
.fi
.sp
Many applications require more complex command-line parsing than this,
however, and use the following structure:
.sp
.nf
while ((rc = poptGetNextOpt(poptcon)) > 0) {
     switch (rc) {
          /* specific arguments are handled here */
     }
}
.fi
.sp
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 
.RI "value of the option through the option table's " arg " elements. The "
.RB "other is to use " poptGetOptArg() ":"
.sp
.nf
.B #include <popt.h>
.BI "char * poptGetOptArg(poptContext " con ");"
.fi
.sp
This function returns the argument given for the final option returned by
.BR poptGetNextOpt() ", or it returns " NULL " if no argument was specified."
The calling function is responsible for deallocating this string.
.sp
.SS "4. LEFTOVER ARGUMENTS"
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:
.nf
.HP
.BI "const char * poptGetArg(poptContext " con ");"
.fi
This function returns the next leftover argument and marks it as
processed.
.PP
.nf
.HP
.BI "const char * poptPeekArg(poptContext " con ");"
.fi
The next leftover argument is returned but not marked as processed.
This allows an application to look ahead into the argument list,
without modifying the list.
.PP
.nf
.HP
.BI "const char ** poptGetArgs(poptContext " con ");"
.fi
All the leftover arguments are returned in a manner identical to 
.IR argv ".  The final element in the returned array points to "
.BR NULL ", indicating the end of the arguments.
.sp
.SS "5. AUTOMATIC HELP MESSAGES"
The \fBpopt\fR library can automatically generate help messages which
describe the options a program accepts. There are two types of help
messages which can be generated. Usage messages are a short messages
which lists valid options, but does not describe them. Help messages
describe each option on one (or more) lines, resulting in a longer, but
more useful, message. Whenever automatic help messages are used, the
\fBdescrip\fR and \fBargDescrip\fR fields \fBstruct poptOption\fR members
should be filled in for each option.
.sp
The \fBPOPT_AUTOHELP\fR macro makes it easy to add \fB--usage\fR and
\fB--help\fR messages to your program, and is described in part 1
of this man page. If more control is needed over your help messages,
the following two functions are available:
.sp
.nf
.B #include <popt.h>
.BI "void poptPrintHelp(poptContext " con ", FILE * " f ", int " flags ");
.BI "void poptPrintUsage(poptContext " con ", FILE * " f ", int " flags ");
.fi
.sp
\fBpoptPrintHelp()\fR displays the standard help message to the stdio file
descriptor f, while \fBpoptPrintUsage()\fR displays the shorter usage
message. Both functions currently ignore the \fBflags\fR argument; it is
there to allow future changes.
.sp
.SH "ERROR HANDLING"
All of the popt functions that can return errors return integers. 
When an error occurs, a negative error code is returned. The 
following table summarizes the error codes that occur:
.sp
.TS
lfB lfB
lfB lfR.
Error	Description
POPT_ERROR_NOARG	Argument missing for an option.
POPT_ERROR_BADOPT	Option's argument couldn't be parsed.
POPT_ERROR_UNWANTEDARG	Option does not take an argument.
POPT_ERROR_OPTSTOODEEP	Option aliasing nested too deeply.
POPT_ERROR_BADQUOTE	Quotations do not match.
POPT_ERROR_ERRNO	errno set, use strerror(errno).
POPT_ERROR_BADNUMBER	Option couldn't be converted to number.
POPT_ERROR_OVERFLOW	A given number was too big or small.
POPT_ERROR_BADOPERATION	Mutually exclusive logical operations requested.
POPT_ERROR_NULLARG	opt->arg should not be NULL.
POPT_ERROR_MALLOC	Memory allocation failed.
POPT_ERROR_BADCONFIG	Config file failed sanity test.
.TE
.sp
Here is a more detailed discussion of each error:
.sp
.TP
.B POPT_ERROR_NOARG
An option that requires an argument was specified on the command
line, but no argument was given. This can be returned only by
.BR poptGetNextOpt() .
.sp
.TP
.B POPT_ERROR_BADOPT
.RI "An option was specified in " argv " but is not in the option 
.RB "table. This error can be returned only from " poptGetNextOpt() .
.sp
.TP
.B POPT_ERROR_OPTSTOODEEP
A set of option aliases is nested too deeply. Currently, popt
follows options only 10 levels
.B (POPT_OPTION_DEPTH)
to prevent infinite recursion. Only
.B poptGetNextOpt()
can return this error.
.sp
.TP
.B POPT_ERROR_BADQUOTE
A parsed string has a quotation mismatch (such as a single quotation
.RB "mark). " poptParseArgvString() ", " poptReadConfigFile() ", or "
.BR poptReadDefaultConfig() " can return this error."
.sp
.TP
.B POPT_ERROR_ERRNO
.RI "A system call returned with an error, and " errno " still
contains the error from the system call. Both
.BR poptReadConfigFile() " and " poptReadDefaultConfig() " can "
return this error.
.sp
.TP
.B POPT_ERROR_BADNUMBER
A conversion from a string to a number (int or long) failed due
to the string containing non-numeric characters. This occurs when
.BR poptGetNextOpt() " is processing an argument of type " 
.BR POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", "
.BR POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."
.sp
.TP
.B POPT_ERROR_OVERFLOW
A string-to-number conversion failed because the number was too
.RB "large or too small. Like " POPT_ERROR_BADNUMBER ", this error 
.RB "can occur only when " poptGetNextOpt() " is processing an "
.RB "argument of type " POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", "
.BR POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."
.sp
.TP
.B POPT_ERROR_BADOPERATION
More than one logical operation (AND, OR, XOR) was specified for an option, or
.B POPT_ARGFLAG_RANDOM
was specified but the platform does not support the
.B random()
function. This can be returned only by
.BR poptSaveLongLong() ", " poptSaveLong() ", " poptSaveInt() ", "
.BR poptSaveShort() " and " poptGetNextOpt() "."
.sp
.TP
.B POPT_ERROR_NULLARG
An operation was invoked on a null target
.I arg
(including zero-length string arguments). In the
.B poptBitsArgs()
case, this includes an empty leftover
.I argv
array. This can only be returned by the
.B poptBits*()
and
.B poptSave*()
functions,
.B poptConfigFileToString()
and
.BR poptGetNextOpt() .
.sp
.TP
.B POPT_ERROR_MALLOC
Memory allocation failed. This can only be returned by
.BR poptReadFile() ,
.BR poptDupArgv() ,
.BR poptParseArgvString() ,
.B poptConfigFileToString()
and
.BR poptGetNextOpt() .
.sp
.TP
.B POPT_ERROR_BADCONFIG
The popt configuration files are corrupted. This can only be returned by
.B poptReadConfigFile()
and
.BR poptReadConfigFiles() .
.sp
.PP
Two functions are available to make it easy for applications to provide
good error messages.
.HP
.nf
.BI "const char *const poptStrerror(const int " error ");"
.fi
This function takes a popt error code and returns a string describing
.RB "the error, just as with the standard " strerror() " function."
.PP
.HP
.nf
.BI "const char * poptBadOption(poptContext " con ", int " flags ");"
.fi
.RB "If an error occurred during " poptGetNextOpt() ", this function "
.RI "returns the option that caused the error. If the " flags " argument"
.RB "is set to " POPT_BADOPTION_NOALIAS ", the outermost option is "
.RI "returned. Otherwise, " flags " should be 0, and the option that is "
returned may have been specified through an alias.
.PP
These two functions make popt error handling trivial for most 
applications. When an error is detected from most of the functions, 
an error message is printed along with the error string from 
.BR poptStrerror() ". When an error occurs during argument parsing, "
code similar to the following displays a useful error message:
.sp
.nf
fprintf(stderr, "%s: %s\\n",
        poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
        poptStrerror(rc));
.fi
.sp
.SH "OPTION ALIASING"
.RB "One of the primary benefits of using popt over " getopt() " is the "
ability to use option aliasing. This lets the user specify options that 
popt expands into other options when they are specified. If the standard 
.RB "grep program made use of popt, users could add a " --text " option "
.RB "that expanded to " "-i -n -E -2" " to let them more easily find "
information in text files.
.sp
.SS "1. SPECIFYING ALIASES"
.RI "Aliases are normally specified in two places: " /etc/popt 
.RB "and the " .popt " file in the user's home directory (found through "
.RB "the " HOME " environment variable). Both files have the same format, "
an arbitrary number of lines formatted like this:
.sp
.IB appname " alias " newoption "" " expansion"
.sp
.RI "The " appname " is the name of the application, which must be the "
.RI "same as the " name " parameter passed to "
.BR poptGetContext() ". This allows each file to specify aliases for "
.RB "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.
.sp
.RB "The following entry would add a " --text " option to the grep command, "
as suggested at the beginning of this section.
.sp
.B "grep alias --text -i -n -E -2"
.SS "2. ENABLING ALIASES"
.RB "An application must enable alias expansion for a " poptContext 
.RB "before calling " poptGetNextArg() " for the first time. There are "
three functions that define aliases for a context:
.HP
.nf
.BI "int poptReadDefaultConfig(poptContext " con ", int " flags ");"
.fi
.RI "This function reads aliases from " /etc/popt " and the "
.BR .popt " file in the user's home directory. Currently, "
.IR flags " should be "
.BR NULL ", as it is provided only for future expansion."
.PP
.HP
.nf
.BI "int poptReadConfigFile(poptContext " con ", char * " fn ");"
.fi
.RI "The file specified by " fn " is opened and parsed as a popt "
configuration file. This allows programs to use program-specific 
configuration files.
.PP
.HP
.nf
.BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ",
.BI "                 int " flags ");"
.fi
Occasionally, processes want to specify aliases without having to
read them from a configuration file. This function adds a new alias
.RI "to a context. The " flags " argument should be 0, as it is "
currently reserved for future expansion. The new alias is specified 
.RB "as a " "struct poptAlias" ", which is defined as:"
.sp
.nf
struct poptAlias {
     const char * longName; /* may be NULL */
     char shortName; /* may be '\\0' */
     int argc;
     const char ** argv; /* must be free()able */
};
.fi
.sp
.RI "The first two elements, " longName " and " shortName ", specify "
.RI "the option that is aliased. The final two, " argc " and " argv ","
define the expansion to use when the aliases option is encountered.
.PP
.SH "PARSING ARGUMENT STRINGS"
Although popt is usually used for parsing arguments already divided into
.RI "an " argv "-style array, some programs need to parse strings that "
are formatted identically to command lines. To facilitate this, popt 
provides a function that parses a string into an array of strings, 
using rules similar to normal shell parsing.
.sp
.nf
.B "#include <popt.h>"
.BI "int poptParseArgvString(char * " s ", int * " argcPtr ",
.BI "                        char *** " argvPtr ");"
.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ",
.BI "                        const char *** " argvPtr ");"
.fi
.sp
.RI "The string s is parsed into an " argv "-style array. The integer "
.RI "pointed to by the " argcPtr " parameter contains the number of elements "
.RI "parsed, and the final " argvPtr " parameter contains the address of the"
newly created array.
.RB "The routine " poptDupArgv() " can be used to make a copy of an existing "
argument array.
.sp
.RI "The " argvPtr 
.RB "created by " poptParseArgvString() " or " poptDupArgv() " is suitable to pass directly "
.RB "to " poptGetContext() .
Both routines return a single dynamically allocated contiguous
.RB "block of storage and should be " free() "ed when the application is"
finished with the storage.
.SH "HANDLING EXTRA ARGUMENTS"
Some applications implement the equivalent of option aliasing but need
.RB "to do so through special logic. The " poptStuffArgs() " function "
allows an application to insert new arguments into the current 
.BR poptContext .
.sp
.nf
.B "#include <popt.h>"
.BI "int poptStuffArgs(poptContext "con ", const char ** " argv ");"
.fi
.sp
.RI "The passed " argv 
.RB "must have a " NULL " pointer as its final element. When "
.BR poptGetNextOpt() " is next called, the "
"stuffed" arguments are the first to be parsed. popt returns to the 
normal arguments once all the stuffed arguments have been exhausted.
.SH "EXAMPLE"
The following example is a simplified version of the program "robin" 
which appears in Chapter 15 of the text cited below.  Robin has 
been stripped of everything but its argument-parsing logic, slightly 
reworked, and renamed "parse." It may prove useful in illustrating 
at least some of the features of the extremely rich popt library.
.sp
.nf
#include <popt.h>
#include <stdio.h>
#include <stdlib.h>

void usage(poptContext optCon, int exitcode, char *error, char *addl) {
    poptPrintUsage(optCon, stderr, 0);
    if (error) fprintf(stderr, "%s: %s\\n", error, addl);
    poptFreeContext(optCon);
    exit(exitcode);
}

int main(int argc, char *argv[]) {
   int     c;            /* used for argument parsing */
   int     i = 0;        /* used for tracking options */
   int     speed = 0;    /* used in argument parsing to set speed */
   int     raw = 0;      /* raw mode? */
   int     j;
   char    buf[BUFSIZ+1];
   const char *portname;
   poptContext optCon;   /* context for parsing command-line options */

   struct poptOption optionsTable[] = {
      { "bps", 'b', POPT_ARG_INT, &speed, 0,
	"signaling rate in bits-per-second", "BPS" },
      { "crnl", 'c', POPT_ARG_NONE, 0, 'c',
	"expand cr characters to cr/lf sequences", NULL },
      { "hwflow", 'h', POPT_ARG_NONE, 0, 'h',
	"use hardware (RTS/CTS) flow control", NULL },
      { "noflow", 'n', POPT_ARG_NONE, 0, 'n',
	"use no flow control", NULL },
      { "raw", 'r', POPT_ARG_NONE, &raw, 0,
	"don't perform any character conversions", NULL },
      { "swflow", 's', POPT_ARG_NONE, 0, 's',
	"use software (XON/XOF) flow control", NULL } ,
      POPT_AUTOHELP
      POPT_TABLEEND
    };

   optCon = poptGetContext(NULL, argc, (const char **) argv, optionsTable, 0);
   poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");

   if (argc < 2)
       usage(optCon, 1, 0, NULL);

   /* Now do options processing, get portname */
   while ((c = poptGetNextOpt(optCon)) >= 0) {
      switch (c) {
       case 'c':
          buf[i++] = 'c';
          break;
       case 'h':
          buf[i++] = 'h';
          break;
       case 's':
          buf[i++] = 's';
          break;
       case 'n':
          buf[i++] = 'n';
          break;
      }
   }
   portname = poptGetArg(optCon);
   if((portname == NULL) || !(poptPeekArg(optCon) == NULL))
      usage(optCon, 1, "Specify a single port", ".e.g., /dev/cua0");

   if (c < -1) {
      /* an error occurred during option processing */
      fprintf(stderr, "%s: %s\\n",
              poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
              poptStrerror(c));
      return 1;
   }

   /* Print out options, portname chosen */
   printf("Options  chosen: ");
   for(j = 0; j < i ; j++)
      printf("-%c ", buf[j]);
   if(raw) printf("-r ");
   if(speed) printf("-b %d ", speed);
   printf("\\nPortname chosen: %s\\n", portname);

   poptFreeContext(optCon);
   exit(0);
}
.fi
.sp
RPM, a popular Linux package management program, makes heavy use
of popt's features. Many of its command-line arguments are implemented
through popt aliases, which makes RPM an excellent example of how to
take advantage of the popt library. For more information on RPM, see
https://rpm.org. The popt source code distribution includes test
program(s) which use all of the features of the popt libraries in
various ways. If a feature isn't working for you, the popt test code
is the first place to look.
.SH BUGS
None presently known.
.SH AUTHOR
Erik W. Troan <ewt@redhat.com>
.PP
This man page is derived in part from
.IR "Linux Application Development"
by Michael K. Johnson and Erik W. Troan, Copyright (c) 1998 by Addison
Wesley Longman, Inc., and included in the popt documentation with the
permission of the Publisher and the appreciation of the Authors.
.PP
Thanks to Robert Lynch for his extensive work on this man page.
.SH "SEE ALSO"
.BR getopt (3)
.sp
.IR "Linux Application Development" ", by Michael K. Johnson and "
Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24.
.sp
.BR popt.pdf " is a PDF version of the above cited book "
chapter. It can be found in the source archive for popt available at: 
http://ftp.rpm.org/popt/releases/.