Node:argp description, Next:argp example, Previous:Processing command-line options, Up:Processing command-line options

argp description

This section will describe how to write a simple program that implements most of the standards mentioned above. It assumes some knowledge of advanced C data structures that we have not yet covered in this book; if you are confused, you might want to consult the chapter that discusses this material. (See More data types.) Note that we are only discussing the basics of argp in this chapter; to read more about this complicated and flexible facility of the GNU C Library, consult Parsing Program Options with Argp. Nevertheless, what you learn in this chapter may be all you need to develop a program that is compliant with GNU coding standards, with respect to command-line options.

The main interface to argp is the argp_parse function. Usually, the only argument-parsing code you will need in main is a call to this function. The first parameter it takes is of type const struct argp *argp, and specifies an ARGP structure (see below). (A value of zero is the same as a structure containing all zeros.) The second parameter is simply argc, the third simply argv. The fourth parameter is a set of flags that modify the parsing behaviour; setting this to zero usually doesn't hurt unless you're doing something fancy, and the same goes for the fifth parameter. The sixth parameter can be useful; in the example below, we use it to pass information from main to our function parse_opt, which does most of the work of initalizing internal variables (fields in the arguments structure) based on command-line options and arguments.

The argp_parse returns a value of type error_t: usually either 0 for success, ENOMEM if a memory allocation error occurred, or EINVAL if an unknown option or argument was met with.

For this example, we are using only the first four fields in ARGP, which are usually all that is needed. The rest of the fields will default to zero. The four fields are, in order:

1. OPTIONS: A pointer to a vector the elements of which are of type struct argp_option, which contains four fields. The vector elements specify which options this parser understands. If you assign your option structure by initializing the array as we do in this section's main example, unspecified fields will default to zero, and need not be specified. The whole vector may contain zero if there are no options at all. It should in any case be terminated by an entry with a zero in all fields (as we do by specifying the last item in the options vector to be {0} in the main example below.

   The four main argp_option structure fields are as follows. (We will ignore the fifth one, which is relatively unimportant and will simply default to zero if you do not specify it.)

   1. NAME: The name of this option's long option (may be zero). To specify multiple names for an option, follow it with additional entries, with the OPTION_ALIAS flag set.
   2. KEY: The integer key to pass to the PARSER function when parsing the current option; this is the same as the name of the current option's short option, if it is a printable ASCII character.
   3. ARG: The name of this option's argument, if any.
   4. FLAGS: Flags describing this option. You can specify multiple flags with logical OR (for example, OPTION_ARG_OPTIONAL | OPTION_ALIAS).

      Some of the available options are:

      • OPTION_ARG_OPTIONAL: The argument to the current option is optional.
      • OPTION_ALIAS: The current option is an alias for the previous option.
      • OPTION_HIDDEN: Don't show the current option in --help output.
   5. DOC: A documentation string for the current option; will be shown in --help output.
2. PARSER: A pointer to a function to be called by argp for each option parsed. It should return one of the following values:
   • 0: Success.
   • ARGP_ERR_UNKNOWN: The given key was not recognized.
   • An errno value indicating some other error. (See Usual file name errors.)

   The parser function takes the following arguments:

   1. KEY: An integer specifying which argument this is, taken from the KEY field in each argp_option structure, or else a key with a special meaning, such as one of the following:
      • ARGP_KEY_ARG: The current command-line argument is not an option.
      • ARGP_KEY_END: All command-line arguments have been parsed.
   2. ARG: The string value of the current command-line argument, or NULL if it has none.
   3. STATE: A pointer to an argp_state structure, containing information about the parsing state, such as the following fields:
      1. input: The same as the last parameter to argp_parse. We use this in the main code example below to pass information between the main and parse_opt functions.
      2. arg_num: The number of the current non-option argument being parsed.
3. ARGS_DOC: If non-zero, a string describing how the non-option arguments should look. It is only used to print the Usage: message. If it contains newlines, the strings separated by them are considered alternative usage patterns, and printed on separate lines (subsequent lines are preceded by or: rather than Usage:.
4. DOC: If non-zero, a descriptive string about this program. It will normally be printed before the options in a help message, but if you include a vertical tab character (\v), the part after the vertical tab will be printed following the options in the output to the --help option. Conventionally, the part before the options is just a short string that says what the program does, while the part afterwards is longer and describes the program in more detail.

There are also some utility functions associated with argp, such as argp_usage, which prints out the standard usage message. We use this function in the parse_opt function in the following example. See Functions For Use in Argp Parsers, for more of these utility functions.