</TABLE>
<P>
A
<B>poptContext</B> 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  <B>poptContext</B> by passing
the context as the sole argument to  <B>poptResetContext()</B>. <P>
When argument processing
is complete, the process should free the  <B>poptContext</B> as it contains dynamically
allocated components. The  <B>poptFreeContext()</B> function takes a <B></B> <B>poptContext</B>
as its sole argument and frees the resources the  context is using. <P>
Here
are the prototypes of both <B>poptResetContext()</B> and  <B>poptFreeContext()</B>: <P>
<BR>
<PRE>#include &lt;popt.h&gt;void poptFreeContext(poptContext con);void poptResetContext(poptContext
con);</PRE><P>

<H3><A NAME="sect6" HREF="#toc6"></B>3. Parsing the Command Line</A></H3>
After an application has created a <B>poptContext</B>,
it may begin  parsing arguments. <B>poptGetNextOpt()</B> performs the actual  argument
parsing. <P>
<BR>
<PRE>#include &lt;popt.h&gt;int poptGetNextOpt(poptContext con);</PRE><P>
</B>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 <I>arg</I><I></I> pointer if it
is not <B>NULL</B>. If the val entry for the option is  non-0, the function then
returns that value. Otherwise,  <B>poptGetNextOpt()</B> continues on to the next
argument. <P>
<B>poptGetNextOpt()</B> 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 <I>val</I> elements in the options table greater than 0.<I></I> <P>
If all of
the command-line options are handled through <I>arg</I><I></I> pointers, command-line parsing
is reduced to the following line of code: <P>
<BR>
<PRE>rc = poptGetNextOpt(poptcon);
</PRE><P>
Many applications require more complex command-line parsing than this, however,
and use the following structure: <P>
<BR>
<PRE>while ((rc = poptGetNextOpt(poptcon)) &gt; 0) {
     switch (rc) {
          /* specific arguments are handled here */
     }
}
</PRE><P>
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 <I>arg</I> elements. The <I></I> other is to use
<B>poptGetOptArg()</B>: <P>
<BR>
<PRE>#include &lt;popt.h&gt;const char * poptGetOptArg(poptContext con);</PRE><P>
</B>This function
returns the argument given for the final option returned by <B>poptGetNextOpt()</B>,
or it returns <B>NULL</B> if no argument was specified. <P>

<H3><A NAME="sect7" HREF="#toc7">4. Leftover Arguments</A></H3>
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:
<BR>
<PRE></PRE>
<DL>

<DT><B>const char * poptGetArg(poptContext </B><I>con</I><B>);</B>This function returns the next
leftover argument and marks it as </DT>
<DD>processed. </DD>
</DL>
<P>
<BR>
<PRE></PRE>
<DL>

<DT><B>const char * poptPeekArg(poptContext </B><I>con</I><B>);</B>The next leftover argument is
returned but not marked as processed. </DT>
<DD>This allows an application to look
ahead into the argument list, without modifying the list. </DD>
</DL>
<P>
<BR>
<PRE></PRE>
<DL>

<DT><B>const char ** poptGetArgs(poptContext </B><I>con</I><B>);</B>All the leftover arguments are
returned in a manner identical to  </DT>
<DD><I>argv</I>.  The final element in the returned
array points to  <B>NULL</B>, indicating the end of the arguments. <P>
</DD>
</DL>

<H3><A NAME="sect8" HREF="#toc8">5. Automatic
Help Messages</A></H3>
The <B>popt</B> 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 <B>descrip</B> and <B>argDescrip</B>
fields <B>struct poptOption</B> members should be filled in for each option. <P>
The
<B>POPT_AUTOHELP</B> macro makes it easy to add <B>--usage</B> and <B>--help</B> 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:
<P>
<BR>
<PRE>#include &lt;popt.h&gt;void poptPrintHelp(poptContext con, FILE * f, int flags);void
poptPrintUsage(poptContext con, FILE * f, int flags);</PRE><P>
</B><B>poptPrintHelp()</B> displays
the standard help message to the stdio file descriptor f, while <B>poptPrintUsage()</B>
displays the shorter usage message. Both functions currently ignore the
<B>flags</B> argument; it is there to allow future changes. <P>

<H2><A NAME="sect9" HREF="#toc9">Error Handling</A></H2>
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: <P>
<BR>
<PRE>     Error                      DescriptionPOPT_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.</PRE><P>
Here
is a more detailed discussion of each error: <P>

<DL>

