📄 i386-pc-mingw32-popt.3.html
字号:
<!-- manual page source format generated by PolyglotMan v3.0.9, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>POPT(3) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>
<A HREF="#toc">Table of Contents</A><P>
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
popt - Parse command line options
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<BR>
<PRE>#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);
</PRE>
<H2><A NAME="sect2" HREF="#toc2"></B>Description</A></H2>
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()</B> and <B>getopt_long()</B>
[see <B><A HREF="getopt.3.html">getopt</B>(3)</A>
].<B></B> Some specific advantages of popt are: it does not utilize
global variables, thus enabling multiple passes in parsing <I>argv</I> ; it can
parse an arbitrary array of <I>argv</I>-style elements, <I></I> 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. <P>
Like <B>getopt_long()</B>, the popt library supports short and long
style options. Recall that a <B>short option</B> consists of a - character followed
by a single alphanumeric character. A <B>long option</B>, 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. <P>
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.
<P>
It may be redistributed under the X consortium license, see the file COPYING
in the popt source distribution for details.
<H2><A NAME="sect3" HREF="#toc3">Basic Popt Usage</A></H2>
<H3><A NAME="sect4" HREF="#toc4">1. the Option
Table</A></H3>
Applications provide popt with information on their command-line options
by means of an "option table," i.e., an array of <B>struct poptOption </B> structures:
<P>
#include <popt.h> <P>
<BR>
<PRE>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 */
};
</PRE><P>
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, <I>longName</I> and
<I>shortName</I>, define the names of the option; the first is a long name, while
the latter is a single character. <P>
The <I>argInfo</I> member tells popt what type
of argument is expected<I></I> after the argument. If no option is expected, <B>POPT_ARG_NONE</B>
should be used. The rest of the valid values are shown in the following
table: <P>
<TABLE BORDER=0>
<TR><TD ALIGN=LEFT>Value</TD><TD ALIGN=LEFT>Description</TD><TD ALIGN=LEFT>arg Type</TD></TR>
<TR><TD ALIGN=LEFT>POPT_ARG_NONE</TD><TD ALIGN=LEFT>No argument expected</TD><TD ALIGN=LEFT>int</TD></TR>
<TR><TD ALIGN=LEFT>POPT_ARG_STRING</TD><TD ALIGN=LEFT>No
type checking to be performed</TD><TD ALIGN=LEFT>char *</TD></TR>
<TR><TD ALIGN=LEFT>POPT_ARG_INT</TD><TD ALIGN=LEFT>An integer argument is expected</TD><TD ALIGN=LEFT>int</TD></TR>
<TR><TD ALIGN=LEFT>POPT_ARG_LONG</TD><TD ALIGN=LEFT>A
long integer is expected</TD><TD ALIGN=LEFT>long</TD></TR>
<TR><TD ALIGN=LEFT>POPT_ARG_VAL</TD><TD ALIGN=LEFT>Integer value taken from CWval</TD><TD ALIGN=LEFT>int</TD></TR>
<TR><TD ALIGN=LEFT>POPT_ARG_FLOAT</TD><TD ALIGN=LEFT>An
float argument is expected</TD><TD ALIGN=LEFT>float</TD></TR>
<TR><TD ALIGN=LEFT>POPT_ARG_DOUBLE</TD><TD ALIGN=LEFT>A double argument is expected</TD><TD ALIGN=LEFT>double</TD></TR>
</TABLE>
<P>
For
numeric values, if the <I>argInfo</I> value is bitwise or'd with one of <B>POPT_ARGFLAG_OR</B>,
<B>POPT_ARGFLAG_AND</B>, or <B>POPT_ARGFLAG_XOR</B>, the value is saved by performing
an OR, AND, or XOR. If the <I>argInfo</I> value is bitwise or'd with <B>POPT_ARGFLAG_NOT</B>,
the value will be negated before saving. For the common operations of setting
and/or clearing bits, <B>POPT_BIT_SET</B> and <B>POPT_BIT_CLR</B> have the appropriate
flags set to perform bit operations. <P>
If the <I>argInfo</I> value is bitwise or'd
with <B>POPT_ARGFLAG_ONEDASH</B>, the long argument may be given with a single
- instead of two. For example, if <B>--longopt</B> is an option with <B>POPT_ARGFLAG_ONEDASH</B>,
is specified, <B>-longopt</B> is accepted as well. <P>
The next element, <I>arg</I>, allows
popt to automatically update <I></I> program variables when the option is used.
If <I>arg</I> is <I></I> <B>NULL</B>, it is ignored and popt takes no special action. <B></B> Otherwise
it should point to a variable of the type indicated in the right-most column
of the table above. <P>
If the option takes no argument (<I>argInfo</I> is <I></I> <B>POPT_ARG_NONE</B>),
the variable pointed to by <B></B> <I>arg</I> 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 <B>POPT_ARG_NONE</B> is 0.) If the option does take an argument,
the variable that <I>arg</I> points to is updated to reflect the value of the
argument.<I></I> Any string is acceptable for <B>POPT_ARG_STRING</B> arguments, but <B>POPT_ARG_INT</B>,
<B>POPT_ARG_LONG</B>, <B>POPT_ARG_FLOAT</B>, and <B>POPT_ARG_DOUBLE</B> are converted to the
appropriate type, and an error returned if the conversion fails. <P>
<B>POPT_ARG_VAL</B>
causes <I>arg</I> to be set to the (integer) value of <I>val</I> 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". <B>POPT_ARG_VAL</B>
causes the parsing function not to return a value, since the value of <I>val</I>
has already been used. <P>
If the <I>argInfo</I> value is bitwise or'd with <B>POPT_ARGFLAG_OPTIONAL</B>,
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. <P>
The next option, <I>val</I>, is the value popt's parsing
function <I></I> 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. <P>
The last two options, <I>descrip</I> and <I>argDescrip</I> are only required<I></I>
if automatic help messages are desired (automatic usage messages can be
generated without them). <I>descrip</I> is a text description of the<I></I> argument and
<I>argdescrip</I> is a short summary of the type of arguments<I></I> the option expects,
or NULL if the option doesn't require any <I></I> arguments. <P>
If popt should automatically
provide <B>--usage</B> and <B>--help</B> (<B>-?</B>) options, one line in the table should be the
macro <B>POPT_AUTOHELP</B>. This macro includes another option table (via <B>POPT_ARG_INCLUDE_TABLE;</B>
see below) in the main one which provides the table entries for these arguments.
When <B>--usage</B> or <B>--help</B> 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
<B>POPT_AUTOHELP</B>. <P>
If the <I>argInfo</I> value is bitwise or'd with <B>POPT_ARGFLAG_DOC_HIDDEN</B>,
the argument will not be shown in help output. <P>
If the <I>argInfo</I> value is bitwise
or'd with <B>POPT_ARGFLAG_SHOW_DEFAULT</B>, the inital value of the arg will be
shown in help output. <P>
The final structure in the table should have all the
pointer values set to <B>NULL</B> and all the arithmetic values set to 0, marking
the end of the table. The macro <B>POPT_TABLEEND</B> is provided to do that. <P>
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 <I>longName</I> element
must be <B>NULL</B> and the <B>shortName</B> element must be <B>'\0'</B>. <P>
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 <I>argInfo</I> field to <B>POPT_ARG_INCLUDE_TABLE</B> and the arg
field to point to the table which is being included. If automatic help generation
is being used, the <I>descrip</I> field should contain a overall description of
the option table being included. <P>
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 <I>arg</I> field. Option callbacks should match the following prototype:
<P>
<BR>
<PRE>void poptCallbackType(poptContext con, const struct
poptOption * opt, const char * arg, void * data);</PRE><P>
</B>The
first parameter is the context which is being parsed (see the next section
for information on contexts), <I>opt</I> points to the option which triggered
this callback, and <I>arg</I> is the option's argument. If the option does not take
an argument, <I>arg</I> is <B>NULL</B>. The final parameter, <I>data</I> is taken from the <I>descrip</I>
field of the option table entry which defined the callback. As <I>descrip</I> is
a pointer, this allows callback functions to be passed an arbitrary set
of data (though a typecast will have to be used). <P>
The option table entry
which defines a callback has an <I>argInfo</I> of <B>POPT_ARG_CALLBACK</B>, an <I>arg</I> which
points to the callback function, and a <I>descrip</I> field which specifies an
arbitrary pointer to be passed to the callback.
<H3><A NAME="sect5" HREF="#toc5">2. Creating a Context</A></H3>
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 <B>poptContext</B> data structure, an opaque type that should
not be modified outside the popt library. <P>
New popt contexts are created
by <B>poptGetContext()</B>: <P>
<BR>
<PRE>poptContext poptGetContext(const char * name, int argc,
const char ** argv, const struct poptOption
* options, int flags);</PRE><P>
</B>The first parameter, <I>name</I>,
is used only for alias handling (discussed later). It should be the name
of the application whose options are being parsed, or should be <B>NULL</B> if
no option aliasing is desired. The next two arguments specify the command-line
arguments to parse. These are generally passed to <B>poptGetContext()</B> exactly
as they were passed to the program's <B>main()</B> function. The <B></B> <I>options</I> parameter
points to the table of command-line options, which was described in the
previous section. The final parameter, <I>flags</I>, can take one of three values:
<BR>
<TABLE BORDER=0>
<TR><TD ALIGN=LEFT>Value</TD><TD ALIGN=LEFT>Description</TD></TR>
<TR><TD ALIGN=LEFT>POPT_CONTEXT_NO_EXEC</TD><TD ALIGN=LEFT>Ignore exec expansions</TD></TR>
<TR><TD ALIGN=LEFT>POPT_CONTEXT_KEEP_FIRST</TD><TD ALIGN=LEFT>Do
not ignore argv[0]</TD></TR>
<TR><TD ALIGN=LEFT>POPT_CONTEXT_POSIXMEHARDER</TD><TD ALIGN=LEFT>Options cannot follow arguments</TD></TR>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -