popt.3

popt-1.7.tar.gz ninigui之MDE编译库支持文件库

to be passed to the callback.
.SS "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 
.BR poptContext " data structure, an opaque type that should not be "
modified outside the popt library.
.sp
.RB "New popt contexts are created by " poptGetContext() ":"
.sp
.nf
.BI "poptContext poptGetContext(const char * " name ", int "argc ",
.BI "                           const char ** "argv ",
.BI "                           const struct poptOption * "options ",
.BI "                           int "flags ");"
.fi
.sp
The first parameter, 
.IR name ", is used only for alias handling (discussed later). It "
should be the name of the application whose options are being parsed,
.RB "or should be " NULL " if no option aliasing is desired. The next "
two arguments specify the command-line arguments to parse. These are 
.RB "generally passed to " poptGetContext() " exactly as they were "
.RB "passed to the program's " main() " function. The " 
.IR options " parameter points to the table of command-line options, "
which was described in the previous section. The final parameter, 
.IR flags ,
can take one of three values:
.br
.TS
lfB lfB
lfB lfR.
Value	Description
POPT_CONTEXT_NO_EXEC	Ignore exec expansions
POPT_CONTEXT_KEEP_FIRST	Do not ignore argv[0]
POPT_CONTEXT_POSIXMEHARDER	Options cannot follow arguments
.TE
.sp
.RB "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 
.BR poptContext " by passing the context as the sole argument to "
.BR poptResetContext() .
.sp
When argument processing is complete, the process should free the 
.BR poptContext " as it contains dynamically allocated components. The "
.BR poptFreeContext() " function takes a " 
.BR poptContext " as its sole argument and frees the resources the "
context is using.
.sp
.RB "Here are the prototypes of both " poptResetContext() " and "
.BR poptFreeContext() :
.sp
.nf
.B #include <popt.h>
.BI "void poptFreeContext(poptContext " con ");"
.BI "void poptResetContext(poptContext " con ");"
.fi
.sp
.SS "3. PARSING THE COMMAND LINE"
.RB "After an application has created a " poptContext ", it may begin "
.RB "parsing arguments. " poptGetNextOpt() " performs the actual "
argument parsing.
.sp
.nf
.B #include <popt.h>
.BI "int poptGetNextOpt(poptContext " con ");"
.fi
.sp
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 
.RI "table entry's " arg 
.RB "pointer if it is not " NULL ". If the val entry for the option is "
non-0, the function then returns that value. Otherwise, 
.BR poptGetNextOpt() " continues on to the next argument."
.sp
.BR poptGetNextOpt() " returns -1 when the final argument has been "
parsed, and other negative values when errors occur. This makes it a 
good idea to 
.RI "keep the " val " elements in the options table greater than 0."
.sp
.RI "If all of the command-line options are handled through " arg 
pointers, command-line parsing is reduced to the following line of code:
.sp
.nf
rc = poptGetNextOpt(poptcon);
.fi
.sp
Many applications require more complex command-line parsing than this,
however, and use the following structure:
.sp
.nf
while ((rc = poptGetNextOpt(poptcon)) > 0) {
     switch (rc) {
          /* specific arguments are handled here */
     }
}
.fi
.sp
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 
.RI "value of the option through the option table's " arg " elements. The "
.RB "other is to use " poptGetOptArg() ":"
.sp
.nf
.B #include <popt.h>
.BI "const char * poptGetOptArg(poptContext " con ");"
.fi
.sp
This function returns the argument given for the final option returned by
.BR poptGetNextOpt() ", or it returns " NULL " if no argument was specified."
.sp
.SS "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:
.nf
.HP
.BI "const char * poptGetArg(poptContext " con ");"
.fi
This function returns the next leftover argument and marks it as
processed.
.PP
.nf
.HP
.BI "const char * poptPeekArg(poptContext " con ");"
.fi
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.
.PP
.nf
.HP
.BI "const char ** poptGetArgs(poptContext " con ");"
.fi
All the leftover arguments are returned in a manner identical to 
.IR argv ".  The final element in the returned array points to "
.BR NULL ", indicating the end of the arguments.
.sp
.SS "5. AUTOMATIC HELP MESSAGES"
The \fBpopt\fR 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
\fBdescrip\fR and \fBargDescrip\fR fields \fBstruct poptOption\fR members
should be filled in for each option.
.sp
The \fBPOPT_AUTOHELP\fR macro makes it easy to add \fB--usage\fR and
\fB--help\fR 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:
.sp
.nf
.B #include <popt.h>
.BI "void poptPrintHelp(poptContext " con ", FILE * " f ", int " flags ");
.BI "void poptPrintUsage(poptContext " con ", FILE * " f ", int " flags ");
.fi
.sp
\fBpoptPrintHelp()\fR displays the standard help message to the stdio file
descriptor f, while \fBpoptPrintUsage()\fR displays the shorter usage
message. Both functions currently ignore the \fBflags\fR argument; it is
there to allow future changes.
.sp
.SH "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:
.sp
.nf
.B "     Error                      Description"
.BR "POPT_ERROR_NOARG       " "Argument missing for an option."
.BR "POPT_ERROR_BADOPT      " "Option's argument couldn't be parsed."
.BR "POPT_ERROR_OPTSTOODEEP " "Option aliasing nested too deeply."
.BR "POPT_ERROR_BADQUOTE    " "Quotations do not match."
.BR "POPT_ERROR_BADNUMBER   " "Option couldn't be converted to number."
.BR "POPT_ERROR_OVERFLOW    " "A given number was too big or small."
.fi
.sp
Here is a more detailed discussion of each error:
.sp
.TP
.B 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
.BR poptGetNextOpt() .
.sp
.TP
.B POPT_ERROR_BADOPT
.RI "An option was specified in " argv " but is not in the option 
.RB "table. This error can be returned only from " poptGetNextOpt() .
.sp
.TP
.B POPT_ERROR_OPTSTOODEEP
A set of option aliases is nested too deeply. Currently, popt 
follows options only 10 levels to prevent infinite recursion. Only 
.BR poptGetNextOpt() " can return this error."
.sp
.TP
.B POPT_ERROR_BADQUOTE
A parsed string has a quotation mismatch (such as a single quotation
.RB "mark). " poptParseArgvString() ", " poptReadConfigFile() ", or "
.BR poptReadDefaultConfig() " can return this error."
.sp
.TP
.B POPT_ERROR_BADNUMBER
A conversion from a string to a number (int or long) failed due
to the string containing nonnumeric characters. This occurs when
.BR poptGetNextOpt() " is processing an argument of type " 
.BR POPT_ARG_INT ", " POPT_ARG_LONG ", "
.RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."  
.sp
.TP
.B POPT_ERROR_OVERFLOW
A string-to-number conversion failed because the number was too
.RB "large or too small. Like " POPT_ERROR_BADNUMBER ", this error 
.RB "can occur only when " poptGetNextOpt() " is processing an "
.RB "argument of type " POPT_ARG_INT ", " POPT_ARG_LONG ", "
.RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."  
.sp
.TP
.B POPT_ERROR_ERRNO
.RI "A system call returned with an error, and " errno " still 
contains the error from the system call. Both 
.BR poptReadConfigFile() " and " poptReadDefaultConfig() " can "
return this error.
.sp
.PP
Two functions are available to make it easy for applications to provide
good error messages.
.HP
.nf
.BI "const char *const poptStrerror(const int " error ");"
.fi
This function takes a popt error code and returns a string describing
.RB "the error, just as with the standard " strerror() " function."
.PP
.HP
.nf
.BI "const char * poptBadOption(poptContext " con ", int " flags ");"
.fi
.RB "If an error occurred during " poptGetNextOpt() ", this function "
.RI "returns the option that caused the error. If the " flags " argument"
.RB "is set to " POPT_BADOPTION_NOALIAS ", the outermost option is "
.RI "returned. Otherwise, " flags " should be 0, and the option that is "
returned may have been specified through an alias.
.PP
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 
.BR poptStrerror() ". When an error occurs during argument parsing, "