C Programming/GNU C Library Reference/argp.h

Next: Parsing of Suboptions, Previous: Parsing program options using, Up: Parsing Program Arguments   [Contents][Index]

Parsing Program Options with Argp
Argp is an interface for parsing unix-style argument vectors. See Program Arguments.

Argp provides features unavailable in the more commonly used  interface. These features include automatically producing output in response to the ‘ --help ’ and ‘ --version ’ options, as described in the GNU coding standards. Using argp makes it less likely that programmers will neglect to implement these additional options or keep them up to date.

Argp also provides the ability to merge several independently defined option parsers into one, mediating conflicts between them and making the result appear seamless. A library can export an argp option parser that user programs might employ in conjunction with their own option parsers, resulting in less work for the user programs. Some programs may use only argument parsers exported by libraries, thereby achieving consistent and efficient option-parsing for abstractions implemented by the libraries.

The header file  should be included to use argp.


 * The  Function
 * Argp Global Variables
 * Specifying Argp Parsers
 * Specifying Options in an Argp Parser
 * Argp Parser Functions
 * Combining Multiple Argp Parsers
 * Flags for
 * Customizing Argp Help Output
 * The  Function
 * Flags for the  Function
 * Argp Examples
 * Argp User Customization
 * Parsing of Suboptions Example

25.3.1 The Function
The main interface to argp is the  function. In many cases, calling  is the only argument-parsing code needed in. See Program Arguments.


 * Function: error_t argp_parse (const struct argp * argp, int argc , char ** argv , unsigned flags , int * arg_index , void * input )
 * Preliminary: | MT-Unsafe race:argpbuf locale env | AS-Unsafe heap i18n lock corrupt | AC-Unsafe mem lock corrupt | See POSIX Safety Concepts. The   function parses the arguments in argv, of length argc , using the argp parser argp . See Specifying Argp Parsers. Passing a null pointer for argp is the same as using a   containing all zeros.  flags is a set of flag bits that modify the parsing behavior. See Flags for  . input is passed through to the argp parser argp , and has meaning defined by argp . A typical usage is to pass a pointer to a structure which is used for specifying parameters to the parser and passing back the results.  Unless the   or   flags are included in flags , calling   may result in the program exiting. This behavior is true if an error is detected, or when an unknown option is encountered. See Program Termination.  If arg_index is non-null, the index of the first unparsed option in argv is returned as a value.  The return value is zero for successful parsing, or an error code (see Error Codes) if an error is detected. Different argp parsers may return arbitrary error codes, but the standard error codes are:   if a memory allocation error occurred, or   if an unknown option or option argument is encountered.

Next: Parsing of Suboptions, Previous: Parsing program options using, Up: Parsing Program Arguments   [Contents][Index]