|
|
|
|
|
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 poptContext as its sole argument and frees
the resources the context 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.
|
|
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
arguments.
|
|
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
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 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 messages, 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:
|
|
An option that requires an argument was specified on the
command line, but no argument was given. This can be
returned only by poptGetNextOpt().
|
|
An option was specified in argv but is not in the
option table. This error can be returned only from
poptGetNextOpt().
|
|
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.
|
|
A parsed string has a quotation mismatch (such as a
single quotation mark). poptParseArgvString(),
poptReadConfigFile(), or
poptReadDefaultConfig() can return this error.
|
|
A conversion from a string to a number (int or long)
failed due to the string containing 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.
|
|
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 processing an argument of type
POPT_ARG_INT, POPT_ARG_LONG,
POPT_ARG_FLOAT, or POPT_ARG_DOUBLE.
|
|
A system call returned with an error, and errno
still contains the error from the system call. Both
poptReadConfigFile() 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 during 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.
|
|
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
expansion
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 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.
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
|
|
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 argument
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 similiar 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 poptDupArgv() can be used
to make a copy of an existing argument array.
The argvPtr created by
poptParseArgvString() or poptDupArgv() is
suitable to pass directly to poptGetContext(). Both
routines return a single dynamically allocated contiguous
block of storage and should be free()ed when the
application is finished with the storage.
|
HANDLING EXTRA ARGUMENTS
|
Some applications implement the equivalent of option
aliasing but need to do so through 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 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
working for you, the popt test code is the first place to
look.
|
BUGS
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, 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.
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
|
copyright 1998-2007, devdaily.com, all rights reserved.
devdaily.com, an alvin j. alexander production.
|