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