i386-pc-mingw32-popt.3

linux 命令行处理popt模块说明文档

.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 "                           int " flags );
.sp
.BI "void 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: ftp://ftp.rpm.org/pub/rpm/dist.
.sp
It may be redistributed under the X consortium 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' */
    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 */
};
.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 argument.  If no option is expected,
.B POPT_ARG_NONE
should be used.
The rest of the valid values 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_INT	An integer argument is expected	int
POPT_ARG_LONG	A long integer is expected	long
POPT_ARG_VAL	Integer value taken from \f(CWval\fR	int
POPT_ARG_FLOAT	An 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 
right-most column of the table above.
.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 " arguments, but "
.BR POPT_ARG_INT ", " POPT_ARG_LONG ", " 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 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 
.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 inital 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 a 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 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 \fIarg\fR field.
Option callbacks should match the following prototype:
.sp
.nf
.BI "void poptCallbackType(poptContext con, 
.BI "                      const struct poptOption * opt, 
.BI "                      const char * arg, void * data);
.fi
.sp
The first parameter is the context which is being parsed (see the next
section for information on contexts), \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