<DT><B>POPT_ERROR_NOARG</B> </DT>
<DD>An option
that requires an argument was specified on the command line, but no argument
was given. This can be returned only by <B>poptGetNextOpt()</B>. <P>
</DD>

<DT><B>POPT_ERROR_BADOPT</B>
</DT>
<DD>An option was specified in <I>argv</I> but is not in the option <I></I> table. This error
can be returned only from <B>poptGetNextOpt()</B>. <P>
</DD>

<DT><B>POPT_ERROR_OPTSTOODEEP</B> </DT>
<DD>A set
of option aliases is nested too deeply. Currently, popt  follows options
only 10 levels to prevent infinite recursion. Only  <B>poptGetNextOpt()</B> can
return this error. <P>
</DD>

<DT><B>POPT_ERROR_BADQUOTE</B> </DT>
<DD>A parsed string has a quotation mismatch
(such as a single quotation mark). <B>poptParseArgvString()</B>, <B>poptReadConfigFile()</B>,
or  <B>poptReadDefaultConfig()</B> can return this error. <P>
</DD>

<DT><B>POPT_ERROR_BADNUMBER</B>
</DT>
<DD>A conversion from a string to a number (int or long) failed due to the
string containing nonnumeric characters. This occurs when <B>poptGetNextOpt()</B>
is processing an argument of type <B></B> <B>POPT_ARG_INT</B>, <B>POPT_ARG_LONG</B>,  POPT_ARG_FLOAT<B>,
or </B>POPT_ARG_DOUBLE<B>.</B> <P>
</DD>

<DT><B>POPT_ERROR_OVERFLOW</B> </DT>
<DD>A string-to-number conversion failed
because the number was too large or too small. Like <B>POPT_ERROR_BADNUMBER</B>,
this error  can occur only when <B>poptGetNextOpt()</B> is processing an  argument
of type <B>POPT_ARG_INT</B>, <B>POPT_ARG_LONG</B>,  POPT_ARG_FLOAT<B>, or </B>POPT_ARG_DOUBLE<B>.</B>
<P>
</DD>

<DT><B>POPT_ERROR_ERRNO</B> </DT>
<DD>A system call returned with an error, and <I>errno</I> still
<I></I> contains the error from the system call. Both  <B>poptReadConfigFile()</B> and
<B>poptReadDefaultConfig()</B> can  return this error. <P>
</DD>
</DL>
<P>
Two functions are available
to make it easy for applications to provide good error messages. <BR>
<PRE></PRE>
<DL>

<DT><B>const char *const poptStrerror(const int </B><I>error</I><B>);</B>This function takes a popt
error code and returns a string describing </DT>
<DD>the error, just as with the
standard <B>strerror()</B> function. </DD>
</DL>
<P>
<BR>
<PRE></PRE>
<DL>

<DT><B>const char * poptBadOption(poptContext </B><I>con</I><B>, int </B><I>flags</I><B>);</B>If an error occurred
during <B>poptGetNextOpt()</B>, this function  </DT>
<DD>returns the option that caused
the error. If the <I>flags</I> argument<I></I> is set to <B>POPT_BADOPTION_NOALIAS</B>, the outermost
option is  returned. Otherwise, <I>flags</I> should be 0, and the option that is
<I></I> returned may have been specified through an alias. </DD>
</DL>
<P>
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  <B>poptStrerror()</B>. When an error occurs during
argument parsing,  code similiar to the following displays a useful error
message: <P>
<BR>
<PRE>fprintf(stderr, "%s: %s\n",
        poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
        poptStrerror(rc));
</PRE><P>

<H2><A NAME="sect10" HREF="#toc10">Option Aliasing</A></H2>
One of the primary benefits of using popt over <B>getopt()</B>
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 <B>--text</B> option  that expanded
to <B>-i -n -E -2</B> to let them more easily find  information in text files. <P>

<H3><A NAME="sect11" HREF="#toc11">1. Specifying
Aliases</A></H3>
Aliases are normally specified in two places: <I>/etc/popt</I><I></I> and the
<B>.popt</B> file in the user's home directory (found through  the <B>HOME</B> environment
variable). Both files have the same format,  an arbitrary number of lines
formatted like this: <P>
<I>appname</I><B> alias </B><I>newoption</I><B></B><I> expansion</I> <P>
The <I>appname</I> is the
name of the application, which must be the <I></I> same as the <I>name</I> parameter
passed to <I></I> <B>poptGetContext()</B>. This allows each file to specify aliases for
 multiple programs. The <B>alias</B> keyword specifies that an alias is  being
defined; currently popt configuration files support only aliases, but other