Included is a 0th order implementation for argp documentation.
.\" Copyright (C) 2006 Justin Pryzby <[EMAIL PROTECTED]> .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be .\" included in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .\" .\" References: .\" glibc manual and source .TH ARGP 3 "30 May 2006" GNU .SH NAME argp_parse, \ argp_state_help, \ argp_help, \ argp_usage, \ argp_error, \ argp_failure, \ _option_is_end, \ _option_is_short, \ _argp_input, \ argp_program_version, \ argp_program_version_hook, \ argp_err_exit_status, \ argp_program_bug_address, \ argp_parser_t \ \- parsing and handling of command-line arguments . . . .SH SYNOPSIS .B #include <argp.h> . . .HP .PD 0 .BI "error_t argp_parse(const struct argp *" argp , .B int .IB argc , .BI "char **" argv , .B unsigned .IB flags , .BI "int *" arg_index , .BI "void *" input ); . . .HP .BI "void argp_state_help(const struct argp_state *" state , .BI "FILE *" stream , .B unsigned .IB flags ); . .HP .BI "void argp_help(const struct argp *" argp , .BI "FILE *" stream , .BI unsigned .IB flags , .BI "char *" name ); .LP . . .BI "void argp_usage(const struct argp_state *" state ); . .br .BI "void argp_error(const struct argp_state *" state , .BI "const char *" fmt , .B ...); . . .HP .BI "void argp_failure(const struct argp_state *" state , .BI int .IB status , .B int .IB errnum , .BI "const char *" fmt , .B ...); .LP . . .br .BI "int _option_is_end(const struct argp_option *" opt ); . .br .BI "int _option_is_short(const struct argp_option *" opt ); . .HP .BI "void *_argp_input(const struct argp *" argp , .BI "const struct argp_state *" state ); .LP . . .\" Variables: .br .BI "const char *" argp_program_version ; . .HP .BI "void (*" argp_program_version_hook ")(FILE *" stream , .BI "struct argp_state *" state ); .LP . . .B error_t .IB argp_err_exit_status ; .br .BI "const char *" argp_program_bug_address ; .br . . .HP .B "typedef error_t (*argp_parser_t)(int" .IR key , .BI "char *" arg , .BI "struct argp_state *" state ); .PD . . . .SH DESCRIPTION .BR argp (3) provides functionality for argument parsing and includes handling for .B \-\-help and .B \-\-version messages; it also allows the use of option and parser sets from other application components. . . .P .BR argp_parse () parses the command-line argument vector .I argv of length .IR argc ; note that, by default, calling .BR argp_parse () may cause the program to terminate if a problem with the arguments is detected, an internal error occurs, or one of the automatically generated options such as .B \-\-help are given. . .P .IR argp should be a pointer to a structure defining the options to be handled as well as the information for the .B \-\-help text; a NULL value is equivalent to having all elements set to zero. . . .P .I argp includes references to other structures, and a callback function. .B struct argp_option defines a single accepted option; .B struct argp_child may be used to include parsing abilities implemented by other modules; The .I parser callback is expected to handle the accepted options; it is passed a .BR "struct argp_state *" . . .P If .I arg_index is not NULL, it is set to the index into .I argv of the first unhandled argument. .\" non option? .I input points to arbitrary data to be passed to the parser callback function; it may be used to communicate the results of argument parsing. .I flags is a bitwise combination of the following values: .\" Test interaction between the first 3: .TP .B ARGP_PARSE_ARGV0 Inhibits the normal behavior of skipping .IR argv[0] ; typically, this doesn't contain an argument, but rather the name of the program. . .TP .B ARGP_NO_ERRS Inhibits the diagnostic output of messages regarding unrecognized arguments to .BR stderr . Also prevents exiting on error, as with .BR ARGP_NO_EXIT . . .TP .B ARGP_NO_ARGS Inhibits passing non-option arguments to the parser function. Normally, all command-line arguments are passed. Note that the parser function need not handle non-option arguments, and .BR argp_parse () will only fail when an option argument is unhandled (or other error occurs). . .TP .B ARGP_IN_ORDER Inhibits the manipulation of .IR argv ; otherwise, all option arguments are shifted to precede the non-option arguments. The same effect is achieved with .BR getopt () by setting the environment variable .BR POSIXLY_CORRECT . . .TP .B ARGP_NO_HELP Inhibits automatic processing of the .B \-\-help and .B \-\-version arguments. . .TP .B ARGP_NO_EXIT Inhibits any call to .BR exit () from within .BR argp_parse (). .\" ... Otherwise, unhandled option arguments and errors cause the program to terminate. . .TP .B ARGP_LONG_ONLY Allows long options to be prefixed with a single hyphen, instead of requiring a double-hyphen. The effect is the same as using .BR getopt_long () instead of .BR getopt (). . .TP .B ARGP_SILENT Inhibits any behavior besides argument parsing. Equivalent to .BR ARGP_NO_EXIT|ARGP_NO_ERRS|ARGP_NO_HELP . . . . .SH "STRUCT ARGP" .P The .B argp structure is defined to have the following fields: .TP 1.1i .BI "const struct argp_option *" options ; Null-terminated array of accepted options; NULL is equivalent to a single element with all elements set to zero. . .TP .BI "argp_parser_t " parser ; Handler for the accepted options; NULL is equivalent to a handler which handles no options. . .TP .BI "const char *" args_doc ; Description of the required, non-option arguments. Alternate accepted syntaxes may be given, separated by newlines. . .TP .BI "const char *" doc ; Description of the program. The first part appears following the .B Usage: line in help output; the second part, following a vertical tab character (if any), appears after the options but before any bug reporting address. . .TP .BI "const struct argp_child *" children ; Null-terminated array specifying indirectly-implemented parsing capabilities. This is intended to allow library components to expose parameters as .B argp structures, which can be trivially used by applications. This field will often be left as NULL. . .TP .BI "char *(*" help_filter ")(int " key, " const char *" text, " void *" input ); . Filter function allowing a layer of indirection before the output of .IR text . This is intended to allow, for example, output of translated .B \-\-help information. This field will often be left as NULL. .TP .BI "const char *" argp_domain ; .BR textdomain ()-style description of the translation to use for internally-generated messages. This field will often be left as NULL. .LP . . . .SH "STRUCT ARGP_OPTION" .P An allowed option is defined by a .BR "struct argp_option" , which has the following fields: . .TP 1.1i .BI "const char *" name ; Long option name; may be NULL. . .TP .BI "int " key ; Value provided to the parser callback function to distinguish between options; it is also accepted as the short option character if .I key is positive and .BI isprint( key ) is true. . .TP .BI "const char *" arg ; Description of the option associated with the argument. If .I arg is not NULL, the option will be required, unless .B OPTION_ARG_OPTIONAL is set in .IR flags . . .TP .BI "int " flags ; .br Bitwise combination of the following values: .RS .TP .B OPTION_ARG_OPTIONAL No value is required to follow this argument. . .TP .B OPTION_HIDDEN This option is not to be included in help output. . .TP .B OPTION_ALIAS .\" First option This option is an alias for the most recent option which did not have this flag set. .IR arg , .IR flags , .IR doc , and .I group are inherited from that option. . .TP .B OPTION_DOC This option is actually an informative text. . .TP .B OPTION_NO_USAGE The option is a special case documented by the .I args_doc member of the .B argp structure, and should not appear in the text of .B \-\-usage messages (but will still appear in the .B \-\-help messages). .RE . .TP .BI "const char *" doc ; Description of the effect this option has on the behavior of the program. If .I name and .I key are both set to zero, then .I doc is displayed as a "separator" between sets of options, and appears in the .B \-\-help message before the other options with the same group. It is suggested to end such separators with a colon. . .TP .BI "int " group ; Used for sorting the options displayed in the .B \-\-help message. Option groups are displayed in increasing order, but with negative groups following nonnegative ones. .LP . . . .SH "PARSER CALLBACK FUNCTION" For each command-line argument, .BR argp_parse () calls the parser callback functions, defined to have type .BR argp_parser_t . .I key is the value given by the .BR "struct argp_option" . .I arg points to the option following the argument, if any; otherwise, it is NULL. .P Parser functions should return 0 if they handle the given argument, and .B ARGP_ERR_UNKNOWN if not, in which case, the remainder of the parsers will be tried. If an internal error occurs, a negative error code (as used by .BR errno ) should be returned. .P The .I parser functions are also called with special .I key values; if .I key is .BR ARGP_KEY_ARG , then .I arg is a non-option command-line argument. All other special values will have .I arg set to NULL. .P .I key may be any of the following special values: . .TP .B ARGP_KEY_ARG .I arg is a non-option command-line argument (such as those documented in .IR args_doc ). . .TP .B ARGP_KEY_ARGS This parser was just called with .B ARGP_KEY_ARG set. This is intended to allow the positions of an arbitrary number of non-option arguments to be stored. . .TP .B ARGP_KEY_END All argument have been handled successfully, including non-option arguments. Child parsers are called first. .B ARGP_KEY_SUCCESS will be set at the next callback, unless an error occurs. . .TP .B ARGP_KEY_NO_ARGS All option arguments have been handled successfully, and no non-option command-line arguments were processed. .B ARGP_KEY_END will be set at the next callback, unless an error occurs. . .TP .B ARGP_KEY_INIT This is the first call of the parser function; the parent parser is initialized before the child parsers. Memory allocation and initialization of .I child_input might happen at this point. . .TP .B ARGP_KEY_FINI This is the last call of the parser function. Memory might be freed at this point. . .TP .B ARGP_KEY_SUCCESS All option arguments have been handled successfully, and .BR argp_parse () will return 0. Any number of non-option arguments may or may not have been handled. .B ARGP_KEY_FINI will be set at the next callback, unless an error occurs. . .TP .B ARGP_KEY_ERROR .\" What kind? An error occurred, and either the program will terminate, or .BR argp_parse () will return nonzero, depending on whether .B ARGP_NO_EXIT is set. .B ARGP_KEY_FINI will be set at the next callback, (unless the error occured during a callback with .B ARGP_KEY_INIT set. .LP . . . .SH "STRUCT ARGP_STATE" The parser functions are passed a pointer to .BR "struct argp_state" , which is defined to have the following fields: .TP .BI "const struct argp *" root_argp ; The .B argp structure created to include automatically generated options, such as .BR \-\-help . . .TP .BI "int " argc ; The count of arguments, as passed to .BR argp_parse (); this field may be manipulated by the callback function. . .TP .BI "char **" argv ; The command-line arguments, as passed to .BR argp_parse (); this field may be manipulated by the callback function. . .TP .BI "int " next ; The index into .I argv of the argument to be processed after the current argument; this field may be manipulated by the callback function. . .TP .BI "unsigned " flags ; The .I flags argument, as passed to .BR argp_parse (); this field may be manipulated by the callback function (but the change may not necessarily effect the behavior of calling .BR argp_parse () with the new flags). . .TP .BI "unsigned " arg_num ; If a parser callback function is called with .I key set to .BR ARGP_KEY_ARG , this is the index into .\" next-1; really?? .I argv of the current argument. Otherwise, it is the number of non-option arguments that have been handled. . .TP .BI "int " quoted ; If an "\-\-" argument (used to end option parsing) was processed, the index into .I argv of the following argument; otherwise zero. . .TP .BI "void *" input ; The .I input argument, as passed to .BR argp_parse (); this field may be manipulated by the callback function. . .TP .BI "void **" child_inputs ; A vector of arbitrary input pointers to be passed to each of the child parsers. . .TP .BI "void *" hook ; .\" TODO .\" I'm going to take a stab in the dark and guess that this is a .\" per-parser object, to be interpreted by the parser . .TP .BI "char *" name ; The program name used to prefix messages from .BR argp_usage (), .BR argp_error (), and .BR argp_failure (). . .TP .BI "FILE *" err_stream ; Stream to which errors and diagnostic messages are printed. . .TP .BI "FILE *" err_stream ; Stream to which expected output is printed. . .TP .BI "void *" pstate ; Opaque data for internal use. .LP . . . .SH "HELP FILTER" If this callback returns NULL, nothing is output; otherwise, the returned string is output, then freed. It is allowed to return .I text unmodified. .P .\" text is the opt_doc if key is ... .I key is the value from an element of the .B argp_option structure, or one of the following special values: .TP .B ARGP_KEY_HELP_PRE_DOC First part of .IR args_doc ; preceding any vertical tab. . .TP .B ARGP_KEY_HELP_POST_DOC Remainder of .IR args_doc ; following a vertical tab. . .TP .B ARGP_KEY_HELP_HEADER .\" TODO . .TP .B ARGP_KEY_HELP_EXTRA .\" TODO .LP .P .I input is the value from the .BR argp_parse () call. . . . .SH "STRUCT ARGP_CHILD" The .B argp_child structure is defined to have the following fields: .TP .BI "struct argp *" argp ; Defines the auxiliary options and parsers to handle them. . .TP .BI "int " flags ; A bitwise combination of any of the values allowed for the .I flag argument to .BR argp_parse (). . .TP .BI "cont char *" header ; A "separator" heading used to prefix the group of arguments exposed by this child. May be NULL, in which case this child's arguments are merged with its parents'. To inhibit merging without printing any heading, use the null string. . .TP .BI "int " group ; Determines the order in which this child's argument's appear relative to the parent's arguments. .LP . . . .SH "VARIABLES" If .I argp_program_version is not NULL, it is printed by .BR argp_parse () to handle a .B \-\-version argument (unless .I argp_program_version_hook is nonzero). Setting .B ARGP_NO_HELP inhibits processing of .B \-\-version arguments. . . .P If .I argp_program_version_hook is not NULL, it is used by .BR argp_parse () as a callback function to output the .B \-\-version information, instead of printing .IR argp_program_version (if nonzero). Setting .B ARGP_NO_HELP inhibits processing of .B \-\-version arguments. . . .P If .I argp_err_exit_status is defined and set to a nonzero value, it is used as the exit status of the program when .BR argp_parse () discovers a problem with the command-line arguments. . . .P If .I argp_program_bug_address is not NULL, it is printed by .BR argp_parse () in the .B \-\-help output. .P . . . .SH "HELP FUNCTIONS" The following functions (with the exception of .BR argp_help ()) are intended to be called from the .I parser callback functions, and accept as their first argument an .BR "struct argp_state *" , as passed to the callback. . .P They respect .BR ARGP_NO_EXIT , .BR ARGP_NO_ERRS , and (with the exception of .BR argp_failure ()), .I argp_err_exit_status and so are safe to use in library code, because the application can control whether the program may terminate through the .IR flags argument to .BR argp_parse (). . .P The .I parser function calling these routines should return a nonzero value afterwards, to prevent .BR argp_parse () from returning successfully in the case that .B ARGP_NO_EXIT is set. . . .P .BR argp_state_help () prints to .I stream a help message of the style requested by .IR flags , which may have any of the same values as for .BR argp_help , or one of the following additional values: .TP .B ARGP_HELP_EXIT_ERR . .TP .B ARGP_HELP_EXIT_OK .\" TODO: Are the following allowed/effective in argp_help? . .TP .B ARGP_HELP_STD_ERR Displays a helpful hint about how to get .B \-\-help output, and exits indicating failure. . .TP .B ARGP_HELP_STD_USAGE The same as .BR ARGP_HELP_STD_USAGE , but also preceded by the short usage message. . .TP .B ARGP_HELP_STD_HELP Displays the same output as the automatically generated .B \-\-help option. .LP . . .BR argp_usage () displays to .B stderr the usage message specified by .B ARGP_HELP_STD_USAGE and terminates the program. . .P .BR argp_error () displays a formatted message followed by a hint about how to get the help message and terminates the program. . .P .BR argp_failure () accepts the same arguments as .BR error (); it displays a .BR printf ()-style message followed by the string given by .BI perror( errnum ). This is intended for the case of internal errors, such as failure to allocate memory. If .I status has a non-zero value, then .BR exit () is called, terminating the program with the given value as the exit status. . . . .P .BR argp_help () prints a .B \-\-help message to .IR stream . .I name is the program name to be used in the .B Usage: message. The style of the message is determined by .IR flags , which is a bitwise combination of the following values: .TP .B ARGP_HELP_USAGE Display a full .B \-\-usage message, which explicitly lists each accepted option. . .TP .B ARGP_HELP_SHORT_USAGE Display a short .B \-\-usage message, which only shows .BR [OPTION]... . . .TP .B ARGP_HELP_SEE Display a hint about how to find the .B \-\-help message (should not be used with .BR ARGP_HELP_USAGE ). . .TP .B ARGP_HELP_LONG Display a full .B \-\-help message, with descriptions for each accepted option. . .TP .B ARGP_HELP_PRE_DOC Display a short description of the program; the first part of .IR doc , appearing before the vertical tab (if any). . .TP .B ARGP_HELP_POST_DOC Display a longer description of the program; the second part of .IR doc , appearing after the vertical tab (if any). . .TP .B ARGP_HELP_DOC Display both the first and second parts of .IR doc , separated by 2 newlines. . .TP .B ARGP_HELP_BUG_ADDR Display a message specifying where to send bug reports, if .I argp_program_bug_address is set. . .TP .B ARGP_HELP_LONG_ONLY Used internally when .B ARGP_LONG_ONLY is set. .LP . . .BR argp_help () should be avoided; it doesn't include automatically generated options like .BR \-\-help ; use .BR argp_state_help () instead. . . . .SH "RETURN VALUE" .BR argp_parse () returns 0 on success. If an internal error occurs, or an error with the arguments is detected, or if none of the parser callback functions handle an option argument, or if any of the callback functions returns another error, .BR argp_parse () will cause the program to terminate, unless .B ARGP_NO_EXIT is set. If it is set, and an error occurs, a nonzero value is returned. . .P .\" are these intended to be exposed? .BR _option_is_short () returns nonzero if .I opt is will be displayed as a short option in .B \-\-help output. .P .BR _argp_input () returns the .I input data specified in the call to .BR argp_parse (). .\" TODO: argp, state .P .BR _option_is_end () returns nonzero if .I opt is the null-terminating element ending the option list. . . . .SH ERRORS If .B ARGP_NO_EXIT is set, and all parser callback functions return .B ARGP_ERR_UNKNOWN for any user-specified argument, .BR argp_parse () returns .BR EINVAL ; if any parser returns a nonzero value other than .BR ARGP_ERR_UNKNOWN , .BR argp_parse () returns immediately with that same return value, which should be one of the system error codes in the style of .BR errno() . . . . .SH EXAMPLE .nf .\" TODO .fi . . . .SH ENVIRONMENT .\" TODO: If .\" .B POSIXLY_CORRECT .\" is set, the behavior is as if .\" .B ARGP_IN_ORDER .\" were set. The .B \-\-help output is configurable at runtime through the environment variable .BR ARGP_HELP_FMT , which can be set to a comma-separated list of following strings: .TP .B [no\-]dup\-args If .B dup\-args is set, the .B \-\-help text for each description of an argument which has an optional or required option will mention the option. Otherwise, only the long argument mentions the option, and an explanatory note is printed immediately preceding the second part of the .I doc text (if any). Default: .BR no\-dup\-args . . .TP .BI short\-opt\-col= n The column in which the short options are printed is set to .IR n ; default: 2. . .TP .BI long\-opt\-col= n The column in which the long options are printed is set to .IR n ; default: 6. . .TP .BI doc\-opt\-col= n The column in which the documentation options are printed is set to .IR n ; default: 2. . .TP .BI opt\-doc\-col= n The column in which options' documentation is printed is set to .IR n ; default: 29. . .TP .BI header\-col= n The column in which "group headers" are printed is set to .IR n ; default: 1. . .TP .BI usage\-indent= n The amount by which continued lines in the .B Usage: statement are indented is set to .I n spaces; default: 12. . .TP .BI rmargin= n The maximum width of the output generated by .B argp is set to .IR n ; default: 79. .LP . . . .SH "CONFORMING TO" These functions and variables are GNU extensions, and should not be used in programs intended to be portable. . .SH NOTES It is a somewhat common error to fail to check if extra non\-option arguments are given. . .SH BUGS Inconsistent values for the environment variables can cause the program to crash. .\" Debian bug # ; fixed-upstream? .P If .B \-h is unused for automatic options, it should be recognized as a short option synonymous with .BR \-\-help . . .SH SEE ALSO .BR getopt (3), .BR error (3), .BR errno (3), .BR exit (3), .BR program_invocation_name (3) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
