libpopt(3) C Library Functions libpopt(3)NAMElibpopt - 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 parses command-line options. The popt library provides
an alternative to parsing the argv array by hand, or using the
getopt(3) functions getopt() and getopt_long().
The popt library has the following advantages:
· popt does not use global variables, thus enabling multiple passes
in parsing argv.
· popt can parse an arbitrary array of argv-style elements, allowing
parsing of command-line strings from any source.
· popt provides a standard method of option aliasing. This feature
is discussed in detail below.
·
popt can exec external option filters.
· popt can automatically generate help and usage messages for the
application.
The popt library supports short and long options. A short option con‐
sists 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 popt 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 sep‐
arates a long option from an argument.
The popt library is highly portable and should work on any POSIX plat‐
form. The latest version is distributed with rpm and is available from:
ftp://ftp.rpm.org/pub/rpm/dist.
The popt library may be redistributed under the X consortium license,
see the file COPYING in the popt source distribution for details.
EXTENDED DESCRIPTION
Option Tables
Each application provides popt with information about the command-line
options for the application, by means of an option table. An option ta‐
ble is an array of struct poptOption structures, with the following
format:
#include <popt.h>
struct poptOption {
const char * longName; /* may be NULL */
char shortName; /* may be ' ' */
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 */
};
Option Table Members
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:
longName Defines the name of the option in a long name.
shortName Defines the name of the option in a single
character.
argInfo Tells popt what type of argument is expected
after the option. Valid values are as follows:
POPT_ARG_DOUBLE Double argument expected, arg
type: double
POPT_ARG_FLOAT Float argument expected, arg
type: float
POPT_ARG_INT Integer argument expected, arg
type: int
POPT_ARG_LONG Long integer expected, arg
type: long
POPT_ARG_NONE No argument expected, arg type:
int
POPT_ARG_STRING No type checking to be per‐
formed, arg type: char *
POPT_ARG_VAL Integer value taken from val,
arg type: int
For numeric values, if the argInfo 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 argInfo 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.
If the argInfovalue is bitwise or'd with
POPT_ARGFLAG_ONEDASH, the long argument may be
given with a single hyphen instead of two. For
example, if --longopt is an option with
POPT_ARGFLAG_ONEDASH, -longopt is also
accepted.
arg Allows popt to automatically update program
variables. If arg is NULL, popt ignores arg and
takes no special action. Otherwise, arg points
to a variable of the appropriate type, as fol‐
lows:
· If argInfo is POPT_ARG_NONE, the variable
pointed to by arg is set to 1 when the
option is used.
· If the option takes an argument, the vari‐
able pointed to by arg 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 argu‐
ments are converted to the appropriate
type, and an error returned if the conver‐
sion fails.
POPT_ARG_VAL causes arg to be set to the inte‐
ger value of val 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, rm -i-f. POPT_ARG_VAL causes the
parsing function not to return a value, because
the value of val has already been used.
If the argInfo 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 arg pointer is
present. Otherwise, the behavior is identical
to that of a long option with an argument.
val The value returned by the popt parsing function
when the option is encountered. If val is 0,
the parsing function does not return a value.
Instead, popt parses the next command-line
argument.
descrip Text description of the argument. Only required
if automatic help messages are desired. Auto‐
matic usage messages can be generated without
this argument.
argDescrip Short summary of the type of arguments expected
by the option, or NULL if the option does not
require any arguments. Only required if auto‐
matic help messages are desired. Automatic
usage messages can be generated without this
argument.
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.
Help and Usage Output
If popt should automatically provide -−usage and -−help 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 -−usage or
-−help option is passed to applications that use popt automatic help,
popt displays the appropriate message on stderr, and exits the applica‐
tion with a return code of 0. To use popt 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.
If the argInfo value is bitwise or'd with POPT_ARGFLAG_DOC_HIDDEN, the
argument is not shown in help output.
If the argInfo value is bitwise or'd with POPT_ARGFLAG_SHOW_DEFAULT,
the inital value of the arg is shown in help output.
Special Option Table Entries
Two types of option table entries do not specify command-line options.
When either of these types of entries is used, the longName element
must be NULL and the shortName element must be \0.
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 argInfo field to
POPT_ARG_INCLUDE_TABLE and the arg field to point to the table that is
being included. If automatic help generation is used, the descrip field
should contain an overall description of the option table being
included.
The other special option table entry type tells popt 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 popt set a variable through
the option's arg field. Option callbacks should match the following
prototype:
void poptCallbackType(poptContext con,
const struct poptOption * opt,
const char * arg, void * data);
The callback uses the following parameters:
con The context that is being parsed. See the next section
for information on contexts.
opt The option that triggered this callback.
arg The argument for the opt option. If the option does not
take an argument, arg is NULL.
data Taken from the descrip field of the option table entry
that defined the callback. As descrip is a pointer,
this allows you to pass an arbitrary set of data to
callback functions, though a typecast must be used.
The option table entry that defines a callback has an argInfo of
POPT_ARG_CALLBACK, an arg that points to the callback function, and a
descrip field that specifies an arbitrary pointer to be passed to the
callback.
Creating a Context
popt can interleave the parsing of multiple command-line sets. popt
allows this by keeping all of the state information for a particular
set of command-line arguments in a poptContext data structure, an
opaque type that should not be modified outside the popt library.
New popt contexts are created by poptGetContext():
poptContext poptGetContext(const char * name, int argc,
const char ** argv,
const struct poptOption * options,
int flags);
The poptGetContext() function takes the following parameters:
name Used only for alias handling. name should be
the name of the application whose options are
being parsed, or should be NULL if no option
aliasing is desired.
argc, argv Specifies the command-line arguments to parse.
These arguments are generally passed to popt‐
GetContext() exactly as they were passed to the
application's main() function.
options Points to the table of command-line options.
See the Option Tables section above.
flags Can take one of the following values:
POPT_CONTEXT_NO_EXEC Ignore exec expansions
POPT_CONTEXT_KEEP_FIRST Do not ignore argv[0]
POPT_CONTEXT_POSIXMEHARDOptions cannot follow
arguments
A poptContext keeps track of which options have already been parsed and
which remain to be parsed. If an application wishes to restart process‐
ing the options of a set of arguments, the application can reset the
poptContext by passing the context as the sole argument to poptReset‐
Context().
When argument processing is complete, the process should free the popt‐
Context, as it contains dynamically allocated components. The popt‐
FreeContext() function takes a poptContext as its sole argument and
frees the resources that the context is using.
Here are the prototypes of both poptResetContext() and poptFreeCon‐
text():
#include <popt.h>
void poptFreeContext(poptContext con);
void poptResetContext(poptContext con);
Parsing the Command Line
After an application has created a poptContext, the poptContext may
begin parsing arguments. poptGetNextOpt() performs the actual argument
parsing:
#include <popt.h>
int poptGetNextOpt(poptContext con);
Taking the context as its sole argument, the poptGetNextOpt() function
parses the next command-line argument found. When poptGetNextOpt()
finds the next argument in the option table, the function populates the
object pointed to by the option table entry's arg pointer, if the
pointer is not NULL. If the val entry for the option is not zero, the
function returns that value. Otherwise, poptGetNextOpt() continues to
the next argument.
poptGetNextOpt() returns −1 when the final argument has been parsed,
and other negative values when errors occur. Therefore, you should
ensure that the val elements in the option table are greater than 0.
If all of the command-line options are handled through arg pointers,
command-line parsing is reduced to the following line of code:
rc = poptGetNextOpt(poptcon);
Many applications require more complex command-line parsing than this,
however, and use the following structure:
while ((rc = poptGetNextOpt(poptcon)) > 0) {
switch (rc) {
/* specific arguments are handled here */
}
}
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 these values:
· Ask popt to populate a variable with the value of the option from
the option table's arg elements.
· Use poptGetOptArg():
#include <popt.h>
const char * poptGetOptArg(poptContext con);
The poptGetOptArg() function returns the argument given for the final
option returned by poptGetNextOpt(), or returns NULL if no argument was
specified.
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 hyphen, popt assumes that this is such an argu‐
ment, and adds the argument to a list of leftover arguments. Three
functions allow applications to access such arguments:
const char * poptGetArg(poptContext con);
Returns the next leftover argument and marks the argument as pro‐
cessed.
const char * poptPeekArg(poptContext con);
Returns the next leftover argument but does not mark the argument
as processed. This allows an application to look ahead into the
argument list, without modifying the list.
const char ** poptGetArgs(poptContext con);
Returns all of the leftover arguments in a manner identical to
argv. The final element in the returned array points to NULL, indi‐
cating the end of the arguments.
Automatic Help Messages
The popt library can automatically generate help messages that describe
the options that an application accepts. Two types of help messages can
be generated:
· Usage messages are short messages that list valid options, but do
not describe the options.
· Help messages describe each option in one or more lines, resulting
in a longer but more useful message.
Whenever automatic help messages are used, the descrip and argDescrip
members of the struct poptOption structure should be populated for each
option.
The POPT_AUTOHELP macro makes it easy to add usage and help messages to
your application, as described earlier in this man page. If you need
more control over your help messages, use the following functions:
#include <popt.h>
void poptPrintHelp(poptContext con, FILE * f, int flags);
void poptPrintUsage(poptContext con, FILE * f, int flags);
poptPrintHelp() displays the standard help message to the stdio file
descriptor f, while poptPrintUsage() displays the shorter usage mes‐
sage. Both functions currently ignore the flags argument, which is pro‐
vided for future functionality.
Option Aliasing
One of the primary benefits of popt is the ability to use option alias‐
ing. Option aliasing allows the user to specify options that popt
expands into other options. For example. if the standard grep command
made use of popt, users could add a -−text option that expanded to -i
-n -E -2, to allow users to more easily find information in text files.
Specifying Aliases
Aliases are normally specified in two places:
· /etc/popt
· $HOME/.popt
Both files have the same format, that is, an arbitrary number of lines
formatted as follows:
appname alias newoption expansion
An alias specification is composed of the following elements:
appname Specifies the name of the application, which
must be the same as the name parameter passed
to poptGetContext(). This allows each file to
specify aliases for multiple programs.
alias Specifies that an alias is being defined. Cur‐
rently, popt configuration files support only
aliases, but other abilities may be added in
the future.
newoption Specifies the option that should be aliased,
either a short option or a long option.
expansion Specifies the expansion for the alias. The
expansion is parsed in a similar way to a shell
command: backslashes are allowed, and single
quotation marks can 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 logi‐
cal continuation of the line containing the
backslash, just as in a shell command.
For example, the following entry would add to the grep command the
-−text option described earlier:
grep alias --text -i -n -E -2
Enabling Aliases
An application must enable alias expansion for a poptContext, before
calling poptGetNextArg() for the first time. Three functions define
aliases for a context:
int poptReadDefaultConfig(poptContext con, int flags);
Reads aliases from /etc/popt and $HOME/.popt. The flags argument
should be NULL, it is provided only for future expansion.
int poptReadConfigFile(poptContext con, char * fn);
Opens the file specified by fn and parses the file as a popt con‐
figuration file. This allows applications to use application-spe‐
cific configuration files.
int poptAddAlias(poptContext con, struct poptAlias alias, int flags);
Adds a new alias to a context. This function is useful when pro‐
cesses want to specify aliases without having to read them from a
configuration file. The flags argument should be 0, it is provided
only for future expansion. The new alias is specified as a struct
poptAlias, which is defined as follows:
struct poptAlias {
const char * longName; /* may be NULL */
char shortName; /* may be ' ' */
int argc;
const char ** argv; /* must be free()able */
};
longName and shortName specify the option that is aliased. argc and
argv define the expansion to use when the aliases option is encoun‐
tered.
Parsing Argument Strings
popt usually parses arguments that are already divided into an argv-
style array. However, some applications need to parse strings that are
formatted identically to command lines. To facilitate this, popt pro‐
vides a function that parses a string into an array of strings, using
rules similar to those of normal shell parsing:
#include <popt.h>
int poptParseArgvString(char * s, int * argcPtr,
char *** argvPtr);
int poptDupArgv(int argc, const char ** argv, int * argcPtr,
const char *** argvPtr);
The string s is parsed into an argv-style array. The integer pointed to
by the argcPtr parameter contains the number of elements parsed, and
the final argvPtr parameter contains the address of the newly created
array. The routine poptDupArgv() can be used to make a copy of an
existing argument array.
The argvPtr created by poptParseArgvString() or poptDupArgv() can be
passed directly to poptGetContext(). Both routines return a single
dynamically allocated contiguous block of storage and should be freed
using free() when the application is finished with the storage.
Handling Extra Arguments
Some applications implement the equivalent of option aliasing but do so
using special logic. The poptStuffArgs() function allows an application
to insert new arguments into the current poptContext:
#include <popt.h>
int poptStuffArgs(poptContext con, const char ** argv);
The passed argv must have a NULL pointer as its final element. When
poptGetNextOpt() is next called, the "stuffed" arguments are the first
to be parsed. popt returns to the normal arguments when all of the
stuffed arguments have been exhausted.
ERRORS
All of the popt functions that can return errors return integers. When
an error occurs, a negative error code is returned. The following
error codes can occur:
POPT_ERROR_BADNUMBER A string-to-number conversion failed because
the string contains nonnumeric characters. This
occurs when poptGetNextOpt() is processing an
argument of type POPT_ARG_INT, POPT_ARG_LONG,
POPT_ARG_FLOAT, or POPT_ARG_DOUBLE.
POPT_ERROR_BADOPT An option was specified in argv but is not in
the option table. This error can be returned
only from poptGetNextOpt().
POPT_ERROR_BADQUOTE A parsed string has a quotation mismatch, for
example, a single quotation mark. popt‐
ParseArgvString(), poptReadConfigFile(), or
poptReadDefaultConfig() can return this error.
POPT_ERROR_ERRNO A system call returned with an error, and errno
still contains the error from the system call.
Both poptReadConfigFile() and poptReadDefault‐
Config() can return this error.
POPT_ERROR_NOARG An option that requires an argument was speci‐
fied on the command line, but no argument was
given. This error can be returned only by popt‐
GetNextOpt().
POPT_ERROR_OPTSTOODEEP A set of option aliases is nested too deeply.
Currently, popt follows options to only 10 lev‐
els, to prevent infinite recursion. Only popt‐
GetNextOpt() can return this error.
POPT_ERROR_OVERFLOW A string-to-number conversion failed because
the number is too large or too small. This
error can occur only when poptGetNextOpt() is
processing an argument of type POPT_ARG_INT,
POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOU‐
BLE.
Two functions allow applications to provide good error messages:
const char *const poptStrerror(const int error);
Takes a popt error code and returns a string describing the error,
just as with the standard strerror() function.
const char * poptBadOption(poptContext con, int flags);
Returns the option that caused the error, if an error occurred dur‐
ing poptGetNextOpt(). If the flags argument is set to POPT_BADOP‐
TION_NOALIAS, the outermost option is returned. Otherwise, flags
should be 0, and the option that is returned may have been speci‐
fied through an alias.
These two functions ensure that popt error handling is 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 poptStr‐
error(). When an error occurs during argument parsing, code similar to
the following displays a useful error message:
fprintf(stderr, "%s: %s0,
poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
poptStrerror(rc));
EXAMPLES
Example 1: Parse Program Created From robin Program
The following example is a simplified version of the robin program that
appears in Chapter 15 of "Linux Application Development" by Michael K.
Johnson and Erik W. Troan (copyright 1998 by Addison Wesley Longman,
Inc.). The robin program has been stripped of everything but its argu‐
ment-parsing logic, slightly reworked, and renamed parse. This program
illustrates some of the features of the extremely rich popt library.
#include <popt.h>
#include <stdio.h>
void usage(poptContext optCon, int exitcode, char *error, char *addl) {
poptPrintUsage(optCon, stderr, 0);
if (error) fprintf(stderr, "%s: %s0, error, addl);
exit(exitcode);
}
int main(int argc, char *argv[]) {
char c; /* used for argument parsing */
int i = 0; /* used for tracking options */
char *portname;
int speed = 0; /* used in argument parsing to set speed */
int raw = 0; /* raw mode? */
int j;
char buf[BUFSIZ+1];
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', 0, 0, 'c',
"expand cr characters to cr/lf sequences" },
{ "hwflow", 'h', 0, 0, 'h',
"use hardware (RTS/CTS) flow control" },
{ "noflow", 'n', 0, 0, 'n',
"use no flow control" },
{ "raw", 'r', 0, &raw, 0,
"don't perform any character conversions" },
{ "swflow", 's', 0, 0, 's',
"use software (XON/XOF) flow control" } ,
POPT_AUTOHELP
{ NULL, 0, 0, NULL, 0 }
};
optCon = poptGetContext(NULL, argc, argv, optionsTable, 0);
poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");
if (argc < 2) {
poptPrintUsage(optCon, stderr, 0);
exit(1);
}
/* 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: %s0,
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("0ortname chosen: %s0, portname);
poptFreeContext(optCon);
exit(0);
}
RPM, a popular Linux package management application, uses several popt
features. Many RPM command-line arguments are implemented using popt
aliases, which makes RPM an excellent example of how to take advantage
of the popt library. For more information about RPM, see
http://www.rpm.org. The popt source code distribution includes test
programs that use all of the features of the popt libraries in various
ways. If a popt feature does not work for you, check the popt test
code.
FILES
The following files are used by this library:
/usr/lib/libpopt.so Command Line Parser API shared library
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │library/popt │
├─────────────────────────────┼─────────────────────────────┤
│Interface stability │Volatile │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOgetopt(3), attributes(5)NOTES
Updated by Erwann Chenede, Sun Microsystems Inc., 2003. Written by Erik
W. Troan (ewt@redhat.com), Michael K. Johnson, and Robert Lynch.
SunOS 5.11 31 May 2004 libpopt(3)
