Parsing Program Options with Argp

Argp is an interface for parsing unix-style argument vectors (see section Program Arguments).

Unlike the more common getopt interface, it provides many related convenience features in addition to parsing options, such as automatically producing output in response to `--help' and `--version' options (as defined by the GNU coding standards). Doing these things in argp results in a more consistent look for programs that use it, and makes less likely that implementors will neglect to implement them 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, which programs can easily use in conjunction with their own option parser. This results in less work for user programs (indeed, some may use only argument parsers exported by libraries, and have no options of their own), and more consistent option-parsing for the abstractions implemented by the library.

The header file `<argp.h>' should be included to use argp.

The argp_parse Function

The main interface to argp is the argp_parse function; often, a call to argp_parse is the only argument-parsing code needed in main (see section Program Arguments).

Function: error_t argp_parse (const struct argp *argp, int argc, char **argv, unsigned flags, int *arg_index, void *input)

The argp_parse function parses the arguments in argv, of length argc, using the argp parser argp (see section Specifying Argp Parsers); a value of zero is the same as a struct argp containing all zeros. flags is a set of flag bits that modify the parsing behavior (see section Flags for argp_parse). input is passed through to the argp parser argp, and has meaning defined by it; a typical usage is to pass a pointer to a structure which can be used for specifying parameters to the parser and passing back results from it.

Unless the ARGP_NO_EXIT or ARGP_NO_HELP flags are included in flags, calling argp_parse may result in the program exiting--for instance when an unknown option is encountered. See section Program Termination.

If arg_index is non-null, the index of the first unparsed option in argv is returned in it.

The return value is zero for successful parsing, or an error code (see section Error Codes) if an error was detected. Different argp parsers may return arbitrary error codes, but standard ones are ENOMEM if a memory allocation error occurred, or EINVAL if an unknown option or option argument was encountered.

Go to the first, previous, next, last section, table of contents.