Functions For Use in Argp Parsers

Argp provides a number of functions for the user of argp parser functions (see section Argp Parser Functions), mostly for producing error messages. These take as their first argument the state argument to the parser function (see section Argp Parsing State).

Function: void argp_usage (const struct argp_state *state)

Output the standard usage message for the argp parser referred to by state to state->err_stream and terminate the program with exit (argp_err_exit_status) (see section Argp Global Variables).

Function: void argp_error (const struct argp_state *state, const char *fmt, ...)

Print the printf format string fmt and following args, preceded by the program name and `:', and followed by a `Try ... --help' message, and terminate the program with an exit status of argp_err_exit_status (see section Argp Global Variables).

Function: void argp_failure (const struct argp_state *state, int status, int errnum, const char *fmt, ...)

Similarly to the standard gnu error-reporting function error, print the printf format string fmt and following args, preceded by the program name and `:', and followed by the standard unix error text for errnum if it is non-zero; then if status is non-zero, terminate the program with that as its exit status.

The difference between this function and argp_error is that argp_error is for parsing errors, whereas argp_failure is for other problems that occur during parsing but don't reflect a syntactic problem with the input--such as illegal values for options, bad phase of the moon, etc.

Function: void argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)

Output a help message for the argp parser referred to by state to stream. The flags argument determines what sort of help message is produced. See section Flags for the argp_help Function.

Error output is sent to state->err_stream, and the program name printed is state->name.

The output or program termination behavior of these functions may be suppressed if the ARGP_NO_EXIT or ARGP_NO_ERRS flags, respectively, were passed to argp_parse. See section Flags for argp_parse.

This behavior is useful if an argp parser is exported for use by other programs (e.g., by a library), and may be used in a context where it is not desirable to terminate the program in response to parsing errors. In argp parsers intended for such general use, calls to any of these functions should be followed by code return of an appropriate error code for the case where the program doesn't terminate; for example:

if (bad argument syntax)
  {
     argp_usage (state);
     return EINVAL;
  }

If it's known that a parser function will only be used when ARGP_NO_EXIT is not set, the return may be omitted.

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