Fix typos.
[kopensolaris-gnu/glibc.git] / manual / argp.texi
1 @node Argp, Suboptions, Getopt, Parsing Program Arguments
2 @need 5000
3 @section Parsing Program Options with Argp
4 @cindex argp (program argument parser)
5 @cindex argument parsing with argp
6 @cindex option parsing with argp
7
8 @dfn{Argp} is an interface for parsing unix-style argument vectors.
9 @xref{Program Arguments}.
10
11 Argp provides features unavailable in the more commonly used
12 @code{getopt} interface.  These features include automatically producing
13 output in response to the @samp{--help} and @samp{--version} options, as
14 described in the GNU coding standards.  Using argp makes it less likely
15 that programmers will neglect to implement these additional options or
16 keep them up to date.
17
18 Argp also provides the ability to merge several independently defined
19 option parsers into one, mediating conflicts between them and making the
20 result appear seamless.  A library can export an argp option parser that
21 user programs might employ in conjunction with their own option parsers,
22 resulting in less work for the user programs.  Some programs may use only
23 argument parsers exported by libraries, thereby achieving consistent and
24 efficient option-parsing for abstractions implemented by the libraries.
25
26 @pindex argp.h
27 The header file @file{<argp.h>} should be included to use argp.
28
29 @subsection The @code{argp_parse} Function
30
31 The main interface to argp is the @code{argp_parse} function.  In many
32 cases, calling @code{argp_parse} is the only argument-parsing code
33 needed in @code{main}.
34 @xref{Program Arguments}.
35
36 @comment argp.h
37 @comment GNU
38 @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input})
39 The @code{argp_parse} function parses the arguments in @var{argv}, of
40 length @var{argc}, using the argp parser @var{argp}.  @xref{Argp
41 Parsers}.
42
43 A value of zero is the same as a @code{struct argp}containing all
44 zeros.  @var{flags} is a set of flag bits that modify the parsing
45 behavior.  @xref{Argp Flags}.  @var{input} is passed through to the argp
46 parser @var{argp}, and has meaning defined by @var{argp}.  A typical
47 usage is to pass a pointer to a structure which is used for specifying
48 parameters to the parser and passing back the results.
49
50 Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
51 in @var{flags}, calling @code{argp_parse} may result in the program
52 exiting.  This behavior is true if an error is detected, or when an
53 unknown option is encountered.  @xref{Program Termination}.
54
55 If @var{arg_index} is non-null, the index of the first unparsed option
56 in @var{argv} is returned as a value.
57
58 The return value is zero for successful parsing, or an error code
59 (@pxref{Error Codes}) if an error is detected.  Different argp parsers
60 may return arbitrary error codes, but the standard error codes are:
61 @code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if
62 an unknown option or option argument is encountered.
63 @end deftypefun
64
65 @menu
66 * Globals: Argp Global Variables.  Global argp parameters.
67 * Parsers: Argp Parsers.        Defining parsers for use with @code{argp_parse}.
68 * Flags: Argp Flags.            Flags that modify the behavior of @code{argp_parse}.
69 * Help: Argp Help.              Printing help messages when not parsing.
70 * Examples: Argp Examples.      Simple examples of programs using argp.
71 * Customization: Argp User Customization.
72                                 Users may control the @samp{--help} output format.
73 @end menu
74
75 @node Argp Global Variables, Argp Parsers, , Argp
76 @subsection Argp Global Variables
77
78 These variables make it easy for user programs to implement the
79 @samp{--version} option and provide a bug-reporting address in the
80 @samp{--help} output.  These are implemented in argp by default.
81
82 @comment argp.h
83 @comment GNU
84 @deftypevar {const char *} argp_program_version
85 If defined or set by the user program to a non-zero value, then a
86 @samp{--version} option is added when parsing with @code{argp_parse},
87 which will print the @samp{--version} string followed by a newline and
88 exit.  The exception to this is if the @code{ARGP_NO_EXIT} flag is used.
89 @end deftypevar
90
91 @comment argp.h
92 @comment GNU
93 @deftypevar {const char *} argp_program_bug_address
94 If defined or set by the user program to a non-zero value,
95 @code{argp_program_bug_address} should point to a string that will be
96 printed at the end of the standard output for the @samp{--help} option,
97 embedded in a sentence that says @samp{Report bugs to @var{address}.}.
98 @end deftypevar
99
100 @need 1500
101 @comment argp.h
102 @comment GNU
103 @defvar argp_program_version_hook
104 If defined or set by the user program to a non-zero value, a
105 @samp{--version} option is added when parsing with @code{arg_parse},
106 which prints the program version and exits with a status of zero.  This
107 is not the case if the @code{ARGP_NO_HELP} flag is used.  If the
108 @code{ARGP_NO_EXIT} flag is set, the exit behavior of the program is
109 suppressed or modified, as when the argp parser is going to be used by
110 other programs.
111
112 It should point to a function with this type of signature:
113
114 @smallexample
115 void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
116 @end smallexample
117
118 @noindent
119 @xref{Argp Parsing State}, for an explanation of @var{state}.
120
121 This variable takes precedence over @code{argp_program_version}, and is
122 useful if a program has version information not easily expressed in a
123 simple string.
124 @end defvar
125
126 @comment argp.h
127 @comment GNU
128 @deftypevar error_t argp_err_exit_status
129 This is the exit status used when argp exits due to a parsing error.  If
130 not defined or set by the user program, this defaults to:
131 @code{EX_USAGE} from @file{<sysexits.h>}.
132 @end deftypevar
133
134 @node Argp Parsers, Argp Flags, Argp Global Variables, Argp
135 @subsection Specifying Argp Parsers
136
137 The first argument to the @code{argp_parse} function is a pointer to a
138 @code{struct argp}, which is known as an @dfn{argp parser}:
139
140 @comment argp.h
141 @comment GNU
142 @deftp {Data Type} {struct argp}
143 This structure specifies how to parse a given set of options and
144 arguments, perhaps in conjunction with other argp parsers.  It has the
145 following fields:
146
147 @table @code
148 @item const struct argp_option *options
149 A pointer to a vector of @code{argp_option} structures specifying which
150 options this argp parser understands; it may be zero if there are no
151 options at all.  @xref{Argp Option Vectors}.
152
153 @item argp_parser_t parser
154 A pointer to a function that defines actions for this parser; it is
155 called for each option parsed, and at other well-defined points in the
156 parsing process.  A value of zero is the same as a pointer to a function
157 that always returns @code{ARGP_ERR_UNKNOWN}.  @xref{Argp Parser
158 Functions}.
159
160 @item const char *args_doc
161 If non-zero, a string describing what non-option arguments are called by
162 this parser.  This is only used to print the @samp{Usage:} message.  If
163 it contains newlines, the strings separated by them are considered
164 alternative usage patterns and printed on separate lines.  Lines after
165 the first are prefixed by @samp{ or: } instead of @samp{Usage:}.
166
167 @item const char *doc
168 If non-zero, a string containing extra text to be printed before and
169 after the options in a long help message, with the two sections
170 separated by a vertical tab (@code{'\v'}, @code{'\013'}) character.  By
171 convention, the documentation before the options is just a short string
172 explaining what the program does.  Documentation printed after the
173 options describe behavior in more detail.
174
175 @item const struct argp_child *children
176 A pointer to a vector of @code{argp_children} structures.  This pointer
177 specifies which additional argp parsers should be combined with this
178 one.  @xref{Argp Children}.
179
180 @item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input})
181 If non-zero, a pointer to a function that filters the output of help
182 messages.  @xref{Argp Help Filtering}.
183
184 @item const char *argp_domain
185 If non-zero, the strings used in the argp library are translated using
186 the domain described by this string.  If zero, the current default domain
187 is used.
188
189 @end table
190 @end deftp
191
192 Of the above group, @code{options}, @code{parser}, @code{args_doc}, and
193 the @code{doc} fields are usually all that are needed.  If an argp
194 parser is defined as an initialized C variable, only the fields used
195 need be specified in the initializer.  The rest will default to zero due
196 to the way C structure initialization works.  This design is exploited in
197 most argp structures; the most-used fields are grouped near the
198 beginning, the unused fields left unspecified.
199
200 @menu
201 * Options: Argp Option Vectors.   Specifying options in an argp parser.
202 * Argp Parser Functions::         Defining actions for an argp parser.
203 * Children: Argp Children.        Combining multiple argp parsers.
204 * Help Filtering: Argp Help Filtering.  Customizing help output for an argp parser.
205 @end menu
206
207 @node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
208 @subsection Specifying Options in an Argp Parser
209
210 The @code{options} field in a @code{struct argp} points to a vector of
211 @code{struct argp_option} structures, each of which specifies an option
212 that the argp parser supports.  Multiple entries may be used for a single
213 option provided it has multiple names.  This should be terminated by an
214 entry with zero in all fields.  Note that when using an initialized C
215 array for options, writing @code{@{ 0 @}} is enough to achieve this.
216
217 @comment argp.h
218 @comment GNU
219 @deftp {Data Type} {struct argp_option}
220 This structure specifies a single option that an argp parser
221 understands, as well as how to parse and document that option.  It has
222 the following fields:
223
224 @table @code
225 @item const char *name
226 The long name for this option, corresponding to the long option
227 @samp{--@var{name}}; this field may be zero if this option @emph{only}
228 has a short name.  To specify multiple names for an option, additional
229 entries may follow this one, with the @code{OPTION_ALIAS} flag
230 set.  @xref{Argp Option Flags}.
231
232 @item int key
233 The integer key provided by the current option to the option parser.  If
234 @var{key} has a value that is a printable @sc{ascii} character (i.e.,
235 @code{isascii (@var{key})} is true), it @emph{also} specifies a short
236 option @samp{-@var{char}}, where @var{char} is the @sc{ascii} character
237 with the code @var{key}.
238
239 @item const char *arg
240 If non-zero, this is the name of an argument associated with this
241 option, which must be provided (e.g., with the
242 @samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}}
243 syntaxes), unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp
244 Option Flags}) is set, in which case it @emph{may} be provided.
245
246 @item int flags
247 Flags associated with this option, some of which are referred to above.
248 @xref{Argp Option Flags}.
249
250 @item const char *doc
251 A documentation string for this option, for printing in help messages.
252
253 If both the @code{name} and @code{key} fields are zero, this string
254 will be printed tabbed left from the normal option column, making it
255 useful as a group header.  This will be the first thing printed in its
256 group.  In this usage, it's conventional to end the string with a
257 @samp{:} character.
258
259 @item int group
260 Group identity for this option.
261
262 In a long help message, options are sorted alphabetically within each
263 group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
264 @minus{}@var{m}, @dots{}, @minus{}2, @minus{}1.
265
266 Every entry in an options array with this field 0 will inherit the group
267 number of the previous entry, or zero if it's the first one.  If it's a
268 group header with @code{name} and @code{key} fields both zero, the
269 previous entry + 1 is the default.  Automagic options such as
270 @samp{--help} are put into group @minus{}1.
271
272 Note that because of C structure initialization rules, this field often
273 need not be specified, because 0 is the correct value.
274 @end table
275 @end deftp
276
277
278 @menu
279 * Flags: Argp Option Flags.     Flags for options.
280 @end menu
281
282 @node Argp Option Flags, , , Argp Option Vectors
283 @subsubsection Flags for Argp Options
284
285 The following flags may be or'd together in the @code{flags} field of a
286 @code{struct argp_option}.  These flags control various aspects of how
287 that option is parsed or displayed in help messages:
288
289
290 @vtable @code
291 @comment argp.h
292 @comment GNU
293 @item OPTION_ARG_OPTIONAL
294 The argument associated with this option is optional.
295
296 @comment argp.h
297 @comment GNU
298 @item OPTION_HIDDEN
299 This option isn't displayed in any help messages.
300
301 @comment argp.h
302 @comment GNU
303 @item OPTION_ALIAS
304 This option is an alias for the closest previous non-alias option.  This
305 means that it will be displayed in the same help entry, and will inherit
306 fields other than @code{name} and @code{key} from the option being
307 aliased.
308
309
310 @comment argp.h
311 @comment GNU
312 @item OPTION_DOC
313 This option isn't actually an option and should be ignored by the actual
314 option parser.  It is an arbitrary section of documentation that should
315 be displayed in much the same manner as the options.  This is known as a
316 @dfn{documentation option}.
317
318 If this flag is set, then the option @code{name} field is displayed
319 unmodified (e.g., no @samp{--} prefix is added) at the left-margin where
320 a @emph{short} option would normally be displayed, and this
321 documentation string is left in it's usual place.  For purposes of
322 sorting, any leading whitespace and punctuation is ignored, unless the
323 first non-whitespace character is @samp{-}.  This entry is displayed
324 after all options, after @code{OPTION_DOC} entries with a leading
325 @samp{-}, in the same group.
326
327 @comment argp.h
328 @comment GNU
329 @item OPTION_NO_USAGE
330 This option shouldn't be included in `long' usage messages, but should
331 still be included in other help messages.  This is intended for options
332 that are completely documented in an argp's @code{args_doc}
333 field.  @xref{Argp Parsers}.  Including this option in the generic usage
334 list would be redundant, and should be avoided.
335
336 For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
337 @samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
338 should probably be marked @code{OPTION_NO_USAGE}.
339 @end vtable
340
341 @node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
342 @subsection Argp Parser Functions
343
344 The function pointed to by the @code{parser} field in a @code{struct
345 argp} (@pxref{Argp Parsers}) defines what actions take place in response
346 to each option or argument parsed.  It is also used as a hook, allowing a
347 parser to perform tasks at certain other points during parsing.
348
349 @need 2000
350 Argp parser functions have the following type signature:
351
352 @cindex argp parser functions
353 @smallexample
354 error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
355 @end smallexample
356
357 @noindent
358 where the arguments are as follows:
359
360 @table @var
361 @item key
362 For each option that is parsed, @var{parser} is called with a value of
363 @var{key} from that option's @code{key} field in the option
364 vector.  @xref{Argp Option Vectors}.  @var{parser} is also called at
365 other times with special reserved keys, such as @code{ARGP_KEY_ARG} for
366 non-option arguments.  @xref{Argp Special Keys}.
367
368 @item arg
369 If @var{key} is an option, @var{arg} is its given value.  This defaults
370 to zero if no value is specified.  Only options that have a non-zero
371 @code{arg} field can ever have a value.  These must @emph{always} have a
372 value unless the @code{OPTION_ARG_OPTIONAL} flag is specified.  If the
373 input being parsed specifies a value for an option that doesn't allow
374 one, an error results before @var{parser} ever gets called.
375
376 If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option
377 argument.  Other special keys always have a zero @var{arg}.
378
379 @item state
380 @var{state} points to a @code{struct argp_state}, containing useful
381 information about the current parsing state for use by
382 @var{parser}.  @xref{Argp Parsing State}.
383 @end table
384
385 When @var{parser} is called, it should perform whatever action is
386 appropriate for @var{key}, and return @code{0} for success,
387 @code{ARGP_ERR_UNKNOWN} if the value of @var{key} is not handled by this
388 parser function, or a unix error code if a real error
389 occurred.  @xref{Error Codes}.
390
391 @comment argp.h
392 @comment GNU
393 @deftypevr Macro int ARGP_ERR_UNKNOWN
394 Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
395 @var{key} value they do not recognize, or for non-option arguments
396 (@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle.
397 @end deftypevr
398
399 @need 3000
400 A typical parser function uses a switch statement on @var{key}:
401
402 @smallexample
403 error_t
404 parse_opt (int key, char *arg, struct argp_state *state)
405 @{
406   switch (key)
407     @{
408     case @var{option_key}:
409       @var{action}
410       break;
411     @dots{}
412     default:
413       return ARGP_ERR_UNKNOWN;
414     @}
415   return 0;
416 @}
417 @end smallexample
418
419 @menu
420 * Keys: Argp Special Keys.           Special values for the @var{key} argument.
421 * State: Argp Parsing State.         What the @var{state} argument refers to.
422 * Functions: Argp Helper Functions.  Functions to help during argp parsing.
423 @end menu
424
425 @node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
426 @subsubsection Special Keys for Argp Parser Functions
427
428 In addition to key values corresponding to user options, the @var{key}
429 argument to argp parser functions may have a number of other special
430 values.  In the following example @var{arg} and @var{state} refer to
431 parser function arguments.  @xref{Argp Parser Functions}.
432
433 @vtable @code
434 @comment argp.h
435 @comment GNU
436 @item ARGP_KEY_ARG
437 This is not an option at all, but rather a command line argument, whose
438 value is pointed to by @var{arg}.
439
440 When there are multiple parser functions in play due to argp parsers
441 being combined, it's impossible to know which one will handle a specific
442 argument.  Each is called until one returns 0 or an error other than
443 @code{ARGP_ERR_UNKNOWN}; if an argument is not handled,
444 @code{argp_parse} immediately returns success, without parsing any more
445 arguments.
446
447 Once a parser function returns success for this key, that fact is
448 recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be
449 used.  @emph{However}, if while processing the argument a parser function
450 decrements the @code{next} field of its @var{state} argument, the option
451 won't be considered processed; this is to allow you to actually modify
452 the argument, perhaps into an option, and have it processed again.
453
454 @comment argp.h
455 @comment GNU
456 @item ARGP_KEY_ARGS
457 If a parser function returns @code{ARGP_ERR_UNKNOWN} for
458 @code{ARGP_KEY_ARG}, it is immediately called again with the key
459 @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
460 convenient for consuming all remaining arguments.  @var{arg} is 0, and
461 the tail of the argument vector may be found at @code{@var{state}->argv
462 + @var{state}->next}.  If success is returned for this key, and
463 @code{@var{state}->next} is unchanged, all remaining arguments are
464 considered to have been consumed.  Otherwise, the amount by which
465 @code{@var{state}->next} has been adjusted indicates how many were used.
466 Here's an example that uses both, for different args:
467
468
469 @smallexample
470 ...
471 case ARGP_KEY_ARG:
472   if (@var{state}->arg_num == 0)
473     /* First argument */
474     first_arg = @var{arg};
475   else
476     /* Let the next case parse it.  */
477     return ARGP_KEY_UNKNOWN;
478   break;
479 case ARGP_KEY_ARGS:
480   remaining_args = @var{state}->argv + @var{state}->next;
481   num_remaining_args = @var{state}->argc - @var{state}->next;
482   break;
483 @end smallexample
484
485 @comment argp.h
486 @comment GNU
487 @item ARGP_KEY_END
488 This indicates that there are no more command line arguments.  Parser
489 functions are called in a different order, children first.  This allows
490 each parser to clean up its state for the parent.
491
492 @comment argp.h
493 @comment GNU
494 @item ARGP_KEY_NO_ARGS
495 Because it's common to do some special processing if there aren't any
496 non-option args, parser functions are called with this key if they
497 didn't successfully process any non-option arguments.  This is called
498 just before @code{ARGP_KEY_END}, where more general validity checks on
499 previously parsed arguments take place.
500
501 @comment argp.h
502 @comment GNU
503 @item ARGP_KEY_INIT
504 This is passed in before any parsing is done.  Afterwards, the values of
505 each element of the @code{child_input} field of @var{state}, if any, are
506 copied to each child's state to be the initial value of the @code{input}
507 when @emph{their} parsers are called.
508
509 @comment argp.h
510 @comment GNU
511 @item ARGP_KEY_SUCCESS
512 Passed in when parsing has successfully been completed, even if
513 arguments remain.
514
515 @comment argp.h
516 @comment GNU
517 @item ARGP_KEY_ERROR
518 Passed in if an error has occurred and parsing is terminated.  In this
519 case a call with a key of @code{ARGP_KEY_SUCCESS} is never made.
520
521 @comment argp.h
522 @comment GNU
523 @item ARGP_KEY_FINI
524 The final key ever seen by any parser, even after
525 @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}.  Any resources
526 allocated by @code{ARGP_KEY_INIT} may be freed here.  At times, certain
527 resources allocated are to be returned to the caller after a successful
528 parse.  In that case, those particular resources can be freed in the
529 @code{ARGP_KEY_ERROR} case.
530 @end vtable
531
532 In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
533 functions, and @code{ARGP_KEY_FINI} the last, unless an error was
534 returned by the parser for @code{ARGP_KEY_INIT}.  Other keys can occur
535 in one the following orders.  @var{opt} refers to an arbitrary option
536 key:
537
538 @table @asis
539 @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
540 The arguments being parsed did not contain any non-option arguments.
541
542 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
543 All non-option arguments were successfully handled by a parser
544 function.  There may be multiple parser functions if multiple argp
545 parsers were combined.
546
547 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
548 Some non-option argument went unrecognized.
549
550 This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
551 for an argument, in which case parsing stops at that argument if
552 @var{arg_index} is a null pointer.  Otherwise an error occurs.
553 @end table
554
555 In all cases, if a non-null value for @var{arg_index} gets passed to
556 @code{argp_parse}, the index of the first unparsed command-line argument
557 is passed back in that value.
558
559 If an error occurs and is either detected by argp or because a parser
560 function returned an error value, each parser is called with
561 @code{ARGP_KEY_ERROR}.  No further calls are made, except the final call
562 with @code{ARGP_KEY_FINI}.
563
564 @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
565 @subsubsection Functions For Use in Argp Parsers
566
567 Argp provides a number of functions available to the user of argp
568 (@pxref{Argp Parser Functions}), mostly for producing error messages.
569 These take as their first argument the @var{state} argument to the
570 parser function.  @xref{Argp Parsing State}.
571
572
573 @cindex usage messages, in argp
574 @comment argp.h
575 @comment GNU
576 @deftypefun void argp_usage (const struct argp_state *@var{state})
577 Outputs the standard usage message for the argp parser referred to by
578 @var{state} to @code{@var{state}->err_stream} and terminate the program
579 with @code{exit (argp_err_exit_status)}.  @xref{Argp Global Variables}.
580 @end deftypefun
581
582 @cindex syntax error messages, in argp
583 @comment argp.h
584 @comment GNU
585 @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{})
586 Prints the printf format string @var{fmt} and following args, preceded
587 by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
588 --help}} message, and terminates the program with an exit status of
589 @code{argp_err_exit_status}.  @xref{Argp Global Variables}.
590 @end deftypefun
591
592 @cindex error messages, in argp
593 @comment argp.h
594 @comment GNU
595 @deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{})
596 Similar to the standard gnu error-reporting function @code{error}, this
597 prints the program name and @samp{:}, the printf format string
598 @var{fmt}, and the appropriate following args.  If it is non-zero, the
599 standard unix error text for @var{errnum} is printed.  If @var{status} is
600 non-zero, it terminates the program with that value as its exit status.
601
602 The difference between @code{argp_failure} and @code{argp_error} is that
603 @code{argp_error} is for @emph{parsing errors}, whereas
604 @code{argp_failure} is for other problems that occur during parsing but
605 don't reflect a syntactic problem with the input, such as illegal values
606 for options, bad phase of the moon, etc.
607 @end deftypefun
608
609 @comment argp.h
610 @comment GNU
611 @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags})
612 Outputs a help message for the argp parser referred to by @var{state},
613 to @var{stream}.  The @var{flags} argument determines what sort of help
614 message is produced.  @xref{Argp Help Flags}.
615 @end deftypefun
616
617 Error output is sent to @code{@var{state}->err_stream}, and the program
618 name printed is @code{@var{state}->name}.
619
620 The output or program termination behavior of these functions may be
621 suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags are
622 passed to @code{argp_parse}.  @xref{Argp Flags}.
623
624 This behavior is useful if an argp parser is exported for use by other
625 programs (e.g., by a library), and may be used in a context where it is
626 not desirable to terminate the program in response to parsing errors.  In
627 argp parsers intended for such general use, and for the case where the
628 program @emph{doesn't} terminate, calls to any of these functions should
629 be followed by code that returns the appropriate error code:
630
631 @smallexample
632 if (@var{bad argument syntax})
633   @{
634      argp_usage (@var{state});
635      return EINVAL;
636   @}
637 @end smallexample
638
639 @noindent
640 If a parser function will @emph{only} be used when @code{ARGP_NO_EXIT}
641 is not set, the return may be omitted.
642
643 @node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions
644 @subsubsection Argp Parsing State
645
646 The third argument to argp parser functions (@pxref{Argp Parser
647 Functions}) is a pointer to a @code{struct argp_state}, which contains
648 information about the state of the option parsing.
649
650 @comment argp.h
651 @comment GNU
652 @deftp {Data Type} {struct argp_state}
653 This structure has the following fields, which may be modified as noted:
654
655 @table @code
656 @item const struct argp *const root_argp
657 The top level argp parser being parsed.  Note that this is often
658 @emph{not} the same @code{struct argp} passed into @code{argp_parse} by
659 the invoking program.  @xref{Argp}.  It is an internal argp parser that
660 contains options implemented by @code{argp_parse} itself, such as
661 @samp{--help}.
662
663 @item int argc
664 @itemx char **argv
665 The argument vector being parsed.  This may be modified.
666
667 @item int next
668 The index in @code{argv} of the next argument to be parsed.  This may be
669 modified.
670
671 One way to consume all remaining arguments in the input is to set
672 @code{@var{state}->next = @var{state}->argc}, perhaps after recording
673 the value of the @code{next} field to find the consumed arguments.  The
674 current option can be re-parsed immediately by decrementing this field,
675 then modifying @code{@var{state}->argv[@var{state}->next]} to reflect
676 the option that should be reexamined.
677
678 @item unsigned flags
679 The flags supplied to @code{argp_parse}.  These may be modified, although
680 some flags may only take effect when @code{argp_parse} is first
681 invoked.  @xref{Argp Flags}.
682
683 @item unsigned arg_num
684 While calling a parsing function with the @var{key} argument
685 @code{ARGP_KEY_ARG}, this represents the number of the current arg,
686 starting at 0.  It is incremented after each @code{ARGP_KEY_ARG} call
687 returns.  At all other times, this is the number of @code{ARGP_KEY_ARG}
688 arguments that have been processed.
689
690 @item int quoted
691 If non-zero, the index in @code{argv} of the first argument following a
692 special @samp{--} argument.  This prevents anything that follows from
693 being interpreted as an option.  It is only set after argument parsing
694 has proceeded past this point.
695
696 @item void *input
697 An arbitrary pointer passed in from the caller of @code{argp_parse}, in
698 the @var{input} argument.
699
700 @item void **child_inputs
701 These are values that will be passed to child parsers.  This vector will
702 be the same length as the number of children in the current parser.  Each
703 child parser will be given the value of
704 @code{@var{state}->child_inputs[@var{i}]} as @emph{its}
705 @code{@var{state}->input} field, where @var{i} is the index of the child
706 in the this parser's @code{children} field.  @xref{Argp Children}.
707
708 @item void *hook
709 For the parser function's use.  Initialized to 0, but otherwise ignored
710 by argp.
711
712 @item char *name
713 The name used when printing messages.  This is initialized to
714 @code{argv[0]}, or @code{program_invocation_name} if @code{argv[0]} is
715 unavailable.
716
717 @item FILE *err_stream
718 @itemx FILE *out_stream
719 The stdio streams used when argp prints.  Error messages are printed to
720 @code{err_stream}, all other output, such as @samp{--help} output) to
721 @code{out_stream}.  These are initialized to @code{stderr} and
722 @code{stdout} respectively.  @xref{Standard Streams}.
723
724 @item void *pstate
725 Private, for use by the argp implementation.
726 @end table
727 @end deftp
728
729 @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
730 @subsection Combining Multiple Argp Parsers
731
732 The @code{children} field in a @code{struct argp} enables other argp
733 parsers to be combined with the referencing one for the parsing of a
734 single set of arguments.  This field should point to a vector of
735 @code{struct argp_child}, which is terminated by an entry having a value
736 of zero in the @code{argp} field.
737
738 Where conflicts between combined parsers arise, as when two specify an
739 option with the same name, the parser conflicts are resolved in favor of
740 the parent argp parser(s), or the earlier of the argp parsers in the
741 list of children.
742
743 @comment argp.h
744 @comment GNU
745 @deftp {Data Type} {struct argp_child}
746 An entry in the list of subsidiary argp parsers pointed to by the
747 @code{children} field in a @code{struct argp}.  The fields are as
748 follows:
749
750 @table @code
751 @item const struct argp *argp
752 The child argp parser, or zero to end of the list.
753
754 @item int flags
755 Flags for this child.
756
757 @item const char *header
758 If non-zero, this is an optional header to be printed within help output
759 before the child options.  As a side-effect, a non-zero value forces the
760 child options to be grouped together.  To achieve this effect without
761 actually printing a header string, use a value of @code{""}.  As with
762 header strings specified in an option entry, the conventional value of
763 the last character is @samp{:}.  @xref{Argp Option Vectors}.
764
765 @item int group
766 This is where the child options are grouped relative to the other
767 `consolidated' options in the parent argp parser.  The values are the
768 same as the @code{group} field in @code{struct argp_option}.  @xref{Argp
769 Option Vectors}.  All child-groupings follow parent options at a
770 particular group level.  If both this field and @code{header} are zero,
771 then the child's options aren't grouped together, they are merged with
772 parent options at the parent option group level.
773
774 @end table
775 @end deftp
776
777 @node Argp Flags, Argp Help, Argp Parsers, Argp
778 @subsection Flags for @code{argp_parse}
779
780 The default behavior of @code{argp_parse} is designed to be convenient
781 for the most common case of parsing program command line argument.  To
782 modify these defaults, the following flags may be or'd together in the
783 @var{flags} argument to @code{argp_parse}:
784
785 @vtable @code
786 @comment argp.h
787 @comment GNU
788 @item ARGP_PARSE_ARGV0
789 Don't ignore the first element of the @var{argv} argument to
790 @code{argp_parse}.  Unless @code{ARGP_NO_ERRS} is set, the first element
791 of the argument vector is skipped for option parsing purposes, as it
792 corresponds to the program name in a command line.
793
794 @comment argp.h
795 @comment GNU
796 @item ARGP_NO_ERRS
797 Don't print error messages for unknown options to @code{stderr}; unless
798 this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
799 is used as the program name in the error messages.  This flag implies
800 @code{ARGP_NO_EXIT}.  This is based on the assumption that silent exiting
801 upon errors is bad behavior.
802
803 @comment argp.h
804 @comment GNU
805 @item ARGP_NO_ARGS
806 Don't parse any non-option args.  Normally these are parsed by calling
807 the parse functions with a key of @code{ARGP_KEY_ARG}, the actual
808 argument being the value.  This flag needn't normally be set, as the
809 default behavior is to stop parsing as soon as an argument fails to be
810 parsed.  @xref{Argp Parser Functions}.
811
812 @comment argp.h
813 @comment GNU
814 @item ARGP_IN_ORDER
815 Parse options and arguments in the same order they occur on the command
816 line.  Normally they're rearranged so that all options come first.
817
818 @comment argp.h
819 @comment GNU
820 @item ARGP_NO_HELP
821 Don't provide the standard long option @samp{--help}, which ordinarily
822 causes usage and option help information to be output to @code{stdout}
823 and @code{exit (0)}.
824
825 @comment argp.h
826 @comment GNU
827 @item ARGP_NO_EXIT
828 Don't exit on errors, although they may still result in error messages.
829
830 @comment argp.h
831 @comment GNU
832 @item ARGP_LONG_ONLY
833 Use the gnu getopt `long-only' rules for parsing arguments.  This allows
834 long-options to be recognized with only a single @samp{-}
835 (i.e.  @samp{-help}).  This results in a less useful interface, and its
836 use is discouraged as it conflicts with the way most GNU programs work
837 as well as the GNU coding standards.
838
839 @comment argp.h
840 @comment GNU
841 @item ARGP_SILENT
842 Turns off any message-printing/exiting options, specifically
843 @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
844 @end vtable
845
846 @node Argp Help Filtering, , Argp Children, Argp Parsers
847 @need 2000
848 @subsection Customizing Argp Help Output
849
850 The @code{help_filter} field in a @code{struct argp} is a pointer to a
851 function that filters the text of help messages before displaying
852 them.  They have a function signature like:
853
854 @smallexample
855 char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input})
856 @end smallexample
857
858
859 @noindent
860 Where @var{key} is either a key from an option, in which case @var{text}
861 is that option's help text.  @xref{Argp Option Vectors}.  Alternately, one
862 of the special keys with names beginning with @samp{ARGP_KEY_HELP_}
863 might be used, describing which other help text @var{text} will contain.
864 @xref{Argp Help Filter Keys}.
865
866 The function should return either @var{text} if it remains as-is, or a
867 replacement string allocated using @code{malloc}.  This will be either be
868 freed by argp or zero, which prints nothing.  The value of @var{text} is
869 supplied @emph{after} any translation has been done, so if any of the
870 replacement text needs translation, it will be done by the filter
871 function.  @var{input} is either the input supplied to @code{argp_parse}
872 or it is zero, if @code{argp_help} was called directly by the user.
873
874 @menu
875 * Keys: Argp Help Filter Keys.  Special @var{key} values for help filter functions.
876 @end menu
877
878 @node Argp Help Filter Keys, , , Argp Help Filtering
879 @subsubsection Special Keys for Argp Help Filter Functions
880
881 The following special values may be passed to an argp help filter
882 function as the first argument in addition to key values for user
883 options.  They specify which help text the @var{text} argument contains:
884
885 @vtable @code
886 @comment argp.h
887 @comment GNU
888 @item ARGP_KEY_HELP_PRE_DOC
889 The help text preceding options.
890
891 @comment argp.h
892 @comment GNU
893 @item ARGP_KEY_HELP_POST_DOC
894 The help text following options.
895
896 @comment argp.h
897 @comment GNU
898 @item ARGP_KEY_HELP_HEADER
899 The option header string.
900
901 @comment argp.h
902 @comment GNU
903 @item ARGP_KEY_HELP_EXTRA
904 This is used after all other documentation; @var{text} is zero for this key.
905
906 @comment argp.h
907 @comment GNU
908 @item ARGP_KEY_HELP_DUP_ARGS_NOTE
909 The explanatory note printed when duplicate option arguments have been suppressed.
910
911 @comment argp.h
912 @comment GNU
913 @item ARGP_KEY_HELP_ARGS_DOC
914 The argument doc string; formally the @code{args_doc} field from the argp parser.  @xref{Argp Parsers}.
915 @end vtable
916
917 @node Argp Help, Argp Examples, Argp Flags, Argp
918 @subsection The @code{argp_help} Function
919
920 Normally programs using argp need not be written with particular
921 printing argument-usage-type help messages in mind as the standard
922 @samp{--help} option is handled automatically by argp.  Typical error
923 cases can be handled using @code{argp_usage} and
924 @code{argp_error}.  @xref{Argp Helper Functions}.  However, if it's
925 desirable to print a help message in some context other than parsing the
926 program options, argp offers the @code{argp_help} interface.
927
928 @comment argp.h
929 @comment GNU
930 @deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name})
931 This outputs a help message for the argp parser @var{argp} to
932 @var{stream}.  The type of messages printed will be determined by
933 @var{flags}.
934
935 Any options such as @samp{--help} that are implemented automatically by
936 argp itself will @emph{not} be present in the help output; for this
937 reason it is best to use @code{argp_state_help} if calling from within
938 an argp parser function.  @xref{Argp Helper Functions}.
939 @end deftypefun
940
941 @menu
942 * Flags: Argp Help Flags.       Specifying what sort of help message to print.
943 @end menu
944
945 @node Argp Help Flags, , , Argp Help
946 @subsection Flags for the @code{argp_help} Function
947
948 When calling @code{argp_help} (@pxref{Argp Help}) or
949 @code{argp_state_help} (@pxref{Argp Helper Functions}) the exact output
950 is determined by the @var{flags} argument.  This should consist of any of
951 the following flags, or'd together:
952
953 @vtable @code
954 @item ARGP_HELP_USAGE
955 A unix @samp{Usage:} message that explicitly lists all options.
956
957 @item ARGP_HELP_SHORT_USAGE
958 A unix @samp{Usage:} message that displays an appropriate placeholder to
959 indicate where the options go; useful for showing the non-option
960 argument syntax.
961
962 @item ARGP_HELP_SEE
963 A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
964 program name and @samp{--help}.
965
966 @item ARGP_HELP_LONG
967 A verbose option help message that gives each option available along
968 with its documentation string.
969
970 @item ARGP_HELP_PRE_DOC
971 The part of the argp parser doc string preceding the verbose option help.
972
973 @item ARGP_HELP_POST_DOC
974 The part of the argp parser doc string that following the verbose option help.
975
976 @item ARGP_HELP_DOC
977 @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
978
979 @item ARGP_HELP_BUG_ADDR
980 A message that prints where to report bugs for this program, if the
981 @code{argp_program_bug_address} variable contains this information.
982
983 @item ARGP_HELP_LONG_ONLY
984 This will modify any output to reflect the @code{ARGP_LONG_ONLY} mode.
985 @end vtable
986
987 The following flags are only understood when used with
988 @code{argp_state_help}.  They control whether the function returns after
989 printing its output, or terminates the program:
990
991 @vtable @code
992 @item ARGP_HELP_EXIT_ERR
993 This will terminate the program with @code{exit (argp_err_exit_status)}.
994
995 @item ARGP_HELP_EXIT_OK
996 This will terminate the program with @code{exit (0)}.
997 @end vtable
998
999 The following flags are combinations of the basic flags for printing
1000 standard messages:
1001
1002 @vtable @code
1003 @item ARGP_HELP_STD_ERR
1004 Assuming that an error message for a parsing error has printed, this
1005 prints a message on how to get help, and terminates the program with an
1006 error.
1007
1008 @item ARGP_HELP_STD_USAGE
1009 This prints a standard usage message and terminates the program with an
1010 error.  This is used when no other specific error messages are
1011 appropriate or available.
1012
1013 @item ARGP_HELP_STD_HELP
1014 This prints the standard response for a @samp{--help} option, and
1015 terminates the program successfully.
1016 @end vtable
1017
1018 @node Argp Examples, Argp User Customization, Argp Help, Argp
1019 @subsection Argp Examples
1020
1021 These example programs demonstrate the basic usage of argp.
1022
1023 @menu
1024 * 1: Argp Example 1.            A minimal program using argp.
1025 * 2: Argp Example 2.            A program using only default options.
1026 * 3: Argp Example 3.            A simple program with user options.
1027 * 4: Argp Example 4.            Combining multiple argp parsers.
1028 @end menu
1029
1030 @node Argp Example 1, Argp Example 2, , Argp Examples
1031 @subsubsection A Minimal Program Using Argp
1032
1033 This is perhaps the smallest program possible that uses argp.  It won't
1034 do much except give an error messages and exit when there are any
1035 arguments, and prints a rather pointless message for @samp{--help}.
1036
1037 @smallexample
1038 @include argp-ex1.c.texi
1039 @end smallexample
1040
1041 @node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples
1042 @subsubsection A Program Using Argp with Only Default Options
1043
1044 This program doesn't use any options or arguments, it uses argp to be
1045 compliant with the GNU standard command line format.
1046
1047 In addition to giving no arguments and implementing a @samp{--help}
1048 option, this example has a @samp{--version} option, which will put the
1049 given documentation string and bug address in the @samp{--help} output,
1050 as per GNU standards.
1051
1052 The variable @code{argp} contains the argument parser
1053 specification.  Adding fields to this structure is the way most
1054 parameters are passed to @code{argp_parse}.  The first three fields are
1055 normally used, but they are not in this small program.  There are also
1056 two global variables that argp can use defined here,
1057 @code{argp_program_version} and @code{argp_program_bug_address}.  They
1058 are considered global variables because they will almost always be
1059 constant for a given program, even if they use different argument
1060 parsers for various tasks.
1061
1062 @smallexample
1063 @include argp-ex2.c.texi
1064 @end smallexample
1065
1066 @node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples
1067 @subsubsection A Program Using Argp with User Options
1068
1069 This program uses the same features as example 2, adding user options
1070 and arguments.
1071
1072 We now use the first four fields in @code{argp} (@pxref{Argp Parsers})
1073 and specify @code{parse_opt} as the parser function.  @xref{Argp Parser
1074 Functions}.
1075
1076 Note that in this example, @code{main} uses a structure to communicate
1077 with the @code{parse_opt} function, a pointer to which it passes in the
1078 @code{input} argument to @code{argp_parse}.  @xref{Argp}.  It is retrieved
1079 by @code{parse_opt} through the @code{input} field in its @code{state}
1080 argument.  @xref{Argp Parsing State}.  Of course, it's also possible to
1081 use global variables instead, but using a structure like this is
1082 somewhat more flexible and clean.
1083
1084 @smallexample
1085 @include argp-ex3.c.texi
1086 @end smallexample
1087
1088 @node Argp Example 4, , Argp Example 3, Argp Examples
1089 @subsubsection A Program Using Multiple Combined Argp Parsers
1090
1091 This program uses the same features as example 3, but has more options,
1092 and presents more structure in the @samp{--help} output.  It also
1093 illustrates how you can `steal' the remainder of the input arguments
1094 past a certain point for programs that accept a list of items.  It also
1095 illustrates the @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only
1096 given if no non-option arguments were supplied to the
1097 program.  @xref{Argp Special Keys}.
1098
1099 For structuring help output, two features are used: @emph{headers} and a
1100 two part option string.  The @emph{headers} are entries in the options
1101 vector.  @xref{Argp Option Vectors}.  The first four fields are zero.  The
1102 two part documentation string are in the variable @code{doc}, which
1103 allows documentation both before and after the options.  @xref{Argp
1104 Parsers}, the two parts of @code{doc} are separated by a vertical-tab
1105 character (@code{'\v'}, or @code{'\013'}).  By convention, the
1106 documentation before the options is a short string stating what the
1107 program does, and after any options it is longer, describing the
1108 behavior in more detail.  All documentation strings are automatically
1109 filled for output, although newlines may be included to force a line
1110 break at a particular point.  In addition, documentation strings are
1111 passed to the @code{gettext} function, for possible translation into the
1112 current locale.
1113
1114 @smallexample
1115 @include argp-ex4.c.texi
1116 @end smallexample
1117
1118 @node Argp User Customization, , Argp Examples, Argp
1119 @subsection Argp User Customization
1120
1121 @cindex ARGP_HELP_FMT environment variable
1122 The formatting of argp @samp{--help} output may be controlled to some
1123 extent by a program's users, by setting the @code{ARGP_HELP_FMT}
1124 environment variable to a comma-separated list of tokens.  Whitespace is
1125 ignored:
1126
1127 @table @samp
1128 @item dup-args
1129 @itemx no-dup-args
1130 These turn @dfn{duplicate-argument-mode} on or off.  In duplicate
1131 argument mode, if an option that accepts an argument has multiple names,
1132 the argument is shown for each name.  Otherwise, it is only shown for the
1133 first long option.  A note is subsequently printed so the user knows that
1134 it applies to other names as well.  The default is @samp{no-dup-args},
1135 which is less consistent, but prettier.
1136
1137 @item dup-args-note
1138 @item no-dup-args-note
1139 These will enable or disable the note informing the user of suppressed
1140 option argument duplication.  The default is @samp{dup-args-note}.
1141
1142 @item short-opt-col=@var{n}
1143 This prints the first short option in column @var{n}.  The default is 2.
1144
1145 @item long-opt-col=@var{n}
1146 This prints the first long option in column @var{n}.  The default is 6.
1147
1148 @item doc-opt-col=@var{n}
1149 This prints `documentation options' (@pxref{Argp Option Flags}) in
1150 column @var{n}.  The default is 2.
1151
1152 @item opt-doc-col=@var{n}
1153 This prints the documentation for options starting in column
1154 @var{n}.  The default is 29.
1155
1156 @item header-col=@var{n}
1157 This will indent the group headers that document groups of options to
1158 column @var{n}.  The default is 1.
1159
1160 @item usage-indent=@var{n}
1161 This will indent continuation lines in @samp{Usage:} messages to column
1162 @var{n}.  The default is 12.
1163
1164 @item rmargin=@var{n}
1165 This will word wrap help output at or before column @var{n}.  The default
1166 is 79.
1167 @end table