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