Lines Matching refs:code
12 @code{getopt} interface. These features include automatically producing
29 @subsection The @code{argp_parse} Function
31 The main interface to argp is the @code{argp_parse} function. In many
32 cases, calling @code{argp_parse} is the only argument-parsing code
33 needed in @code{main}.
67 The @code{argp_parse} function parses the arguments in @var{argv}, of
70 a @code{struct argp} containing all zeros.
78 Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
79 in @var{flags}, calling @code{argp_parse} may result in the program
86 The return value is zero for successful parsing, or an error code
89 @code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if
95 * Parsers: Argp Parsers. Defining parsers for use with @code{argp_parse}.
96 * Flags: Argp Flags. Flags that modify the behavior of @code{argp_parse}.
113 @samp{--version} option is added when parsing with @code{argp_parse},
115 exit. The exception to this is if the @code{ARGP_NO_EXIT} flag is used.
121 @code{argp_program_bug_address} should point to a string that will be
130 @samp{--version} option is added when parsing with @code{arg_parse},
132 is not the case if the @code{ARGP_NO_HELP} flag is used. If the
133 @code{ARGP_NO_EXIT} flag is set, the exit behavior of the program is
146 This variable takes precedence over @code{argp_program_version}, and is
155 @code{EX_USAGE} from @file{<sysexits.h>}.
161 The first argument to the @code{argp_parse} function is a pointer to a
162 @code{struct argp}, which is known as an @dfn{argp parser}:
170 @table @code
172 A pointer to a vector of @code{argp_option} structures specifying which
180 that always returns @code{ARGP_ERR_UNKNOWN}. @xref{Argp Parser
193 separated by a vertical tab (@code{'\v'}, @code{'\013'}) character. By
199 A pointer to a vector of @code{argp_child} structures. This pointer
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
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
238 array for options, writing @code{@{ 0 @}} is enough to achieve this.
246 @table @code
251 entries may follow this one, with the @code{OPTION_ALIAS} flag
257 @code{isascii (@var{key})} is true), it @emph{also} specifies a short
259 with the code @var{key}.
265 syntaxes), unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp
275 If both the @code{name} and @code{key} fields are zero, this string
290 group header with @code{name} and @code{key} fields both zero, the
307 The following flags may be or'd together in the @code{flags} field of a
308 @code{struct argp_option}. These flags control various aspects of how
312 @vtable @code
325 fields other than @code{name} and @code{key} from the option being
336 If this flag is set, then the option @code{name} field is displayed
342 after all options, after @code{OPTION_DOC} entries with a leading
349 that are completely documented in an argp's @code{args_doc}
353 For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
355 should probably be marked @code{OPTION_NO_USAGE}.
361 The function pointed to by the @code{parser} field in a @code{struct
380 @var{key} from that option's @code{key} field in the option
382 other times with special reserved keys, such as @code{ARGP_KEY_ARG} for
388 @code{arg} field can ever have a value. These must @emph{always} have a
389 value unless the @code{OPTION_ARG_OPTIONAL} flag is specified. If the
393 If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option
397 @var{state} points to a @code{struct argp_state}, containing useful
403 appropriate for @var{key}, and return @code{0} for success,
404 @code{ARGP_ERR_UNKNOWN} if the value of @var{key} is not handled by this
405 parser function, or a unix error code if a real error
410 Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
412 (@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle.
449 @vtable @code
458 @code{ARGP_ERR_UNKNOWN}; if an argument is not handled,
459 @code{argp_parse} immediately returns success, without parsing any more
463 recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be
465 decrements the @code{next} field of its @var{state} argument, the option
471 If a parser function returns @code{ARGP_ERR_UNKNOWN} for
472 @code{ARGP_KEY_ARG}, it is immediately called again with the key
473 @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
475 the tail of the argument vector may be found at @code{@var{state}->argv
477 @code{@var{state}->next} is unchanged, all remaining arguments are
479 @code{@var{state}->next} has been adjusted indicates how many were used.
510 just before @code{ARGP_KEY_END}, where more general validity checks on
516 each element of the @code{child_input} field of @var{state}, if any, are
517 copied to each child's state to be the initial value of the @code{input}
528 case a call with a key of @code{ARGP_KEY_SUCCESS} is never made.
533 @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}. Any resources
534 allocated by @code{ARGP_KEY_INIT} may be freed here. At times, certain
537 @code{ARGP_KEY_ERROR} case.
540 In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
541 functions, and @code{ARGP_KEY_FINI} the last, unless an error was
542 returned by the parser for @code{ARGP_KEY_INIT}. Other keys can occur
547 @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
550 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
555 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
558 This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
564 @code{argp_parse}, the index of the first unparsed command-line argument
569 @code{ARGP_KEY_ERROR}. No further calls are made, except the final call
570 with @code{ARGP_KEY_FINI}.
576 Functions}) is a pointer to a @code{struct argp_state}, which contains
583 @table @code
586 @emph{not} the same @code{struct argp} passed into @code{argp_parse} by
588 contains options implemented by @code{argp_parse} itself, such as
596 The index in @code{argv} of the next argument to be parsed. This may be
600 @code{@var{state}->next = @var{state}->argc}, perhaps after recording
601 the value of the @code{next} field to find the consumed arguments. The
603 then modifying @code{@var{state}->argv[@var{state}->next]} to reflect
607 The flags supplied to @code{argp_parse}. These may be modified, although
608 some flags may only take effect when @code{argp_parse} is first
613 @code{ARGP_KEY_ARG}, this represents the number of the current arg,
614 starting at 0. It is incremented after each @code{ARGP_KEY_ARG} call
615 returns. At all other times, this is the number of @code{ARGP_KEY_ARG}
619 If non-zero, the index in @code{argv} of the first argument following a
625 An arbitrary pointer passed in from the caller of @code{argp_parse}, in
632 @code{@var{state}->child_inputs[@var{i}]} as @emph{its}
633 @code{@var{state}->input} field, where @var{i} is the index of the child
634 in the this parser's @code{children} field. @xref{Argp Children}.
642 @code{argv[0]}, or @code{program_invocation_name} if @code{argv[0]} is
648 @code{err_stream}, all other output, such as @samp{--help} output) to
649 @code{out_stream}. These are initialized to @code{stderr} and
650 @code{stdout} respectively. @xref{Standard Streams}.
672 @var{state} to @code{@var{state}->err_stream} and terminates the program
673 with @code{exit (argp_err_exit_status)}. @xref{Argp Global Variables}.
689 @code{argp_err_exit_status}. @xref{Argp Global Variables}.
701 Similar to the standard GNU error-reporting function @code{error}, this
707 The difference between @code{argp_failure} and @code{argp_error} is that
708 @code{argp_error} is for @emph{parsing errors}, whereas
709 @code{argp_failure} is for other problems that occur during parsing but
857 Error output is sent to @code{@var{state}->err_stream}, and the program
858 name printed is @code{@var{state}->name}.
861 suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags are
862 passed to @code{argp_parse}. @xref{Argp Flags}.
869 be followed by code that returns the appropriate error code:
880 If a parser function will @emph{only} be used when @code{ARGP_NO_EXIT}
886 The @code{children} field in a @code{struct argp} enables other argp
889 @code{struct argp_child}, which is terminated by an entry having a value
890 of zero in the @code{argp} field.
900 @code{children} field in a @code{struct argp}. The fields are as
903 @table @code
914 actually printing a header string, use a value of @code{""}. As with
921 same as the @code{group} field in @code{struct argp_option}. @xref{Argp
923 particular group level. If both this field and @code{header} are zero,
931 @subsection Flags for @code{argp_parse}
933 The default behavior of @code{argp_parse} is designed to be convenient
936 @var{flags} argument to @code{argp_parse}:
938 @vtable @code
942 @code{argp_parse}. Unless @code{ARGP_NO_ERRS} is set, the first element
948 Don't print error messages for unknown options to @code{stderr}; unless
949 this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
951 @code{ARGP_NO_EXIT}. This is based on the assumption that silent exiting
957 the parse functions with a key of @code{ARGP_KEY_ARG}, the actual
970 causes usage and option help information to be output to @code{stdout}
971 and @code{exit (0)}.
988 @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
995 The @code{help_filter} field in a @code{struct argp} is a pointer to a
1012 replacement string allocated using @code{malloc}. This will be either be
1016 function. @var{input} is either the input supplied to @code{argp_parse}
1017 or it is zero, if @code{argp_help} was called directly by the user.
1030 @vtable @code
1053 The argument doc string; formally the @code{args_doc} field from the argp parser. @xref{Argp Parse…
1057 @subsection The @code{argp_help} Function
1062 cases can be handled using @code{argp_usage} and
1063 @code{argp_error}. @xref{Argp Helper Functions}. However, if it's
1065 program options, argp offers the @code{argp_help} interface.
1077 reason it is best to use @code{argp_state_help} if calling from within
1086 @subsection Flags for the @code{argp_help} Function
1088 When calling @code{argp_help} (@pxref{Argp Help}) or
1089 @code{argp_state_help} (@pxref{Argp Helper Functions}) the exact output
1093 @vtable @code
1124 @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
1129 @code{argp_program_bug_address} variable contains this information.
1133 This will modify any output to reflect the @code{ARGP_LONG_ONLY} mode.
1137 @code{argp_state_help}. They control whether the function returns after
1140 @vtable @code
1143 This will terminate the program with @code{exit (argp_err_exit_status)}.
1147 This will terminate the program with @code{exit (0)}.
1153 @vtable @code
1206 The variable @code{argp} contains the argument parser
1208 parameters are passed to @code{argp_parse}. The first three fields are
1211 @code{argp_program_version} and @code{argp_program_bug_address}. They
1226 We now use the first four fields in @code{argp} (@pxref{Argp Parsers})
1227 and specify @code{parse_opt} as the parser function. @xref{Argp Parser
1230 Note that in this example, @code{main} uses a structure to communicate
1231 with the @code{parse_opt} function, a pointer to which it passes in the
1232 @code{input} argument to @code{argp_parse}. @xref{Argp}. It is retrieved
1233 by @code{parse_opt} through the @code{input} field in its @code{state}
1249 illustrates the @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only
1256 two part documentation string are in the variable @code{doc}, which
1258 Parsers}, the two parts of @code{doc} are separated by a vertical-tab
1259 character (@code{'\v'}, or @code{'\013'}). By convention, the
1265 passed to the @code{gettext} function, for possible translation into the
1277 extent by a program's users, by setting the @code{ARGP_HELP_FMT}