GNU Info

(libc.info)Argp Helper Functions

---

Prev: Argp Parsing State Up: Argp Parser Functions

---

Enter node , (file) or (file)node

Functions For Use in Argp Parsers
.................................

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

 - Function: void argp_usage (const struct argp_state *STATE)
     Outputs 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)'.  Note: Argp Global Variables.

 - Function: void argp_error (const struct argp_state *STATE, const
          char *FMT, ...)
     Prints the printf format string FMT and following args, preceded
     by the program name and `:', and followed by a `Try ... --help'
     message, and terminates the program with an exit status of
     `argp_err_exit_status'.  Note: Argp Global Variables.

 - Function: void argp_failure (const struct argp_state *STATE, int
          STATUS, int ERRNUM, const char *FMT, ...)
     Similar to the standard gnu error-reporting function `error', this
     prints the program name and `:', the printf format string FMT, and
     the appropriate following args.  If it is non-zero, the standard
     unix error text for ERRNUM is printed.  If STATUS is non-zero, it
     terminates the program with that value as its exit status.

     The difference between `argp_failure' 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)
     Outputs a help message for the argp parser referred to by STATE,
     to STREAM.  The FLAGS argument determines what sort of help
     message is produced.  Note: Argp Help Flags.

   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 are passed to
`argp_parse'.  Note: Argp Flags.

   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, and for the
case where the program _doesn't_ terminate, calls to any of these
functions should be followed by code that returns the appropriate error
code:

     if (BAD ARGUMENT SYNTAX)
       {
          argp_usage (STATE);
          return EINVAL;
       }

If a parser function will _only_ be used when `ARGP_NO_EXIT' is not
set, the return may be omitted.