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