2 Documentation for the argp argument parser
4 Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
5 This file is part of the GNU C Library.
6 Written by Miles Bader <miles@gnu.ai.mit.edu>.
8 The GNU C Library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public License as
10 published by the Free Software Foundation; either version 2 of the
11 License, or (at your option) any later version.
13 The GNU C Library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Library General Public License for more details.
18 You should have received a copy of the GNU Library General Public
19 License along with the GNU C Library; see the file COPYING.LIB. If not,
20 write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 Boston, MA 02111-1307, USA. */
24 @node Argp, Suboptions, Getopt, Parsing Program Arguments
26 @section Parsing Program Options with Argp
27 @cindex argp (program argument parser)
28 @cindex argument parsing with argp
29 @cindex option parsing with argp
31 @dfn{Argp} is an interface for parsing unix-style argument vectors
32 (@pxref{Program Arguments}).
34 Unlike the more common @code{getopt} interface, it provides many related
35 convenience features in addition to parsing options, such as
36 automatically producing output in response to @samp{--help} and
37 @samp{--version} options (as defined by the GNU coding standards).
38 Doing these things in argp results in a more consistent look for
39 programs that use it, and makes less likely that implementors will
40 neglect to implement them or keep them up-to-date.
42 Argp also provides the ability to merge several independently defined
43 option parsers into one, mediating conflicts between them, and making
44 the result appear seamless. A library can export an argp option parser,
45 which programs can easily use in conjunction with their own option
46 parser. This results in less work for user programs (indeed, some may
47 use only argument parsers exported by libraries, and have no options of
48 their own), and more consistent option-parsing for the abstractions
49 implemented by the library.
52 The header file @file{<argp.h>} should be included to use argp.
54 @subsection The @code{argp_parse} Function
56 The main interface to argp is the @code{argp_parse} function; often, a
57 call to @code{argp_parse} is the only argument-parsing code needed in
58 @code{main} (@pxref{Program Arguments}).
62 @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, @w{int @var{argc}, char **@var{argv}}, @w{unsigned @var{flags}}, @w{int *@var{arg_index}}, @w{void *@var{input}})
63 The @code{argp_parse} function parses the arguments in in @var{argv}, of
64 length @var{argc}, using the argp parser @var{argp} (@pxref{Argp
65 Parsers}); a value of zero is the same as a @code{struct argp}
66 containing all zeros. @var{flags} is a set of flag bits that modify the
67 parsing behavior (@pxref{Argp Flags}). @var{input} is passed through to
68 the argp parser @var{argp}, and has meaning defined by it; a typical
69 usage is to pass a pointer to a structure which can be used for
70 specifying parameters to the parser and passing back results from it.
72 Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
73 in @var{flags}, calling @code{argp_parse} may result in the program
74 exiting---for instance when an unknown option is encountered.
75 @xref{Program Termination}.
77 The return value is zero for successful parsing, or a unix error code
78 (@pxref{Error Codes}) if an error was detected. Different argp parsers
79 may return arbitrary error codes, but standard ones are @code{ENOMEM} if
80 a memory allocation error occurred, or @code{EINVAL} if an unknown option
81 or option argument was encountered.
85 * Globals: Argp Global Variables. Global argp parameters.
86 * Parsers: Argp Parsers. Defining parsers for use with @code{argp_parse}.
87 * Flags: Argp Flags. Flags that modify the behavior of @code{argp_parse}.
88 * Help: Argp Help. Printing help messages when not parsing.
89 * Examples: Argp Examples. Simple examples of programs using argp.
90 * Customization: Argp User Customization.
91 Users may control the @samp{--help} output format.
94 @node Argp Global Variables, Argp Parsers, , Argp
95 @subsection Argp Global Variables
97 These variables make it very easy for every user program to implement
98 the @samp{--version} option and provide a bug-reporting address in the
99 @samp{--help} output (which is implemented by argp regardless).
103 @deftypevar {const char *} argp_program_version
104 If defined or set by the user program to a non-zero value, then a
105 @samp{--version} option is added when parsing with @code{argp_parse}
106 (unless the @code{ARGP_NO_HELP} flag is used), which will print this
107 string followed by a newline and exit (unless the @code{ARGP_NO_EXIT}
113 @deftypevar {const char *} argp_program_bug_address
114 If defined or set by the user program to a non-zero value,
115 @code{argp_program_bug_address} should point to string that is the
116 bug-reporting address for the program. It will be printed at the end of
117 the standard output for the @samp{--help} option, embedded in a sentence
118 that says something like @samp{Report bugs to @var{address}.}.
124 @defvar argp_program_version_hook
125 If defined or set by the user program to a non-zero value, then a
126 @samp{--version} option is added when parsing with @code{argp_parse}
127 (unless the @code{ARGP_NO_HELP} flag is used), which calls this function
128 to print the version, and then exits with a status of 0 (unless the
129 @code{ARGP_NO_EXIT} flag is used). It should point to a function with
130 the following type signature:
133 void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
137 @xref{Argp Parsing State}, for an explanation of @var{state}.
139 This variable takes precedent over @code{argp_program_version}, and is
140 useful if a program has version information that cannot be easily
141 specified as a simple string.
146 @deftypevar error_t argp_err_exit_status
147 The exit status that argp will use when exiting due to a parsing error.
148 If not defined or set by the user program, this defaults to
149 @code{EX_USAGE} from @file{<sysexits.h>}.
152 @node Argp Parsers, Argp Flags, Argp Global Variables, Argp
153 @subsection Specifying Argp Parsers
155 The first argument to the @code{argp_parse} function is a pointer to a
156 @code{struct argp}, which known as an @dfn{argp parser}:
160 @deftp {Data Type} {struct argp}
161 This structure specifies how to parse a given set of options and
162 arguments, perhaps in conjunction with other argp parsers. It has the
166 @item const struct argp_option *options
167 A pointer to a vector of @code{argp_option} structures specifying which
168 options this argp parser understands; it may be zero if there are no
169 options at all. @xref{Argp Option Vectors}.
171 @item argp_parser_t parser
172 A pointer to a function that defines actions for this parser; it is
173 called for each option parsed, and at other well-defined points in the
174 parsing process. A value of zero is the same as a pointer to a
175 function that always returns @code{ARGP_ERR_UNKNOWN}.
176 @xref{Argp Parser Functions}.
178 @item const char *args_doc
179 If non-zero, a string describing what non-option arguments are wanted by
180 this parser; it is only used to print the @samp{Usage:} message. If it
181 contains newlines, the strings separated by them are considered
182 alternative usage patterns, and printed on separate lines (lines after
183 the first are prefix by @samp{ or: } instead of @samp{Usage:}).
185 @item const char *doc
186 If non-zero, a string containing extra text to be printed before and
187 after the options in a long help message, with the two sections
188 separated by a vertical tab (@code{'\v'}, @code{'\013'}) character. By
189 convention, the documentation before the options is just a short string
190 saying what the program does, and that afterwards is longer, describing
191 the behavior in more detail.
193 @item const struct argp_child *children
194 A pointer to a vector of @code{argp_children} structures specifying
195 additional argp parsers that should be combined with this one.
196 @xref{Argp Children}.
198 @item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input})
199 If non-zero, a pointer to a function to filter the output of help
200 messages. @xref{Argp Help Filtering}.
204 The @code{options}, @code{parser}, @code{args_doc}, and @code{doc}
205 fields are usually all that are needed. If an argp parser is defined as
206 an initialized C variable, only the used fields need be specified in in
207 the initializer---the rest will default to zero due to the way C
208 structure initialization works (this fact is exploited for most argp
209 structures, grouping the most-used fields near the beginning, so that
210 unused fields can simply be left unspecified).
213 * Options: Argp Option Vectors. Specifying options in an argp parser.
214 * Argp Parser Functions:: Defining actions for an argp parser.
215 * Children: Argp Children. Combining multiple argp parsers.
216 * Help Filtering: Argp Help Filtering. Customizing help output for an argp parser.
219 @node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
220 @subsection Specifying Options in an Argp Parser
222 The @code{options} field in a @code{struct argp} points to a vector of
223 @code{struct argp_option} structures, each of which specifies an option
224 that argp parser supports (actually, sometimes multiple entries may used
225 for a single option if it has many names). It should be terminated by
226 an entry with zero in all fields (note that when using an initialized C
227 array for options, writing @code{@{ 0 @}} is enough to achieve this).
231 @deftp {Data Type} {struct argp_option}
232 This structure specifies a single option that an argp parser
233 understands, and how to parse and document it. It has the following fields:
236 @item const char *name
237 The long name for this option, corresponding to the long option
238 @samp{--@var{name}}; this field can be zero if this option only has a
239 short name. To specify multiple names for an option, additional entries
240 may follow this one, with the @code{OPTION_ALIAS} flag set (@pxref{Argp
244 The integer key that is provided to the argp parser's parsing function
245 when this option is being parsed. Also, if @var{key} has a value that
246 is a printable @sc{ascii} character (i.e., @code{isascii (@var{key})} is
247 true), it @emph{also} specifies a short option @samp{-@var{char}}, where
248 @var{char} is the @sc{ascii} character with the code @var{key}.
250 @item const char *arg
251 If non-zero, this is the name of an argument associated with this
252 option, which must be provided (e.g., with the
253 @samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}}
254 syntaxes) unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp Option
255 Flags}) is set, in which case it @emph{may} be provided.
258 Flags associated with this option (some of which are referred to above).
259 @xref{Argp Option Flags}.
261 @item const char *doc
262 A documentation string for this option, for printing in help messages.
264 If both the @code{name} and @code{key} fields are zero, this string
265 will be printed out-dented from the normal option column, making it
266 useful as a group header (it will be the first thing printed in its
267 group); in this usage, it's conventional to end the string with a
271 The group this option is in.
273 In a long help message, options are sorted alphabetically within each
274 group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
275 -@var{m}, @dots{}, -2, -1. Every entry in an options array with this
276 field 0 will inherit the group number of the previous entry, or zero if
277 it's the first one, unless its a group header (@code{name} and
278 @code{key} fields both zero), in which case, the previous entry + 1 is
279 the default. Automagic options such as @samp{--help} are put into group
282 Note that because of C structure initialization rules, this field
283 often need not be specified, because 0 is the right value.
288 * Flags: Argp Option Flags. Flags for options.
291 @node Argp Option Flags, , , Argp Option Vectors
292 @subsubsection Flags for Argp Options
294 The following flags may be or'd together in the @code{flags} field of a
295 @code{struct argp_option}, and control various aspects of how that
296 option is parsed or displayed in help messages:
301 @item OPTION_ARG_OPTIONAL
302 The argument associated with this option is optional.
307 This option isn't displayed in any help messages.
312 This option is an alias for the closest previous non-alias option. This
313 means that it will be displayed in the same help entry, and will inherit
314 fields other than @code{name} and @code{key} from the aliased option.
319 This option isn't actually an option (and so should be ignored by the
320 actual option parser), but rather an arbitrary piece of documentation
321 that should be displayed in much the same manner as the options (known
322 as a @dfn{documentation option}).
324 If this flag is set, then the option @code{name} field is displayed
325 unmodified (e.g., no @samp{--} prefix is added) at the left-margin
326 (where a @emph{short} option would normally be displayed), and the
327 documentation string in the normal place. For purposes of sorting, any
328 leading whitespace and punctuation is ignored, except that if the first
329 non-whitespace character is not @samp{-}, this entry is displayed after
330 all options (and @code{OPTION_DOC} entries with a leading @samp{-}) in
335 @item OPTION_NO_USAGE
336 This option shouldn't be included in `long' usage messages (but is still
337 included in help messages). This is mainly intended for options that
338 are completely documented in an argp's @code{args_doc} field
339 (@pxref{Argp Parsers}), in which case including the option
340 in the generic usage list would be redundant.
342 For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
343 @samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
344 should probably be marked @code{OPTION_NO_USAGE}.
347 @node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
348 @subsection Argp Parser Functions
350 The function pointed to by the @code{parser} field in a @code{struct
351 argp} (@pxref{Argp Parsers}) defines what actions take place in response
352 to each option or argument that is parsed, and is also used as a hook,
353 to allow a parser to do something at certain other points during
357 Argp parser functions have the following type signature:
359 @cindex argp parser functions
361 error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
365 where the arguments are as follows:
369 For each option that is parsed, @var{parser} is called with a value of
370 @var{key} from that option's @code{key} field in the option vector
371 (@pxref{Argp Option Vectors}). @var{parser} is also called at other
372 times with special reserved keys, such as @code{ARGP_KEY_ARG} for
373 non-option arguments. @xref{Argp Special Keys}.
376 If @var{key} is an option, @var{arg} is the value given for it, or zero
377 if no value was specified. Only options that have a non-zero @code{arg}
378 field can ever have a value, and those must @emph{always} have a value,
379 unless the @code{OPTION_ARG_OPTIONAL} flag was specified (if the input
380 being parsed specifies a value for an option that doesn't allow one, an
381 error results before @var{parser} ever gets called).
383 If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option argument;
384 other special keys always have a zero @var{arg}.
387 @var{state} points to a @code{struct argp_state}, containing useful
388 information about the current parsing state for use by @var{parser}.
389 @xref{Argp Parsing State}.
392 When @var{parser} is called, it should perform whatever action is
393 appropriate for @var{key}, and return either @code{0} for success,
394 @code{ARGP_ERR_UNKNOWN}, if the value of @var{key} is not handled by
395 this parser function, or a unix error code if a real error occurred
396 (@pxref{Error Codes}).
400 @deftypevr Macro int ARGP_ERR_UNKNOWN
401 Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
402 @var{key} value they do not recognize, or for non-option arguments
403 (@code{@var{key} == ARGP_KEY_ARG}) that they do not which to handle.
407 A typical parser function uses a switch statement on @var{key}:
411 parse_opt (int key, char *arg, struct argp_state *state)
415 case @var{option_key}:
420 return ARGP_ERR_UNKNOWN;
427 * Keys: Argp Special Keys. Special values for the @var{key} argument.
428 * State: Argp Parsing State. What the @var{state} argument refers to.
429 * Functions: Argp Helper Functions. Functions to help during argp parsing.
432 @node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
433 @subsubsection Special Keys for Argp Parser Functions
435 In addition to key values corresponding to user options, the @var{key}
436 argument to argp parser functions may have a number of other special
437 values (@var{arg} and @var{state} refer to parser function arguments;
438 @pxref{Argp Parser Functions}):
444 This is not an option at all, but rather a command line argument, whose
445 value is pointed to by @var{arg}.
447 When there are multiple parser functions (due to argp parsers being
448 combined), it's impossible to know which one wants to handle an
449 argument, so each is called in turn, until one returns 0 or an error
450 other than @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one,
451 @code{argp_parse} immediately returns success, without parsing any more
454 Once a parser function returns success for this key, that fact is
455 recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be used.
456 @emph{However}, if while processing the argument, a parser function
457 decrements the @code{next} field of its @var{state} argument, the option
458 won't be considered processed; this is to allow you to actually modify
459 the argument (perhaps into an option), and have it processed again.
464 There are no more command line arguments at all.
468 @item ARGP_KEY_NO_ARGS
469 Because it's common to want to do some special processing if there
470 aren't any non-option args, parser functions are called with this key if
471 they didn't successfully process any non-option arguments. Called just
472 before @code{ARGP_KEY_END} (where more general validity checks on
473 previously parsed arguments can take place).
478 Passed in before any parsing is done. Afterwards, the values of each
479 element of the @code{child_input} field of @var{state}, if any, are
480 copied to each child's state to be the initial value of the @code{input}
481 when @emph{their} parsers are called.
485 @item ARGP_KEY_SUCCESS
486 Passed in when parsing has successfully been completed (even if there are
487 still arguments remaining).
492 Passed in if an error has occurred, and parsing terminated (in which case
493 a call with a key of @code{ARGP_KEY_SUCCESS} is never made).
498 The final key ever seen by any parser (even after
499 @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}). Any resources
500 allocated by @code{ARGP_KEY_INIT} may be freed here (although sometimes
501 certain resources allocated there are to be returned to the caller after
502 a successful parse; in that case, those particular resources can be
503 freed in the @code{ARGP_KEY_ERROR} case).
506 In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
507 functions, and @code{ARGP_KEY_FINI} the last (unless an error was
508 returned by the parser for @code{ARGP_KEY_INIT}). Other keys can occur
509 in one the following orders (@var{opt} refers to an arbitrary option
513 @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
514 The arguments being parsed contained no non-option arguments at all.
516 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
517 All non-option arguments were successfully handled by a parser function
518 (there may be multiple parser functions if multiple argp parsers were
521 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
522 Some non-option argument was unrecognized.
524 This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
525 for an argument, in which case parsing stops at that argument. If a
526 non-zero value for @var{arg_index} was passed to @code{argp_parse}, the
527 index of this argument is returned in it, otherwise an error occurs.
530 If an error occurs (either detected by argp, or because a parser
531 function returned an error value), then each parser is called with
532 @code{ARGP_KEY_ERROR}, and no further calls are made except the final
533 call with @code{ARGP_KEY_FINI}.
535 @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
536 @subsubsection Functions For Use in Argp Parsers
538 Argp provides a number of functions for the user of argp parser
539 functions (@pxref{Argp Parser Functions}), mostly for producing error
540 messages. These take as their first argument the @var{state} argument
541 to the parser function (@pxref{Argp Parsing State}).
543 @cindex usage messages, in argp
546 @deftypefun void argp_usage (const struct argp_state *@var{state})
547 Output the standard usage message for the argp parser referred to by
548 @var{state} to @code{@var{state}->err_stream} and terminate the program
549 with @code{exit (argp_err_exit_status)} (@pxref{Argp Global Variables}).
552 @cindex syntax error messages, in argp
555 @deftypefun void argp_error (const struct argp_state *@var{state}, @w{const char *@var{fmt}, @dots{}})
556 Print the printf format string @var{fmt} and following args, preceded by
557 the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
558 --help}} message, and terminate the program with an exit status of
559 @code{argp_err_exit_status} (@pxref{Argp Global Variables}).
562 @cindex error messages, in argp
565 @deftypefun void argp_failure (const struct argp_state *@var{state}, @w{int @var{status}, int @var{errnum},} @w{const char *@var{fmt}, @dots{}})
566 Similarly to the standard gnu error-reporting function @code{error},
567 print the printf format string @var{fmt} and following args, preceded by
568 the program name and @samp{:}, and followed by the standard unix error
569 text for @var{errnum} if it is non-zero; then if @var{status} is
570 non-zero, terminate the program with that as its exit status.
572 The difference between this function and @code{argp_error} is that
573 @code{argp_error} is for @emph{parsing errors}, whereas
574 @code{argp_failure} is for other problems that occur during parsing but
575 don't reflect a syntactic problem with the input---such as illegal
576 values for options, bad phase of the moon, etc.
581 @deftypefun void argp_state_help (const struct argp_state *@var{state}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}})
582 Output a help message for the argp parser referred to by @var{state} to
583 @var{stream}. The @var{flags} argument determines what sort of help
584 message is produced. @xref{Argp Help Flags}.
587 Error output is sent to @code{@var{state}->err_stream}, and the program
588 name printed is @code{@var{state}->name}.
590 The output or program termination behavior of these functions may be
591 suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags,
592 respectively, were passed to @code{argp_parse}. @xref{Argp Flags}.
594 This behavior is useful if an argp parser is exported for use by other
595 programs (e.g., by a library), and may be used in a context where it is
596 not desirable to terminate the program in response to parsing errors.
597 In argp parsers intended for such general use, calls to any of these
598 functions should be followed by code return of an appropriate error code
599 for the case where the program @emph{doesn't} terminate; for example:
602 if (@var{bad argument syntax})
604 argp_usage (@var{state});
610 If it's known that a parser function will only be used when
611 @code{ARGP_NO_EXIT} is not set, the return may be omitted.
613 @node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions
614 @subsubsection Argp Parsing State
616 The third argument to argp parser functions (@pxref{Argp Parser
617 Functions}) is a pointer to a @code{struct argp_state}, which contains
618 information about the state of the option parsing.
622 @deftp {Data Type} {struct argp_state}
623 This structure has the following fields, which may be modified as noted:
626 @item const struct argp *const root_argp
627 The top level argp parser being parsed. Note that this is often
628 @emph{not} the same @code{struct argp} passed into @code{argp_parse} by
629 the invoking program (@pxref{Argp}), but instead an internal argp parser
630 that contains options implemented by @code{argp_parse} itself (such as
635 The argument vector being parsed. May be modified.
638 The index in @code{argv} of the next argument to be parsed. May be modified.
640 One way to consume all remaining arguments in the input is to set
641 @code{@var{state}->next = @var{state}->argc} (perhaps after recording
642 the value of the @code{next} field to find the consumed arguments).
643 Also, you can cause the current option to be re-parsed by decrementing
644 this field, and then modifying
645 @code{@var{state}->argv[@var{state}->next]} to be the option that should
649 The flags supplied to @code{argp_parse}. May be modified, although some
650 flags may only take effect when @code{argp_parse} is first invoked.
653 @item unsigned arg_num
654 While calling a parsing function with the @var{key} argument
655 @code{ARGP_KEY_ARG}, this is the number of the current arg, starting at
656 0, and incremented after each such call returns. At all other times,
657 this is the number of such arguments that have been processed.
660 If non-zero, the index in @code{argv} of the first argument following a
661 special @samp{--} argument (which prevents anything following being
662 interpreted as an option). Only set once argument parsing has proceeded
666 An arbitrary pointer passed in from the caller of @code{argp_parse}, in
667 the @var{input} argument.
669 @item void **child_inputs
670 Values to pass to child parsers. This vector will be the same length as
671 the number of children in the current parser, and each child parser will
672 be given the value of @code{@var{state}->child_inputs[@var{i}]} as
673 @emph{its} @code{@var{state}->input} field, where @var{i} is the index
674 of the child in the this parser's @code{children} field. @xref{Argp
678 For the parser function's use. Initialized to 0, but otherwise ignored
682 The name used when printing messages. This is initialized to
683 @code{argv[0]}, or @code{program_invocation_name} if that is
686 @item FILE *err_stream
687 @itemx FILE *out_stream
688 Stdio streams used when argp prints something; error messages are
689 printed to @code{err_stream}, and all other output (such as
690 @samp{--help} output) to @code{out_stream}. These are initialized to
691 @code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}).
694 Private, for use by the argp implementation.
698 @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
699 @subsection Combining Multiple Argp Parsers
701 The @code{children} field in a @code{struct argp} allows other argp
702 parsers to be combined with the referencing one to parse a single set of
703 arguments. It should point to a vector of @code{struct argp_child},
704 terminated by an entry having a value of zero in the @code{argp} field.
706 Where conflicts between combined parsers arise (for instance, if two
707 specify an option with the same name), they are resolved in favor of
708 the parent argp parsers, or earlier argp parsers in the list of children.
712 @deftp {Data Type} {struct argp_child}
713 An entry in the list of subsidiary argp parsers pointed to by the
714 @code{children} field in a @code{struct argp}. The fields are as follows:
717 @item const struct argp *argp
718 The child argp parser, or zero to end the list.
721 Flags for this child.
723 @item const char *header
724 If non-zero, an optional header to be printed in help output before the
725 child options. As a side-effect, a non-zero value forces the child
726 options to be grouped together; to achieve this effect without actually
727 printing a header string, use a value of @code{""}. As with header
728 strings specified in an option entry, the value conventionally has
729 @samp{:} as the last character. @xref{Argp Option Vectors}.
732 Where to group the child options relative to the other (`consolidated')
733 options in the parent argp parser. The values are the same as the
734 @code{group} field in @code{struct argp_option} (@pxref{Argp Option
735 Vectors}), but all child-groupings follow parent options at a particular
736 group level. If both this field and @code{header} are zero, then the
737 child's options aren't grouped together at all, but rather merged with
738 the parent options (merging the child's grouping levels with the
743 @node Argp Flags, Argp Help, Argp Parsers, Argp
744 @subsection Flags for @code{argp_parse}
746 The default behavior of @code{argp_parse} is designed to be convenient
747 for the most common case of parsing program command line argument. To
748 modify these defaults, the following flags may be or'd together in the
749 @var{flags} argument to @code{argp_parse}:
754 @item ARGP_PARSE_ARGV0
755 Don't ignore the first element of the @var{argv} argument to
756 @code{argp_parse}. Normally (and always unless @code{ARGP_NO_ERRS} is
757 set) the first element of the argument vector is skipped for option
758 parsing purposes, as it corresponds to the program name in a command
764 Don't print error messages for unknown options to @code{stderr}; unless
765 this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
766 is used as the program name in the error messages. This flag implies
767 @code{ARGP_NO_EXIT} (on the assumption that silent exiting upon errors
773 Don't parse any non-option args. Normally non-option args are parsed by
774 calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the
775 actual arg as the value. This flag needn't normally be set, as the
776 normal behavior is to stop parsing as soon as some argument isn't
777 accepted by a parsing function. @xref{Argp Parser Functions}.
782 Parse options and arguments in the same order they occur on the command
783 line---normally they're rearranged so that all options come first
788 Don't provide the standard long option @samp{--help}, which ordinarily
789 causes usage and option help information to be output to @code{stdout},
790 and @code{exit (0)} called.
795 Don't exit on errors (they may still result in error messages).
800 Use the gnu getopt `long-only' rules for parsing arguments.
805 Turns off any message-printing/exiting options, specifically
806 @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
809 @node Argp Help Filtering, , Argp Children, Argp Parsers
811 @subsection Customizing Argp Help Output
813 The @code{help_filter} field in a a @code{struct argp} is a pointer to a
814 function to filter the text of help messages before displaying them.
815 They have a function signature like:
818 char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input})
822 where @var{key} is either a key from an option, in which case @var{text}
823 is that option's help text (@pxref{Argp Option Vectors}), or one of the
824 special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing
825 which other help text @var{text} is (@pxref{Argp Help Filter Keys}).
827 The function should return either @var{text}, if it should be used
828 as-is, a replacement string, which should be allocated using
829 @code{malloc}, and will be freed by argp, or zero, meaning `print
830 nothing'. The value of @var{text} supplied is @emph{after} any
831 translation has been done, so if any of the replacement text also needs
832 translation, that should be done by the filter function. @var{input} is
833 either the input supplied to @code{argp_parse}, or zero, if
834 @code{argp_help} was called directly by the user.
837 * Keys: Argp Help Filter Keys. Special @var{key} values for help filter functions.
840 @node Argp Help Filter Keys, , , Argp Help Filtering
841 @subsubsection Special Keys for Argp Help Filter Functions
843 The following special values may be passed to an argp help filter
844 function as the first argument, in addition to key values for user
845 options, and specify which help text the @var{text} argument contains:
850 @item ARGP_KEY_HELP_PRE_DOC
851 Help text preceding options.
855 @item ARGP_KEY_HELP_POST_DOC
856 Help text following options.
860 @item ARGP_KEY_HELP_HEADER
861 Option header string.
865 @item ARGP_KEY_HELP_EXTRA
866 After all other documentation; @var{text} is zero for this key.
870 @item ARGP_KEY_HELP_DUP_ARGS_NOTE
871 The explanatory note emitted when duplicate option arguments have been
876 @item ARGP_KEY_HELP_ARGS_DOC
877 The argument doc string (the @code{args_doc} field from the argp parser;
878 @pxref{Argp Parsers}).
881 @node Argp Help, Argp Examples, Argp Flags, Argp
882 @subsection The @code{argp_help} Function
884 Normally programs using argp need not worry too much about printing
885 argument-usage-type help messages, because the standard @samp{--help}
886 option is handled automatically by argp, and the typical error cases can
887 be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp
890 However, if it's desirable to print a standard help message in some
891 context other than parsing the program options, argp offers the
892 @code{argp_help} interface.
896 @deftypefun void argp_help (const struct argp *@var{argp}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}}, @w{char *@var{name}})
897 Output a help message for the argp parser @var{argp} to @var{stream}.
898 What sort of messages is printed is determined by @var{flags}.
900 Any options such as @samp{--help} that are implemented automatically by
901 argp itself will @emph{not} be present in the help output; for this
902 reason, it is better to use @code{argp_state_help} if calling from
903 within an argp parser function. @xref{Argp Helper Functions}.
907 * Flags: Argp Help Flags. Specifying what sort of help message to print.
910 @node Argp Help Flags, , , Argp Help
911 @subsection Flags for the @code{argp_help} Function
913 When calling @code{argp_help} (@pxref{Argp Help}), or
914 @code{argp_state_help} (@pxref{Argp Helper Functions}), exactly what is
915 output is determined by the @var{flags} argument, which should consist
916 of any of the following flags, or'd together:
919 @item ARGP_HELP_USAGE
920 A unix @samp{Usage:} message that explicitly lists all options.
922 @item ARGP_HELP_SHORT_USAGE
923 A unix @samp{Usage:} message that displays only an appropriate
924 placeholder to indicate where the options go; useful for showing
925 the non-option argument syntax.
928 A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
929 program name and @samp{--help}.
932 A verbose option help message that gives each option understood along
933 with its documentation string.
935 @item ARGP_HELP_PRE_DOC
936 The part of the argp parser doc string that precedes the verbose option help.
938 @item ARGP_HELP_POST_DOC
939 The part of the argp parser doc string that follows the verbose option help.
942 @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
944 @item ARGP_HELP_BUG_ADDR
945 A message saying where to report bugs for this program, if the
946 @code{argp_program_bug_address} variable contains one.
948 @item ARGP_HELP_LONG_ONLY
949 Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode.
952 The following flags are only understood when used with
953 @code{argp_state_help}, and control whether the function returns after
954 printing its output, or terminates the program:
957 @item ARGP_HELP_EXIT_ERR
958 Terminate the program with @code{exit (argp_err_exit_status)}.
960 @item ARGP_HELP_EXIT_OK
961 Terminate the program with @code{exit (0)}.
964 The following flags are combinations of the basic ones for printing
968 @item ARGP_HELP_STD_ERR
969 Assuming an error message for a parsing error has already printed,
970 prints a note on how to get help, and terminates the program with an
973 @item ARGP_HELP_STD_USAGE
974 Prints a standard usage message and terminates the program with an
975 error. This is used when no more specific error message is appropriate.
977 @item ARGP_HELP_STD_HELP
978 Prints the standard response for a @samp{--help} option, and terminates
979 the program successfully.
982 @node Argp Examples, Argp User Customization, Argp Help, Argp
983 @subsection Argp Examples
985 These example programs demonstrate the basic usage of argp.
988 * 1: Argp Example 1. A minimal program using argp.
989 * 2: Argp Example 2. A program using only default options.
990 * 3: Argp Example 3. A simple program with user options.
991 * 4: Argp Example 4. Combining multiple argp parsers.
994 @node Argp Example 1, Argp Example 2, , Argp Examples
995 @subsubsection A Minimal Program Using Argp
997 This is (probably) the smallest possible program that uses argp.
998 It won't do much except give an error messages and exit when there are any
999 arguments, and print a (rather pointless) message for @samp{--help}.
1002 @include argp-ex1.c.texi
1005 @node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples
1006 @subsubsection A Program Using Argp with Only Default Options
1008 This program doesn't use any options or arguments, but uses argp to be
1009 compliant with the GNU standard command line format.
1011 In addition to making sure no arguments are given, and implementing a
1012 @samp{--help} option, this example will have a @samp{--version} option,
1013 and will put the given documentation string and bug address in the
1014 @samp{--help} output, as per GNU standards.
1016 The variable @code{argp} contains the argument parser specification;
1017 adding fields to this structure is the way most parameters are passed to
1018 @code{argp_parse} (the first three fields are usually used, but not in
1019 this small program). There are also two global variables that argp
1020 knows about defined here, @code{argp_program_version} and
1021 @code{argp_program_bug_address} (they are global variables because they
1022 will almost always be constant for a given program, even if it uses
1023 different argument parsers for various tasks).
1026 @include argp-ex2.c.texi
1029 @node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples
1030 @subsubsection A Program Using Argp with User Options
1032 This program uses the same features as example 2, and adds user options
1035 We now use the first four fields in @code{argp} (@pxref{Argp Parsers}),
1036 and specifies @code{parse_opt} as the parser function (@pxref{Argp
1039 Note that in this example, @code{main} uses a structure to communicate
1040 with the @code{parse_opt} function, a pointer to which it passes in the
1041 @code{input} argument to @code{argp_parse} (@pxref{Argp}), and is
1042 retrieved by @code{parse_opt} through the @code{input} field in its
1043 @code{state} argument (@pxref{Argp Parsing State}). Of course, it's
1044 also possible to use global variables instead, but using a structure
1045 like this is somewhat more flexible and clean.
1048 @include argp-ex3.c.texi
1051 @node Argp Example 4, , Argp Example 3, Argp Examples
1052 @subsubsection A Program Using Multiple Combined Argp Parsers
1054 This program uses the same features as example 3, but has more options,
1055 and somewhat more structure in the @samp{--help} output. It also shows
1056 how you can `steal' the remainder of the input arguments past a certain
1057 point, for programs that accept a list of items, and the special
1058 @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no
1059 non-option arguments were supplied to the program (@pxref{Argp Special
1062 For structuring the help output, two features are used: @emph{headers},
1063 which are entries in the options vector (@pxref{Argp Option Vectors})
1064 with the first four fields being zero, and a two part documentation
1065 string (in the variable @code{doc}), which allows documentation both
1066 before and after the options (@pxref{Argp Parsers}); the
1067 two parts of @code{doc} are separated by a vertical-tab character
1068 (@code{'\v'}, or @code{'\013'}). By convention, the documentation
1069 before the options is just a short string saying what the program does,
1070 and that afterwards is longer, describing the behavior in more detail.
1071 All documentation strings are automatically filled for output, although
1072 newlines may be included to force a line break at a particular point.
1073 All documentation strings are also passed to the @code{gettext}
1074 function, for possible translation into the current locale.
1077 @include argp-ex4.c.texi
1080 @node Argp User Customization, , Argp Examples, Argp
1081 @subsection Argp User Customization
1083 @cindex ARGP_HELP_FMT environment variable
1084 The way formatting of argp @samp{--help} output may be controlled to
1085 some extent by a program's users, by setting the @code{ARGP_HELP_FMT}
1086 environment variable to a comma-separated list (whitespace is ignored)
1087 of the following tokens:
1092 Turn @dfn{duplicate-argument-mode} on or off. In duplicate argument
1093 mode, if an option which accepts an argument has multiple names, the
1094 argument is shown for each name; otherwise, it is only shown for the
1095 first long option, and a note is emitted later so the user knows that it
1096 applies to the other names as well. The default is @samp{no-dup-args},
1097 which is less consistent, but prettier.
1100 @item no-dup-args-note
1101 Enable or disable the note informing the user of suppressed option
1102 argument duplication. The default is @samp{dup-args-note}.
1104 @item short-opt-col=@var{n}
1105 Show the first short option in column @var{n} (default 2).
1107 @item long-opt-col=@var{n}
1108 Show the first long option in column @var{n} (default 6).
1110 @item doc-opt-col=@var{n}
1111 Show `documentation options' (@pxref{Argp Option Flags}) in column
1112 @var{n} (default 2).
1114 @item opt-doc-col=@var{n}
1115 Show the documentation for options starting in column @var{n} (default 29).
1117 @item header-col=@var{n}
1118 Indent group headers (which document groups of options) to column
1119 @var{n} (default 1).
1121 @item usage-indent=@var{n}
1122 Indent continuation lines in @samp{Usage:} messages to column @var{n}
1125 @item rmargin=@var{n}
1126 Word wrap help output at or before column @var{n} (default 79).