<html lang="en">
<head>
<title>Argp Special Keys - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Argp-Parser-Functions.html#Argp-Parser-Functions" title="Argp Parser Functions">
<link rel="next" href="Argp-Parsing-State.html#Argp-Parsing-State" title="Argp Parsing State">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Argp-Special-Keys"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Argp-Parsing-State.html#Argp-Parsing-State">Argp Parsing State</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Argp-Parser-Functions.html#Argp-Parser-Functions">Argp Parser Functions</a>
<hr>
</div>

<h5 class="subsubsection">25.3.5.1 Special Keys for Argp Parser Functions</h5>

<p>In addition to key values corresponding to user options, the <var>key</var>
argument to argp parser functions may have a number of other special
values.  In the following example <var>arg</var> and <var>state</var> refer to
parser function arguments.  See <a href="Argp-Parser-Functions.html#Argp-Parser-Functions">Argp Parser Functions</a>.

     <dl>
<!-- argp.h -->
<!-- GNU -->
<dt><code>ARGP_KEY_ARG</code><a name="index-ARGP_005fKEY_005fARG-3050"></a><dd>This is not an option at all, but rather a command line argument, whose
value is pointed to by <var>arg</var>.

     <p>When there are multiple parser functions in play due to argp parsers
being combined, it's impossible to know which one will handle a specific
argument.  Each is called until one returns 0 or an error other than
<code>ARGP_ERR_UNKNOWN</code>; if an argument is not handled,
<code>argp_parse</code> immediately returns success, without parsing any more
arguments.

     <p>Once a parser function returns success for this key, that fact is
recorded, and the <code>ARGP_KEY_NO_ARGS</code> case won't be
used.  <em>However</em>, if while processing the argument a parser function
decrements the <code>next</code> field of its <var>state</var> argument, the option
won't be considered processed; this is to allow you to actually modify
the argument, perhaps into an option, and have it processed again.

     <!-- argp.h -->
     <!-- GNU -->
     <br><dt><code>ARGP_KEY_ARGS</code><a name="index-ARGP_005fKEY_005fARGS-3051"></a><dd>If a parser function returns <code>ARGP_ERR_UNKNOWN</code> for
<code>ARGP_KEY_ARG</code>, it is immediately called again with the key
<code>ARGP_KEY_ARGS</code>, which has a similar meaning, but is slightly more
convenient for consuming all remaining arguments.  <var>arg</var> is 0, and
the tail of the argument vector may be found at <var>state</var><code>-&gt;argv
+ </code><var>state</var><code>-&gt;next</code>.  If success is returned for this key, and
<var>state</var><code>-&gt;next</code> is unchanged, all remaining arguments are
considered to have been consumed.  Otherwise, the amount by which
<var>state</var><code>-&gt;next</code> has been adjusted indicates how many were used. 
Here's an example that uses both, for different args:

     <pre class="smallexample">          ...
          case ARGP_KEY_ARG:
            if (<var>state</var>-&gt;arg_num == 0)
              /* First argument */
              first_arg = <var>arg</var>;
            else
              /* Let the next case parse it.  */
              return ARGP_KEY_UNKNOWN;
            break;
          case ARGP_KEY_ARGS:
            remaining_args = <var>state</var>-&gt;argv + <var>state</var>-&gt;next;
            num_remaining_args = <var>state</var>-&gt;argc - <var>state</var>-&gt;next;
            break;
</pre>
     <!-- argp.h -->
     <!-- GNU -->
     <br><dt><code>ARGP_KEY_END</code><a name="index-ARGP_005fKEY_005fEND-3052"></a><dd>This indicates that there are no more command line arguments.  Parser
functions are called in a different order, children first.  This allows
each parser to clean up its state for the parent.

     <!-- argp.h -->
     <!-- GNU -->
     <br><dt><code>ARGP_KEY_NO_ARGS</code><a name="index-ARGP_005fKEY_005fNO_005fARGS-3053"></a><dd>Because it's common to do some special processing if there aren't any
non-option args, parser functions are called with this key if they
didn't successfully process any non-option arguments.  This is called
just before <code>ARGP_KEY_END</code>, where more general validity checks on
previously parsed arguments take place.

     <!-- argp.h -->
     <!-- GNU -->
     <br><dt><code>ARGP_KEY_INIT</code><a name="index-ARGP_005fKEY_005fINIT-3054"></a><dd>This is passed in before any parsing is done.  Afterwards, the values of
each element of the <code>child_input</code> field of <var>state</var>, if any, are
copied to each child's state to be the initial value of the <code>input</code>
when <em>their</em> parsers are called.

     <!-- argp.h -->
     <!-- GNU -->
     <br><dt><code>ARGP_KEY_SUCCESS</code><a name="index-ARGP_005fKEY_005fSUCCESS-3055"></a><dd>Passed in when parsing has successfully been completed, even if
arguments remain.

     <!-- argp.h -->
     <!-- GNU -->
     <br><dt><code>ARGP_KEY_ERROR</code><a name="index-ARGP_005fKEY_005fERROR-3056"></a><dd>Passed in if an error has occurred and parsing is terminated.  In this
case a call with a key of <code>ARGP_KEY_SUCCESS</code> is never made.

     <!-- argp.h -->
     <!-- GNU -->
     <br><dt><code>ARGP_KEY_FINI</code><a name="index-ARGP_005fKEY_005fFINI-3057"></a><dd>The final key ever seen by any parser, even after
<code>ARGP_KEY_SUCCESS</code> and <code>ARGP_KEY_ERROR</code>.  Any resources
allocated by <code>ARGP_KEY_INIT</code> may be freed here.  At times, certain
resources allocated are to be returned to the caller after a successful
parse.  In that case, those particular resources can be freed in the
<code>ARGP_KEY_ERROR</code> case. 
</dl>

   <p>In all cases, <code>ARGP_KEY_INIT</code> is the first key seen by parser
functions, and <code>ARGP_KEY_FINI</code> the last, unless an error was
returned by the parser for <code>ARGP_KEY_INIT</code>.  Other keys can occur
in one the following orders.  <var>opt</var> refers to an arbitrary option
key:

     <dl>
<dt><var>opt</var><small class="dots">...</small> <code>ARGP_KEY_NO_ARGS</code> <code>ARGP_KEY_END</code> <code>ARGP_KEY_SUCCESS</code><dd>The arguments being parsed did not contain any non-option arguments.

     <br><dt>( <var>opt</var> | <code>ARGP_KEY_ARG</code> )<small class="dots">...</small> <code>ARGP_KEY_END</code> <code>ARGP_KEY_SUCCESS</code><dd>All non-option arguments were successfully handled by a parser
function.  There may be multiple parser functions if multiple argp
parsers were combined.

     <br><dt>( <var>opt</var> | <code>ARGP_KEY_ARG</code> )<small class="dots">...</small> <code>ARGP_KEY_SUCCESS</code><dd>Some non-option argument went unrecognized.

     <p>This occurs when every parser function returns <code>ARGP_KEY_UNKNOWN</code>
for an argument, in which case parsing stops at that argument if
<var>arg_index</var> is a null pointer.  Otherwise an error occurs. 
</dl>

   <p>In all cases, if a non-null value for <var>arg_index</var> gets passed to
<code>argp_parse</code>, the index of the first unparsed command-line argument
is passed back in that value.

   <p>If an error occurs and is either detected by argp or because a parser
function returned an error value, each parser is called with
<code>ARGP_KEY_ERROR</code>.  No further calls are made, except the final call
with <code>ARGP_KEY_FINI</code>.

   </body></html>