(Argp Option Vectors): Use @minus, not @math, to format a proper minus
[kopensolaris-gnu/glibc.git] / manual / argp.texi
1 @ignore
2    Documentation for the argp argument parser
3
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>.
7
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.
12
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.
17
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.  */
22 @end ignore
23
24 @node Argp, Suboptions, Getopt, Parsing Program Arguments
25 @need 5000
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
30
31 @dfn{Argp} is an interface for parsing unix-style argument vectors
32 (@pxref{Program Arguments}).
33
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.
41
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.
50
51 @pindex argp.h
52 The header file @file{<argp.h>} should be included to use argp.
53
54 @subsection The @code{argp_parse} Function
55
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}).
59
60 @comment argp.h
61 @comment GNU
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.
71
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}.
76
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.
82 @end deftypefun
83
84 @menu
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.
92 @end menu
93
94 @node Argp Global Variables, Argp Parsers, , Argp
95 @subsection Argp Global Variables
96
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).
100
101 @comment argp.h
102 @comment GNU
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}
108 flag is used).
109 @end deftypevar
110
111 @comment argp.h
112 @comment GNU
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}.}.
119 @end deftypevar
120
121 @need 1500
122 @comment argp.h
123 @comment GNU
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:
131
132 @smallexample
133 void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
134 @end smallexample
135
136 @noindent
137 @xref{Argp Parsing State}, for an explanation of @var{state}.
138
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.
142 @end defvar
143
144 @comment argp.h
145 @comment GNU
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>}.
150 @end deftypevar
151
152 @node Argp Parsers, Argp Flags, Argp Global Variables, Argp
153 @subsection Specifying Argp Parsers
154
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}:
157
158 @comment argp.h
159 @comment GNU
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
163 following fields:
164
165 @table @code
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}.
170
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}.
177
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:}).
184
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.
192
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}.
197
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}.
201 @end table
202 @end deftp
203
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).
211
212 @menu
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.
217 @end menu
218
219 @node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
220 @subsection Specifying Options in an Argp Parser
221
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).
228
229 @comment argp.h
230 @comment GNU
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:
234
235 @table @code
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
241 Option Flags}).
242
243 @item int key
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}.
249
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.
256
257 @item int flags
258 Flags associated with this option (some of which are referred to above).
259 @xref{Argp Option Flags}.
260
261 @item const char *doc
262 A documentation string for this option, for printing in help messages.
263
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
268 @samp{:} character.
269
270 @item int group
271 The group this option is in.
272
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 @minus{}@var{m}, @dots{}, @minus{}2, @minus{}1.  Every entry in an
276 options array with this
277 field 0 will inherit the group number of the previous entry, or zero if
278 it's the first one, unless its a group header (@code{name} and
279 @code{key} fields both zero), in which case, the previous entry + 1 is
280 the default.  Automagic options such as @samp{--help} are put into group
281 @minus{}1.
282
283 Note that because of C structure initialization rules, this field
284 often need not be specified, because 0 is the right value.
285 @end table
286 @end deftp
287
288 @menu
289 * Flags: Argp Option Flags.     Flags for options.
290 @end menu
291
292 @node Argp Option Flags, , , Argp Option Vectors
293 @subsubsection Flags for Argp Options
294
295 The following flags may be or'd together in the @code{flags} field of a
296 @code{struct argp_option}, and control various aspects of how that
297 option is parsed or displayed in help messages:
298
299 @vtable @code
300 @comment argp.h
301 @comment GNU
302 @item OPTION_ARG_OPTIONAL
303 The argument associated with this option is optional.
304
305 @comment argp.h
306 @comment GNU
307 @item OPTION_HIDDEN
308 This option isn't displayed in any help messages.
309
310 @comment argp.h
311 @comment GNU
312 @item OPTION_ALIAS
313 This option is an alias for the closest previous non-alias option.  This
314 means that it will be displayed in the same help entry, and will inherit
315 fields other than @code{name} and @code{key} from the aliased option.
316
317 @comment argp.h
318 @comment GNU
319 @item OPTION_DOC
320 This option isn't actually an option (and so should be ignored by the
321 actual option parser), but rather an arbitrary piece of documentation
322 that should be displayed in much the same manner as the options (known
323 as a @dfn{documentation option}).
324
325 If this flag is set, then the option @code{name} field is displayed
326 unmodified (e.g., no @samp{--} prefix is added) at the left-margin
327 (where a @emph{short} option would normally be displayed), and the
328 documentation string in the normal place.  For purposes of sorting, any
329 leading whitespace and punctuation is ignored, except that if the first
330 non-whitespace character is not @samp{-}, this entry is displayed after
331 all options (and @code{OPTION_DOC} entries with a leading @samp{-}) in
332 the same group.
333
334 @comment argp.h
335 @comment GNU
336 @item OPTION_NO_USAGE
337 This option shouldn't be included in `long' usage messages (but is still
338 included in help messages).  This is mainly intended for options that
339 are completely documented in an argp's @code{args_doc} field
340 (@pxref{Argp Parsers}), in which case including the option
341 in the generic usage list would be redundant.
342
343 For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
344 @samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
345 should probably be marked @code{OPTION_NO_USAGE}.
346 @end vtable
347
348 @node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
349 @subsection Argp Parser Functions
350
351 The function pointed to by the @code{parser} field in a @code{struct
352 argp} (@pxref{Argp Parsers}) defines what actions take place in response
353 to each option or argument that is parsed, and is also used as a hook,
354 to allow a parser to do something at certain other points during
355 parsing.
356
357 @need 2000
358 Argp parser functions have the following type signature:
359
360 @cindex argp parser functions
361 @smallexample
362 error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
363 @end smallexample
364
365 @noindent
366 where the arguments are as follows:
367
368 @table @var
369 @item key
370 For each option that is parsed, @var{parser} is called with a value of
371 @var{key} from that option's @code{key} field in the option vector
372 (@pxref{Argp Option Vectors}).  @var{parser} is also called at other
373 times with special reserved keys, such as @code{ARGP_KEY_ARG} for
374 non-option arguments.  @xref{Argp Special Keys}.
375
376 @item arg
377 If @var{key} is an option, @var{arg} is the value given for it, or zero
378 if no value was specified.  Only options that have a non-zero @code{arg}
379 field can ever have a value, and those must @emph{always} have a value,
380 unless the @code{OPTION_ARG_OPTIONAL} flag was specified (if the input
381 being parsed specifies a value for an option that doesn't allow one, an
382 error results before @var{parser} ever gets called).
383
384 If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option argument;
385 other special keys always have a zero @var{arg}.
386
387 @item state
388 @var{state} points to a @code{struct argp_state}, containing useful
389 information about the current parsing state for use by @var{parser}.
390 @xref{Argp Parsing State}.
391 @end table
392
393 When @var{parser} is called, it should perform whatever action is
394 appropriate for @var{key}, and return either @code{0} for success,
395 @code{ARGP_ERR_UNKNOWN}, if the value of @var{key} is not handled by
396 this parser function, or a unix error code if a real error occurred
397 (@pxref{Error Codes}).
398
399 @comment argp.h
400 @comment GNU
401 @deftypevr Macro int ARGP_ERR_UNKNOWN
402 Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
403 @var{key} value they do not recognize, or for non-option arguments
404 (@code{@var{key} == ARGP_KEY_ARG}) that they do not which to handle.
405 @end deftypevr
406
407 @need 3000
408 A typical parser function uses a switch statement on @var{key}:
409
410 @smallexample
411 error_t
412 parse_opt (int key, char *arg, struct argp_state *state)
413 @{
414   switch (key)
415     @{
416     case @var{option_key}:
417       @var{action}
418       break;
419     @dots{}
420     default:
421       return ARGP_ERR_UNKNOWN;
422     @}
423   return 0;
424 @}
425 @end smallexample
426
427 @menu
428 * Keys: Argp Special Keys.           Special values for the @var{key} argument.
429 * State: Argp Parsing State.         What the @var{state} argument refers to.
430 * Functions: Argp Helper Functions.  Functions to help during argp parsing.
431 @end menu
432
433 @node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
434 @subsubsection Special Keys for Argp Parser Functions
435
436 In addition to key values corresponding to user options, the @var{key}
437 argument to argp parser functions may have a number of other special
438 values (@var{arg} and @var{state} refer to parser function arguments;
439 @pxref{Argp Parser Functions}):
440
441 @vtable @code
442 @comment argp.h
443 @comment GNU
444 @item ARGP_KEY_ARG
445 This is not an option at all, but rather a command line argument, whose
446 value is pointed to by @var{arg}.
447
448 When there are multiple parser functions (due to argp parsers being
449 combined), it's impossible to know which one wants to handle an
450 argument, so each is called in turn, until one returns 0 or an error
451 other than @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one,
452 @code{argp_parse} immediately returns success, without parsing any more
453 arguments.
454
455 Once a parser function returns success for this key, that fact is
456 recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be used.
457 @emph{However}, if while processing the argument, a parser function
458 decrements the @code{next} field of its @var{state} argument, the option
459 won't be considered processed; this is to allow you to actually modify
460 the argument (perhaps into an option), and have it processed again.
461
462 @comment argp.h
463 @comment GNU
464 @item ARGP_KEY_ARGS
465 If a parser function returns @code{ARGP_ERR_UNKNOWN} for
466 @code{ARGP_KEY_ARG}, it is immediately called again with the key
467 @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
468 convenient for consuming all remaining arguments.  @var{arg} is 0, and
469 the tail of the argument vector may be found at @code{@var{state}->argv
470 + @var{state}->next}.  If success is returned for this key, and
471 @code{@var{state}->next} is unchanged, then all remaining arguments are
472 considered to have been consumed, otherwise, the amount by which
473 @code{@var{state}->next} has been adjust indicates how many were used.
474 For instance, here's an example that uses both, for different args:
475
476 @smallexample
477 ...
478 case ARGP_KEY_ARG:
479   if (@var{state}->arg_num == 0)
480     /* First argument */
481     first_arg = @var{arg};
482   else
483     return ARGP_KEY_UNKNOWN;    /* Let the next case parse it.  */
484   break;
485 case ARGP_KEY_ARGS:
486   remaining_args = @var{state}->argv + @var{state}->next;
487   num_remaining_args = @var{state}->argc - @var{state}->next;
488   break;
489 @end smallexample
490
491 @comment argp.h
492 @comment GNU
493 @item ARGP_KEY_END
494 There are no more command line arguments at all.
495
496 @comment argp.h
497 @comment GNU
498 @item ARGP_KEY_NO_ARGS
499 Because it's common to want to do some special processing if there
500 aren't any non-option args, parser functions are called with this key if
501 they didn't successfully process any non-option arguments.  Called just
502 before @code{ARGP_KEY_END} (where more general validity checks on
503 previously parsed arguments can take place).
504
505 @comment argp.h
506 @comment GNU
507 @item ARGP_KEY_INIT
508 Passed in before any parsing is done.  Afterwards, the values of each
509 element of the @code{child_input} field of @var{state}, if any, are
510 copied to each child's state to be the initial value of the @code{input}
511 when @emph{their} parsers are called.
512
513 @comment argp.h
514 @comment GNU
515 @item ARGP_KEY_SUCCESS
516 Passed in when parsing has successfully been completed (even if there are
517 still arguments remaining).
518
519 @comment argp.h
520 @comment GNU
521 @item ARGP_KEY_ERROR
522 Passed in if an error has occurred, and parsing terminated (in which case
523 a call with a key of @code{ARGP_KEY_SUCCESS} is never made).
524
525 @comment argp.h
526 @comment GNU
527 @item ARGP_KEY_FINI
528 The final key ever seen by any parser (even after
529 @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}).  Any resources
530 allocated by @code{ARGP_KEY_INIT} may be freed here (although sometimes
531 certain resources allocated there are to be returned to the caller after
532 a successful parse; in that case, those particular resources can be
533 freed in the @code{ARGP_KEY_ERROR} case).
534 @end vtable
535
536 In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
537 functions, and @code{ARGP_KEY_FINI} the last (unless an error was
538 returned by the parser for @code{ARGP_KEY_INIT}).  Other keys can occur
539 in one the following orders (@var{opt} refers to an arbitrary option
540 key):
541
542 @table @asis
543 @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
544 The arguments being parsed contained no non-option arguments at all.
545
546 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
547 All non-option arguments were successfully handled by a parser function
548 (there may be multiple parser functions if multiple argp parsers were
549 combined).
550
551 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
552 Some non-option argument was unrecognized.
553
554 This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
555 for an argument, in which case parsing stops at that argument.  If a
556 non-zero value for @var{arg_index} was passed to @code{argp_parse}, the
557 index of this argument is returned in it, otherwise an error occurs.
558 @end table
559
560 If an error occurs (either detected by argp, or because a parser
561 function returned an error value), then each parser is called with
562 @code{ARGP_KEY_ERROR}, and no further calls are made except the final
563 call with @code{ARGP_KEY_FINI}.
564
565 @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
566 @subsubsection Functions For Use in Argp Parsers
567
568 Argp provides a number of functions for the user of argp parser
569 functions (@pxref{Argp Parser Functions}), mostly for producing error
570 messages.  These take as their first argument the @var{state} argument
571 to the parser function (@pxref{Argp Parsing State}).
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 Output 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)} (@pxref{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}, @w{const char *@var{fmt}, @dots{}})
586 Print the printf format string @var{fmt} and following args, preceded by
587 the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
588 --help}} message, and terminate the program with an exit status of
589 @code{argp_err_exit_status} (@pxref{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}, @w{int @var{status}, int @var{errnum},} @w{const char *@var{fmt}, @dots{}})
596 Similarly to the standard gnu error-reporting function @code{error},
597 print the printf format string @var{fmt} and following args, preceded by
598 the program name and @samp{:}, and followed by the standard unix error
599 text for @var{errnum} if it is non-zero; then if @var{status} is
600 non-zero, terminate the program with that as its exit status.
601
602 The difference between this function 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
606 values 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}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}})
612 Output a help message for the argp parser referred to by @var{state} to
613 @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,
622 respectively, were 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.
627 In argp parsers intended for such general use, calls to any of these
628 functions should be followed by code return of an appropriate error code
629 for the case where the program @emph{doesn't} terminate; for example:
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 it's known that a parser function will only be used when
641 @code{ARGP_NO_EXIT} 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 (@pxref{Argp}), but instead an internal argp parser
660 that 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.  May be modified.
666
667 @item int next
668 The index in @code{argv} of the next argument to be parsed.  May be modified.
669
670 One way to consume all remaining arguments in the input is to set
671 @code{@var{state}->next = @var{state}->argc} (perhaps after recording
672 the value of the @code{next} field to find the consumed arguments).
673 Also, you can cause the current option to be re-parsed by decrementing
674 this field, and then modifying
675 @code{@var{state}->argv[@var{state}->next]} to be the option that should
676 be reexamined.
677
678 @item unsigned flags
679 The flags supplied to @code{argp_parse}.  May be modified, although some
680 flags may only take effect when @code{argp_parse} is first invoked.
681 @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 is the number of the current arg, starting at
686 0, and incremented after each such call returns.  At all other times,
687 this is the number of such arguments that have been processed.
688
689 @item int quoted
690 If non-zero, the index in @code{argv} of the first argument following a
691 special @samp{--} argument (which prevents anything following being
692 interpreted as an option).  Only set once argument parsing has proceeded
693 past this point.
694
695 @item void *input
696 An arbitrary pointer passed in from the caller of @code{argp_parse}, in
697 the @var{input} argument.
698
699 @item void **child_inputs
700 Values to pass to child parsers.  This vector will be the same length as
701 the number of children in the current parser, and each child parser will
702 be given the value of @code{@var{state}->child_inputs[@var{i}]} as
703 @emph{its} @code{@var{state}->input} field, where @var{i} is the index
704 of the child in the this parser's @code{children} field.  @xref{Argp
705 Children}.
706
707 @item void *hook
708 For the parser function's use.  Initialized to 0, but otherwise ignored
709 by argp.
710
711 @item char *name
712 The name used when printing messages.  This is initialized to
713 @code{argv[0]}, or @code{program_invocation_name} if that is
714 unavailable.
715
716 @item FILE *err_stream
717 @itemx FILE *out_stream
718 Stdio streams used when argp prints something; error messages are
719 printed to @code{err_stream}, and all other output (such as
720 @samp{--help} output) to @code{out_stream}.  These are initialized to
721 @code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}).
722
723 @item void *pstate
724 Private, for use by the argp implementation.
725 @end table
726 @end deftp
727
728 @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
729 @subsection Combining Multiple Argp Parsers
730
731 The @code{children} field in a @code{struct argp} allows other argp
732 parsers to be combined with the referencing one to parse a single set of
733 arguments.  It should point to a vector of @code{struct argp_child},
734 terminated by an entry having a value of zero in the @code{argp} field.
735
736 Where conflicts between combined parsers arise (for instance, if two
737 specify an option with the same name), they are resolved in favor of
738 the parent argp parsers, or earlier argp parsers in the list of children.
739
740 @comment argp.h
741 @comment GNU
742 @deftp {Data Type} {struct argp_child}
743 An entry in the list of subsidiary argp parsers pointed to by the
744 @code{children} field in a @code{struct argp}.  The fields are as follows:
745
746 @table @code
747 @item const struct argp *argp
748 The child argp parser, or zero to end the list.
749
750 @item int flags
751 Flags for this child.
752
753 @item const char *header
754 If non-zero, an optional header to be printed in help output before the
755 child options.  As a side-effect, a non-zero value forces the child
756 options to be grouped together; to achieve this effect without actually
757 printing a header string, use a value of @code{""}.  As with header
758 strings specified in an option entry, the value conventionally has
759 @samp{:} as the last character.  @xref{Argp Option Vectors}.
760
761 @item int group
762 Where to group the child options relative to the other (`consolidated')
763 options in the parent argp parser.  The values are the same as the
764 @code{group} field in @code{struct argp_option} (@pxref{Argp Option
765 Vectors}), but all child-groupings follow parent options at a particular
766 group level.  If both this field and @code{header} are zero, then the
767 child's options aren't grouped together at all, but rather merged with
768 the parent options (merging the child's grouping levels with the
769 parents).
770 @end table
771 @end deftp
772
773 @node Argp Flags, Argp Help, Argp Parsers, Argp
774 @subsection Flags for @code{argp_parse}
775
776 The default behavior of @code{argp_parse} is designed to be convenient
777 for the most common case of parsing program command line argument.  To
778 modify these defaults, the following flags may be or'd together in the
779 @var{flags} argument to @code{argp_parse}:
780
781 @vtable @code
782 @comment argp.h
783 @comment GNU
784 @item ARGP_PARSE_ARGV0
785 Don't ignore the first element of the @var{argv} argument to
786 @code{argp_parse}.  Normally (and always unless @code{ARGP_NO_ERRS} is
787 set) the first element of the argument vector is skipped for option
788 parsing purposes, as it corresponds to the program name in a command
789 line.
790
791 @comment argp.h
792 @comment GNU
793 @item ARGP_NO_ERRS
794 Don't print error messages for unknown options to @code{stderr}; unless
795 this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
796 is used as the program name in the error messages.  This flag implies
797 @code{ARGP_NO_EXIT} (on the assumption that silent exiting upon errors
798 is bad behaviour).
799
800 @comment argp.h
801 @comment GNU
802 @item ARGP_NO_ARGS
803 Don't parse any non-option args.  Normally non-option args are parsed by
804 calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the
805 actual arg as the value.  This flag needn't normally be set, as the
806 normal behavior is to stop parsing as soon as some argument isn't
807 accepted by a parsing function.  @xref{Argp Parser Functions}.
808
809 @comment argp.h
810 @comment GNU
811 @item ARGP_IN_ORDER
812 Parse options and arguments in the same order they occur on the command
813 line---normally they're rearranged so that all options come first
814
815 @comment argp.h
816 @comment GNU
817 @item ARGP_NO_HELP
818 Don't provide the standard long option @samp{--help}, which ordinarily
819 causes usage and option help information to be output to @code{stdout},
820 and @code{exit (0)} called.
821
822 @comment argp.h
823 @comment GNU
824 @item ARGP_NO_EXIT
825 Don't exit on errors (they may still result in error messages).
826
827 @comment argp.h
828 @comment GNU
829 @item ARGP_LONG_ONLY
830 Use the gnu getopt `long-only' rules for parsing arguments.  This
831 allows long-options to be recognized with only a single @samp{-} (for
832 instances, @samp{-help}), but results in a generally somewhat less
833 useful interface, that conflicts with the way most GNU programs work.
834 For this reason, its use is discouraged.
835
836 @comment argp.h
837 @comment GNU
838 @item ARGP_SILENT
839 Turns off any message-printing/exiting options, specifically
840 @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
841 @end vtable
842
843 @node Argp Help Filtering, , Argp Children, Argp Parsers
844 @need 2000
845 @subsection Customizing Argp Help Output
846
847 The @code{help_filter} field in a a @code{struct argp} is a pointer to a
848 function to filter the text of help messages before displaying them.
849 They have a function signature like:
850
851 @smallexample
852 char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input})
853 @end smallexample
854
855 @noindent
856 where @var{key} is either a key from an option, in which case @var{text}
857 is that option's help text (@pxref{Argp Option Vectors}), or one of the
858 special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing
859 which other help text @var{text} is (@pxref{Argp Help Filter Keys}).
860
861 The function should return either @var{text}, if it should be used
862 as-is, a replacement string, which should be allocated using
863 @code{malloc}, and will be freed by argp, or zero, meaning `print
864 nothing'.  The value of @var{text} supplied is @emph{after} any
865 translation has been done, so if any of the replacement text also needs
866 translation, that should be done by the filter function.  @var{input} is
867 either the input supplied to @code{argp_parse}, or zero, if
868 @code{argp_help} was called directly by the user.
869
870 @menu
871 * Keys: Argp Help Filter Keys.  Special @var{key} values for help filter functions.
872 @end menu
873
874 @node Argp Help Filter Keys, , , Argp Help Filtering
875 @subsubsection Special Keys for Argp Help Filter Functions
876
877 The following special values may be passed to an argp help filter
878 function as the first argument, in addition to key values for user
879 options, and specify which help text the @var{text} argument contains:
880
881 @vtable @code
882 @comment argp.h
883 @comment GNU
884 @item ARGP_KEY_HELP_PRE_DOC
885 Help text preceding options.
886
887 @comment argp.h
888 @comment GNU
889 @item ARGP_KEY_HELP_POST_DOC
890 Help text following options.
891
892 @comment argp.h
893 @comment GNU
894 @item ARGP_KEY_HELP_HEADER
895 Option header string.
896
897 @comment argp.h
898 @comment GNU
899 @item ARGP_KEY_HELP_EXTRA
900 After all other documentation; @var{text} is zero for this key.
901
902 @comment argp.h
903 @comment GNU
904 @item ARGP_KEY_HELP_DUP_ARGS_NOTE
905 The explanatory note emitted when duplicate option arguments have been
906 suppressed.
907
908 @comment argp.h
909 @comment GNU
910 @item ARGP_KEY_HELP_ARGS_DOC
911 The argument doc string (the @code{args_doc} field from the argp parser;
912 @pxref{Argp Parsers}).
913 @end vtable
914
915 @node Argp Help, Argp Examples, Argp Flags, Argp
916 @subsection The @code{argp_help} Function
917
918 Normally programs using argp need not worry too much about printing
919 argument-usage-type help messages, because the standard @samp{--help}
920 option is handled automatically by argp, and the typical error cases can
921 be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp
922 Helper Functions}).
923
924 However, if it's desirable to print a standard help message in some
925 context other than parsing the program options, argp offers the
926 @code{argp_help} interface.
927
928 @comment argp.h
929 @comment GNU
930 @deftypefun void argp_help (const struct argp *@var{argp}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}}, @w{char *@var{name}})
931 Output a help message for the argp parser @var{argp} to @var{stream}.
932 What sort of messages is printed is determined by @var{flags}.
933
934 Any options such as @samp{--help} that are implemented automatically by
935 argp itself will @emph{not} be present in the help output; for this
936 reason, it is better to use @code{argp_state_help} if calling from
937 within an argp parser function.  @xref{Argp Helper Functions}.
938 @end deftypefun
939
940 @menu
941 * Flags: Argp Help Flags.       Specifying what sort of help message to print.
942 @end menu
943
944 @node Argp Help Flags, , , Argp Help
945 @subsection Flags for the @code{argp_help} Function
946
947 When calling @code{argp_help} (@pxref{Argp Help}), or
948 @code{argp_state_help} (@pxref{Argp Helper Functions}), exactly what is
949 output is determined by the @var{flags} argument, which should consist
950 of any of the following flags, or'd together:
951
952 @vtable @code
953 @item ARGP_HELP_USAGE
954 A unix @samp{Usage:} message that explicitly lists all options.
955
956 @item ARGP_HELP_SHORT_USAGE
957 A unix @samp{Usage:} message that displays only an appropriate
958 placeholder to indicate where the options go; useful for showing
959 the non-option argument syntax.
960
961 @item ARGP_HELP_SEE
962 A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
963 program name and @samp{--help}.
964
965 @item ARGP_HELP_LONG
966 A verbose option help message that gives each option understood along
967 with its documentation string.
968
969 @item ARGP_HELP_PRE_DOC
970 The part of the argp parser doc string that precedes the verbose option help.
971
972 @item ARGP_HELP_POST_DOC
973 The part of the argp parser doc string that follows the verbose option help.
974
975 @item ARGP_HELP_DOC
976 @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
977
978 @item ARGP_HELP_BUG_ADDR
979 A message saying where to report bugs for this program, if the
980 @code{argp_program_bug_address} variable contains one.
981
982 @item ARGP_HELP_LONG_ONLY
983 Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode.
984 @end vtable
985
986 The following flags are only understood when used with
987 @code{argp_state_help}, and control whether the function returns after
988 printing its output, or terminates the program:
989
990 @vtable @code
991 @item ARGP_HELP_EXIT_ERR
992 Terminate the program with @code{exit (argp_err_exit_status)}.
993
994 @item ARGP_HELP_EXIT_OK
995 Terminate the program with @code{exit (0)}.
996 @end vtable
997
998 The following flags are combinations of the basic ones for printing
999 standard messages:
1000
1001 @vtable @code
1002 @item ARGP_HELP_STD_ERR
1003 Assuming an error message for a parsing error has already printed,
1004 prints a note on how to get help, and terminates the program with an
1005 error.
1006
1007 @item ARGP_HELP_STD_USAGE
1008 Prints a standard usage message and terminates the program with an
1009 error.  This is used when no more specific error message is appropriate.
1010
1011 @item ARGP_HELP_STD_HELP
1012 Prints the standard response for a @samp{--help} option, and terminates
1013 the program successfully.
1014 @end vtable
1015
1016 @node Argp Examples, Argp User Customization, Argp Help, Argp
1017 @subsection Argp Examples
1018
1019 These example programs demonstrate the basic usage of argp.
1020
1021 @menu
1022 * 1: Argp Example 1.            A minimal program using argp.
1023 * 2: Argp Example 2.            A program using only default options.
1024 * 3: Argp Example 3.            A simple program with user options.
1025 * 4: Argp Example 4.            Combining multiple argp parsers.
1026 @end menu
1027
1028 @node Argp Example 1, Argp Example 2, , Argp Examples
1029 @subsubsection A Minimal Program Using Argp
1030
1031 This is (probably) the smallest possible program that uses argp.
1032 It won't do much except give an error messages and exit when there are any
1033 arguments, and print a (rather pointless) message for @samp{--help}.
1034
1035 @smallexample
1036 @include argp-ex1.c.texi
1037 @end smallexample
1038
1039 @node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples
1040 @subsubsection A Program Using Argp with Only Default Options
1041
1042 This program doesn't use any options or arguments, but uses argp to be
1043 compliant with the GNU standard command line format.
1044
1045 In addition to making sure no arguments are given, and implementing a
1046 @samp{--help} option, this example will have a @samp{--version} option,
1047 and will put the given documentation string and bug address in the
1048 @samp{--help} output, as per GNU standards.
1049
1050 The variable @code{argp} contains the argument parser specification;
1051 adding fields to this structure is the way most parameters are passed to
1052 @code{argp_parse} (the first three fields are usually used, but not in
1053 this small program).  There are also two global variables that argp
1054 knows about defined here, @code{argp_program_version} and
1055 @code{argp_program_bug_address} (they are global variables because they
1056 will almost always be constant for a given program, even if it uses
1057 different argument parsers for various tasks).
1058
1059 @smallexample
1060 @include argp-ex2.c.texi
1061 @end smallexample
1062
1063 @node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples
1064 @subsubsection A Program Using Argp with User Options
1065
1066 This program uses the same features as example 2, and adds user options
1067 and arguments.
1068
1069 We now use the first four fields in @code{argp} (@pxref{Argp Parsers}),
1070 and specifies @code{parse_opt} as the parser function (@pxref{Argp
1071 Parser Functions}).
1072
1073 Note that in this example, @code{main} uses a structure to communicate
1074 with the @code{parse_opt} function, a pointer to which it passes in the
1075 @code{input} argument to @code{argp_parse} (@pxref{Argp}), and is
1076 retrieved by @code{parse_opt} through the @code{input} field in its
1077 @code{state} argument (@pxref{Argp Parsing State}).  Of course, it's
1078 also possible to use global variables instead, but using a structure
1079 like this is somewhat more flexible and clean.
1080
1081 @smallexample
1082 @include argp-ex3.c.texi
1083 @end smallexample
1084
1085 @node Argp Example 4, , Argp Example 3, Argp Examples
1086 @subsubsection A Program Using Multiple Combined Argp Parsers
1087
1088 This program uses the same features as example 3, but has more options,
1089 and somewhat more structure in the @samp{--help} output.  It also shows
1090 how you can `steal' the remainder of the input arguments past a certain
1091 point, for programs that accept a list of items, and the special
1092 @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no
1093 non-option arguments were supplied to the program (@pxref{Argp Special
1094 Keys}).
1095
1096 For structuring the help output, two features are used: @emph{headers},
1097 which are entries in the options vector (@pxref{Argp Option Vectors})
1098 with the first four fields being zero, and a two part documentation
1099 string (in the variable @code{doc}), which allows documentation both
1100 before and after the options (@pxref{Argp Parsers}); the
1101 two parts of @code{doc} are separated by a vertical-tab character
1102 (@code{'\v'}, or @code{'\013'}).  By convention, the documentation
1103 before the options is just a short string saying what the program does,
1104 and that afterwards is longer, describing the behavior in more detail.
1105 All documentation strings are automatically filled for output, although
1106 newlines may be included to force a line break at a particular point.
1107 All documentation strings are also passed to the @code{gettext}
1108 function, for possible translation into the current locale.
1109
1110 @smallexample
1111 @include argp-ex4.c.texi
1112 @end smallexample
1113
1114 @node Argp User Customization, , Argp Examples, Argp
1115 @subsection Argp User Customization
1116
1117 @cindex ARGP_HELP_FMT environment variable
1118 The way formatting of argp @samp{--help} output may be controlled to
1119 some extent by a program's users, by setting the @code{ARGP_HELP_FMT}
1120 environment variable to a comma-separated list (whitespace is ignored)
1121 of the following tokens:
1122
1123 @table @samp
1124 @item dup-args
1125 @itemx no-dup-args
1126 Turn @dfn{duplicate-argument-mode} on or off.  In duplicate argument
1127 mode, if an option which accepts an argument has multiple names, the
1128 argument is shown for each name; otherwise, it is only shown for the
1129 first long option, and a note is emitted later so the user knows that it
1130 applies to the other names as well.  The default is @samp{no-dup-args},
1131 which is less consistent, but prettier.
1132
1133 @item dup-args-note
1134 @item no-dup-args-note
1135 Enable or disable the note informing the user of suppressed option
1136 argument duplication.  The default is @samp{dup-args-note}.
1137
1138 @item short-opt-col=@var{n}
1139 Show the first short option in column @var{n} (default 2).
1140
1141 @item long-opt-col=@var{n}
1142 Show the first long option in column @var{n} (default 6).
1143
1144 @item doc-opt-col=@var{n}
1145 Show `documentation options' (@pxref{Argp Option Flags}) in column
1146 @var{n} (default 2).
1147
1148 @item opt-doc-col=@var{n}
1149 Show the documentation for options starting in column @var{n} (default 29).
1150
1151 @item header-col=@var{n}
1152 Indent group headers (which document groups of options) to column
1153 @var{n} (default 1).
1154
1155 @item usage-indent=@var{n}
1156 Indent continuation lines in @samp{Usage:} messages to column @var{n}
1157 (default 12).
1158
1159 @item rmargin=@var{n}
1160 Word wrap help output at or before column @var{n} (default 79).
1161 @end table