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