| <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: <a rel="next" accesskey="n" href="Argp-Parsing-State.html#Argp-Parsing-State">Argp Parsing State</a>, |
| Up: <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>->argv |
| + </code><var>state</var><code>->next</code>. If success is returned for this key, and |
| <var>state</var><code>->next</code> is unchanged, all remaining arguments are |
| considered to have been consumed. Otherwise, the amount by which |
| <var>state</var><code>->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>->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>->argv + <var>state</var>->next; |
| num_remaining_args = <var>state</var>->argc - <var>state</var>->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> |
| |
