Партнёры:
Хостинг:
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 vari-
ables, thus enabling multiple passes in parsing argv ; it
can parse an arbitrary array of argv-style elements, allow-
ing parsing of command-line-strings from any source; it pro-
vides 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 mes-
sages 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 compatibil-
ity 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 always available
from: ftp://ftp.redhat.com/pub/redhat/code/popt.
It may be redistributed under either the GNU General Public
License or the GNU Library General Public License, at the
distributor's discretion.
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 con-
sidered 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:
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_INT An integer argument is expected int
POPT_ARG_LONG A long integer is expected long
POPT_ARG_VAL Integer value taken from val int
If the argInfo value is bitwise or'd with
POPT_ARGFLAG_ONEDASH, the long argument may be given with a
single - instead of two. For example, if --longopt is an
option with POPT_ARGFLAG_ONEDASH, is specified, -longopt is
accepted as well.
The next element, arg, allows popt to automatically update
program variables when the option is used. If arg is NULL,
it is ignored and popt takes no special action. Otherwise it
should point to a variable of the type indicated in the
right-most column of the table above.
If the option takes no argument (argInfo is POPT_ARG_NONE),
the variable pointed to by arg is set to 1 when the option
is used. (Incidentally, it will perhaps not escape the
attention of hunt-and-peck typists that the value of
POPT_ARG_NONE is 0.) If the option does take an argument,
the variable that arg points to is updated to reflect the
value of the argument. Any string is acceptable for
POPT_ARG_STRING arguments, but POPT_ARG_INT and
POPT_ARG_LONG are converted to the appropriate type, and an
error returned if the conversion fails.
POPT_ARG_VAL causes arg to be set to the (integer) value of
val 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".
POPT_ARG_VAL causes the parsing function not to return a
value, since the value of val has already been used.
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 pars-
ing the next command-line argument.
The last two options, descrip and argDescrip are only
required if automatic help messages are desired (automatic
usage messages can be generated without them). descrip is a
text description of the argument and argdescrip is a short
summary of the type of arguments the option expects, or NULL
if the option doesn't require any arguments.
If popt should automatically provide --usage and --help (-?
options, one line in the table should be the macro
POPT_AUTOHELP. This macro includes another option table
(via POPT_ARG_INCLUDE_TABLE; see below) in the main one
which provides the table entries for these arguments. When
--usage or --help are passed to programs which use popt's
automatical 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 option table instead
of using POPT_AUTOHELP.
If the argInfo value is bitwise or'd with
POPT_ARGFLAG_DOC_HIDDEN, the argument will not be shown in
help output.
The final structure in the table should have all the pointer
values set to NULL and all the arithmetic values set to 0,
marking the end of the table.
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 longName element must be NULL and the
shortName element must be '\0'.
The first of these special entry types allows the applica-
tion 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 argInfo field to POPT_ARG_INCLUDE_TABLE and the arg
field to point to the table which is being included. If
automatic help generation is being used, the descrip field
should contain a overall description of the option table
being included.
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 usefull 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 arg field.
Option callbacks should match the following prototype:
void poptCallbackType(poptContext con,
const struct poptOption * opt,
const char * arg, void * data);
The first parameter is the context which is being parsed
(see the next section for information on contexts), opt
points to the option which triggered this callback, and arg
is the option's argument. If the option does not take an
argument, arg is NULL. The final parameter, data is taken
from the descrip field of the option table entry which
defined the callback. As descrip is a pointer, this allows
callback functions to be passed an arbitrary set of data
(though a typecast will have to be used).
The option table entry which defines a callback has an
argInfo of POPT_ARG_CALLBACK, an arg which points to the
callback function, and a descrip field which specifies an
arbitrary pointer to be passed to the callback.
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 poptCon-
text data structure, an opaque type that should not be modi-
fied 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 first parameter, name, is used only for alias handling
(discussed later). It should be the name of the application
whose options are being parsed, or should be NULL if no
option aliasing is desired. The next two arguments specify
the command-line arguments to parse. These are generally
passed to poptGetContext() exactly as they were passed to
the program's main() function. The options parameter points
to the table of command-line options, which was described in
the previous section. The final parameter, flags,is not
currently used but should always be specified as 0 for com-
patibility with future versions of the popt library.
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 poptContext by passing the context as the
sole argument to poptResetContext().
When argument processing is complete, the process should
free the poptContext as it contains dynamically allocated
components. The poptFreeContext() function takes a poptCon-
text as its sole argument and frees the resources the con-
text is using.
Here are the prototypes of both poptResetContext() and
poptFreeContext():
#include <popt.h>
void poptFreeContext(poptContext con);
void poptResetContext(poptContext con);
3. PARSING THE COMMAND LINE
After an application has created a poptContext, it may begin
parsing arguments. poptGetNextOpt() performs the actual
argument parsing.
#include <popt.h>
int poptGetNextOpt(poptContext con);
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 table entry's arg
pointer if it is not NULL. If the val entry for the option
is non-0, the function then returns that value. Otherwise,
poptGetNextOpt() continues on to the next argument.
poptGetNextOpt() returns -1 when the final argument has been
parsed, and other negative values when errors occur. This
makes it a good idea to keep the val elements in the options
table 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 them. One is to
ask popt to fill in a variable with the value of the option
through the option table's arg elements. The other is to use
poptGetOptArg():
#include <popt.h>
const char * poptGetOptArg(poptContext con);
This function returns the argument given for the final
option returned by poptGetNextOpt(), or it returns NULL if
no argument was specified.
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:
const char * poptGetArg(poptContext con);
This function returns the next leftover argument and
marks it as processed.
const char * poptPeekArg(poptContext con);
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.
const char ** poptGetArgs(poptContext con);
All the leftover arguments are returned in a manner
identical to argv. The final element in the returned
array points to NULL, indicating the end of the argu-
ments.
5. AUTOMATIC HELP MESSAGES
The popt 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 mes-
sages 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 use-
ful, message. Whenever automatic help messages are used, the
descrip and argDescrip fields struct poptOption members
should be filled in for each option.
The POPT_AUTOHELP macro makes it easy to add --usage and --
help messages to your program, and is described in part 1 of
this man page. If more control is needed over your help mes-
sages, the following two functions are available:
#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 message. Both functions currently ignore the
flags argument; it is there to allow future changes.
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:
Error Description
POPT_ERROR_NOARG Argument missing for an option.
POPT_ERROR_BADOPT Option's argument couldn't be parsed.
POPT_ERROR_OPTSTOODEEP Option aliasing nested too deeply.
POPT_ERROR_BADQUOTE Quotations do not match.
POPT_ERROR_BADNUMBER Option couldn't be converted to number.
POPT_ERROR_OVERFLOW A given number was too big or small.
Here is a more detailed discussion of each error:
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 poptGetNextOpt().
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_OPTSTOODEEP
A set of option aliases is nested too deeply.
Currently, popt follows options only 10 levels to
prevent infinite recursion. Only poptGetNextOpt() can
return this error.
POPT_ERROR_BADQUOTE
A parsed string has a quotation mismatch (such as a
single quotation mark). poptParseArgvString(), pop-
tReadConfigFile(), or poptReadDefaultConfig() can
return this error.
POPT_ERROR_BADNUMBER
A conversion from a string to a number (int or long)
failed due to the string containing nonnumeric charac-
ters. This occurs when poptGetNextOpt() is processing
an argument of type POPT_ARG_INT or POPT_ARG_LONG.
POPT_ERROR_OVERFLOW
A string-to-number conversion failed because the number
was too large or too small. Like POPT_ERROR_BADNUMBER,
this error can occur only when poptGetNextOpt() is pro-
cessing an argument of type POPT_ARG_INT or
POPT_ARG_LONG.
POPT_ERROR_ERRNO
A system call returned with an error, and errno still
contains the error from the system call. Both poptRead-
ConfigFile() and poptReadDefaultConfig() can return
this error.
Two functions are available to make it easy for applications
to provide good error messages.
const char *const poptStrerror(const int error);
This function 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);
If an error occurred during poptGetNextOpt(), this
function returns the option that caused the error. If
the flags argument is set to POPT_BADOPTION_NOALIAS,
the outermost option is returned. Otherwise, flags
should be 0, and the option that is returned may have
been specified through an alias.
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 poptStrerror(). When an error occurs dur-
ing argument parsing, code similiar to the following
displays a useful error message:
fprintf(stderr, "%s: %s\n",
poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
poptStrerror(rc));
OPTION ALIASING
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 grep program made use of
popt, users could add a --text option that expanded to -i -n
-E -2 to let them more easily find information in text
files.
1. SPECIFYING ALIASES
Aliases are normally specified in two places: /etc/popt and
the .popt file in the user's home directory (found through
the HOME environment variable). Both files have the same
format, an arbitrary number of lines formatted like this:
appname alias newoption
The appname is 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 pro-
grams. 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 simi-
larly 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.
The following entry would add a --text option to the grep
command, as suggested at the beginning of this section.
grep alias --text -i -n -E -2
2. ENABLING ALIASES
An application must enable alias expansion for a poptContext
before calling poptGetNextArg() for the first time. There
are three functions that define aliases for a context:
int poptReadDefaultConfig(poptContext con, int flags);
This function reads aliases from /etc/popt and the
.popt file in the user's home directory. Currently,
flags should be NULL, as it is provided only for future
expansion.
int poptReadConfigFile(poptContext con, char * fn);
The file specified by fn is opened and parsed as a popt
configuration file. This allows programs to use
program-specific configuration files.
int poptAddAlias(poptContext con, struct poptAlias alias,
int flags);
Occasionally, processes want to specify aliases without
having to read them from a configuration file. This
function adds a new alias to a context. The flags argu-
ment should be 0, as it is currently reserved for
future expansion. The new alias is specified as a
struct poptAlias, which is defined as:
struct poptAlias {
const char * longName; /* may be NULL */
char shortName; /* may be '\0' */
int argc;
const char ** argv; /* must be free()able */
};
The first two elements, longName and shortName, specify
the option that is aliased. The final two, argc and
argv, define the expansion to use when the aliases
option is encountered.
PARSING ARGUMENT STRINGS
Although popt is usually used for parsing arguments already
divided into 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 simi-
liar to 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 poptDu-
pArgv() can be used to make a copy of an existing argument
array.
The argvPtr created by poptParseArgvString() or poptDu-
pArgv() is suitable to pass directly to poptGetContext().
Both routines return a single dynamically allocated contigu-
ous block of storage and should be free()ed when the appli-
cation is finished with the storage.
HANDLING EXTRA ARGUMENTS
Some applications implement the equivalent of option alias-
ing but need to do so through special logic. The poptStuf-
fArgs() 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 ele-
ment. When 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.
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.
#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: %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);
}
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
http://www.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 work-
ing for you, the popt test code is the first place to look.
BUGS
None presently known.
AUTHOR
Erik W. Troan <ewt@redhat.com>
This man page is derived in part from Linux Application
Development by Michael K. Johnson and Erik W. Troan, Copy-
right (c) 1998 by Addison Wesley Longman, Inc., and included
in the popt documentation with the permission of the Pub-
lisher and the appreciation of the Authors.
Thanks to Robert Lynch for his extensive work on this man
page.
SEE ALSO
getopt(3)
Linux Application Development, by Michael K. Johnson and
Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5),
Chapter 24.
popt.ps is a Postscript version of the above cited book
chapter. It can be found in the source archive for popt
available at: ftp://ftp.redhat.com/pub/redhat/code/popt
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |