diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/.cvsignore | 2 | ||||
| -rw-r--r-- | manual/Makefile | 17 | ||||
| -rw-r--r-- | manual/argp.texi | 1127 | ||||
| -rw-r--r-- | manual/getopt.texi | 257 | ||||
| -rw-r--r-- | manual/libc.texinfo | 13 | ||||
| -rw-r--r-- | manual/maint.texi | 4 | ||||
| -rw-r--r-- | manual/startup.texi | 306 | ||||
| -rw-r--r-- | manual/summary.awk | 5 | ||||
| -rw-r--r-- | manual/texinfo.tex | 12 |
9 files changed, 1461 insertions, 282 deletions
diff --git a/manual/.cvsignore b/manual/.cvsignore index 146fd188bf..51a9a04ef2 100644 --- a/manual/.cvsignore +++ b/manual/.cvsignore @@ -8,5 +8,5 @@ glibc-* *.toc *.aux *.log *.cp *.cps *.fn *.fns *.vr *.vrs *.tp *.tps *.ky *.kys *.pg *.pgs -chapters chapters-incl summary.texi stamp-* +chapters chapters-incl1 chapters-incl2 summary.texi stamp-* distinfo diff --git a/manual/Makefile b/manual/Makefile index 94cc59c891..5f05524049 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -39,11 +39,20 @@ endif chapters: libc.texinfo $(find-includes) ifdef chapters --include chapters-incl -chapters-incl: $(chapters) +# @includes in chapter files +-include chapters-incl1 +chapters-incl1: $(chapters) $(find-includes) -chapters-incl := $(filter-out summary.texi,$(chapters-incl)) +chapters-incl1 := $(filter-out summary.texi,$(chapters-incl1)) endif +ifdef chapters-incl1 +# @includes in files included by chapter files, if any +-include chapters-incl2 +chapters-incl2: $(chapters-incl1) + $(find-includes) +endif + +chapters-incl := $(chapters-incl1) $(chapters-incl2) define find-includes (echo '$(@F) :=' \\ ;\ @@ -75,7 +84,7 @@ dir-add.texi: xtract-typefun.awk $(chapters) sed -e 's,[{}],@&,g' \ -e 's,/\*\(@.*\)\*/,\1,g' \ -e 's,/\* *,/* @r{,g' -e 's, *\*/,} */,' \ - -e 's/\(@[a-z][a-z]*\)@{\([^}]*\)@}/\1{\2}/'\ + -e 's/\(@[a-z][a-z]*\)@{\([^}]*\)@}/\1{\2}/g'\ $< | expand > $@.new mv -f $@.new $@ diff --git a/manual/argp.texi b/manual/argp.texi new file mode 100644 index 0000000000..53a405e93f --- /dev/null +++ b/manual/argp.texi @@ -0,0 +1,1127 @@ +@ignore + Documentation for the argp argument parser + + Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc. + This file is part of the GNU C Library. + Written by Miles Bader <miles@gnu.ai.mit.edu>. + + The GNU C Library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + The GNU C Library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public + License along with the GNU C Library; see the file COPYING.LIB. If not, + write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. */ +@end ignore + +@node Argp, Suboptions, Getopt, Parsing Program Arguments +@need 5000 +@section Parsing Program Options with Argp +@cindex argp (program argument parser) +@cindex argument parsing with argp +@cindex option parsing with argp + +@dfn{Argp} is an interface for parsing unix-style argument vectors +(@pxref{Program Arguments}). + +Unlike the more common @code{getopt} interface, it provides many related +convenience features in addition to parsing options, such as +automatically producing output in response to @samp{--help} and +@samp{--version} options (as defined by the GNU coding standards). +Doing these things in argp results in a more consistent look for +programs that use it, and makes less likely that implementors will +neglect to implement them or keep them up-to-date. + +Argp also provides the ability to merge several independently defined +option parsers into one, mediating conflicts between them, and making +the result appear seamless. A library can export an argp option parser, +which programs can easily use in conjunction with their own option +parser. This results in less work for user programs (indeed, some may +use only argument parsers exported by libraries, and have no options of +their own), and more consistent option-parsing for the abstractions +implemented by the library. + +@pindex argp.h +The header file @file{<argp.h>} should be included to use argp. + +@subsection The @code{argp_parse} Function + +The main interface to argp is the @code{argp_parse} function; often, a +call to @code{argp_parse} is the only argument-parsing code needed in +@code{main} (@pxref{Program Arguments}). + +@comment argp.h +@comment GNU +@deftypefun {error_t} argp_parse (const struct argp *@var{argp}, @w{int @var{argc}, char **@var{argv}}, @w{unsigned @var{flags}}, @w{int *@var{arg_index}}, @w{void *@var{input}}) +The @code{argp_parse} function parses the arguments in in @var{argv}, of +length @var{argc}, using the argp parser @var{argp} (@pxref{Argp +Parsers}); a value of zero is the same as a @code{struct argp} +containing all zeros. @var{flags} is a set of flag bits that modify the +parsing behavior (@pxref{Argp Flags}). @var{input} is passed through to +the argp parser @var{argp}, and has meaning defined by it; a typical +usage is to pass a pointer to a structure which can be used for +specifying parameters to the parser and passing back results from it. + +Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included +in @var{flags}, calling @code{argp_parse} may result in the program +exiting---for instance when an unknown option is encountered. +@xref{Program Termination}. + +The return value is zero for successful parsing, or a unix error code +(@pxref{Error Codes}) if an error was detected. Different argp parsers +may return arbitrary error codes, but standard ones are @code{ENOMEM} if +a memory allocation error occurred, or @code{EINVAL} if an unknown option +or option argument was encountered. +@end deftypefun + +@menu +* Globals: Argp Global Variables. Global argp parameters. +* Parsers: Argp Parsers. Defining parsers for use with @code{argp_parse}. +* Flags: Argp Flags. Flags that modify the behavior of @code{argp_parse}. +* Help: Argp Help. Printing help messages when not parsing. +* Examples: Argp Examples. Simple examples of programs using argp. +* Customization: Argp User Customization. + Users may control the @samp{--help} output format. +@end menu + +@node Argp Global Variables, Argp Parsers, , Argp +@subsection Argp Global Variables + +These variables make it very easy for every user program to implement +the @samp{--version} option and provide a bug-reporting address in the +@samp{--help} output (which is implemented by argp regardless). + +@comment argp.h +@comment GNU +@deftypevar {const char *} argp_program_version +If defined or set by the user program to a non-zero value, then a +@samp{--version} option is added when parsing with @code{argp_parse} +(unless the @code{ARGP_NO_HELP} flag is used), which will print this +string followed by a newline and exit (unless the @code{ARGP_NO_EXIT} +flag is used). +@end deftypevar + +@comment argp.h +@comment GNU +@deftypevar {const char *} argp_program_bug_address +If defined or set by the user program to a non-zero value, +@code{argp_program_bug_address} should point to string that is the +bug-reporting address for the program. It will be printed at the end of +the standard output for the @samp{--help} option, embedded in a sentence +that says something like @samp{Report bugs to @var{address}.}. +@end deftypevar + +@need 1500 +@comment argp.h +@comment GNU +@defvar argp_program_version_hook +If defined or set by the user program to a non-zero value, then a +@samp{--version} option is added when parsing with @code{argp_parse} +(unless the @code{ARGP_NO_HELP} flag is used), which calls this function +to print the version, and then exits with a status of 0 (unless the +@code{ARGP_NO_EXIT} flag is used). It should point to a function with +the following type signature: + +@smallexample +void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state}) +@end smallexample + +@noindent +@xref{Argp Parsing State}, for an explanation of @var{state}. + +This variable takes precedent over @code{argp_program_version}, and is +useful if a program has version information that cannot be easily +specified as a simple string. +@end defvar + +@comment argp.h +@comment GNU +@deftypevar error_t argp_err_exit_status +The exit status that argp will use when exiting due to a parsing error. +If not defined or set by the user program, this defaults to +@code{EX_USAGE} from @file{<sysexits.h>}. +@end deftypevar + +@node Argp Parsers, Argp Flags, Argp Global Variables, Argp +@subsection Specifying Argp Parsers + +The first argument to the @code{argp_parse} function is a pointer to a +@code{struct argp}, which known as an @dfn{argp parser}: + +@comment argp.h +@comment GNU +@deftp {Data Type} {struct argp} +This structure specifies how to parse a given set of options and +arguments, perhaps in conjunction with other argp parsers. It has the +following fields: + +@table @code +@item const struct argp_option *options +A pointer to a vector of @code{argp_option} structures specifying which +options this argp parser understands; it may be zero if there are no +options at all. @xref{Argp Option Vectors}. + +@item argp_parser_t parser +A pointer to a function that defines actions for this parser; it is +called for each option parsed, and at other well-defined points in the +parsing process. A value of zero is the same as a pointer to a +function that always returns @code{ARGP_ERR_UNKNOWN}. +@xref{Argp Parser Functions}. + +@item const char *args_doc +If non-zero, a string describing what non-option arguments are wanted by +this parser; it is only used to print the @samp{Usage:} message. If it +contains newlines, the strings separated by them are considered +alternative usage patterns, and printed on separate lines (lines after +the first are prefix by @samp{ or: } instead of @samp{Usage:}). + +@item const char *doc +If non-zero, a string containing extra text to be printed before and +after the options in a long help message, with the two sections +separated by a vertical tab (@code{'\v'}, @code{'\013'}) character. By +convention, the documentation before the options is just a short string +saying what the program does, and that afterwards is longer, describing +the behavior in more detail. + +@item const struct argp_child *children +A pointer to a vector of @code{argp_children} structures specifying +additional argp parsers that should be combined with this one. +@xref{Argp Children}. + +@item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input}) +If non-zero, a pointer to a function to filter the output of help +messages. @xref{Argp Help Filtering}. +@end table +@end deftp + +The @code{options}, @code{parser}, @code{args_doc}, and @code{doc} +fields are usually all that are needed. If an argp parser is defined as +an initialized C variable, only the used fields need be specified in in +the initializer---the rest will default to zero due to the way C +structure initialization works (this fact is exploited for most argp +structures, grouping the most-used fields near the beginning, so that +unused fields can simply be left unspecified). + +@menu +* Options: Argp Option Vectors. Specifying options in an argp parser. +* Argp Parser Functions:: Defining actions for an argp parser. +* Children: Argp Children. Combining multiple argp parsers. +* Help Filtering: Argp Help Filtering. Customizing help output for an argp parser. +@end menu + +@node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers +@subsection Specifying Options in an Argp Parser + +The @code{options} field in a @code{struct argp} points to a vector of +@code{struct argp_option} structures, each of which specifies an option +that argp parser supports (actually, sometimes multiple entries may used +for a single option if it has many names). It should be terminated by +an entry with zero in all fields (note that when using an initialized C +array for options, writing @code{@{ 0 @}} is enough to achieve this). + +@comment argp.h +@comment GNU +@deftp {Data Type} {struct argp_option} +This structure specifies a single option that an argp parser +understands, and how to parse and document it. It has the following fields: + +@table @code +@item const char *name +The long name for this option, corresponding to the long option +@samp{--@var{name}}; this field can be zero if this option only has a +short name. To specify multiple names for an option, additional entries +may follow this one, with the @code{OPTION_ALIAS} flag set (@pxref{Argp +Option Flags}). + +@item int key +The integer key that is provided to the argp parser's parsing function +when this option is being parsed. Also, if @var{key} has a value that +is a printable @sc{ascii} character (i.e., @code{isascii (@var{key})} is +true), it @emph{also} specifies a short option @samp{-@var{char}}, where +@var{char} is the @sc{ascii} character with the code @var{key}. + +@item const char *arg +If non-zero, this is the name of an argument associated with this +option, which must be provided (e.g., with the +@samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}} +syntaxes) unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp Option +Flags}) is set, in which case it @emph{may} be provided. + +@item int flags +Flags associated with this option (some of which are referred to above). +@xref{Argp Option Flags}. + +@item const char *doc +A documentation string for this option, for printing in help messages. + +If both the @code{name} and @code{key} fields are zero, this string +will be printed out-dented from the normal option column, making it +useful as a group header (it will be the first thing printed in its +group); in this usage, it's conventional to end the string with a +@samp{:} character. + +@item int group +The group this option is in. + +In a long help message, options are sorted alphabetically within each +group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n}, +-@var{m}, @dots{}, -2, -1. Every entry in an options array with this +field 0 will inherit the group number of the previous entry, or zero if +it's the first one, unless its a group header (@code{name} and +@code{key} fields both zero), in which case, the previous entry + 1 is +the default. Automagic options such as @samp{--help} are put into group +-1. + +Note that because of C structure initialization rules, this field +often need not be specified, because 0 is the right value. +@end table +@end deftp + +@menu +* Flags: Argp Option Flags. Flags for options. +@end menu + +@node Argp Option Flags, , , Argp Option Vectors +@subsubsection Flags for Argp Options + +The following flags may be or'd together in the @code{flags} field of a +@code{struct argp_option}, and control various aspects of how that +option is parsed or displayed in help messages: + +@vtable @code +@comment argp.h +@comment GNU +@item OPTION_ARG_OPTIONAL +The argument associated with this option is optional. + +@comment argp.h +@comment GNU +@item OPTION_HIDDEN +This option isn't displayed in any help messages. + +@comment argp.h +@comment GNU +@item OPTION_ALIAS +This option is an alias for the closest previous non-alias option. This +means that it will be displayed in the same help entry, and will inherit +fields other than @code{name} and @code{key} from the aliased option. + +@comment argp.h +@comment GNU +@item OPTION_DOC +This option isn't actually an option (and so should be ignored by the +actual option parser), but rather an arbitrary piece of documentation +that should be displayed in much the same manner as the options (known +as a @dfn{documentation option}). + +If this flag is set, then the option @code{name} field is displayed +unmodified (e.g., no @samp{--} prefix is added) at the left-margin +(where a @emph{short} option would normally be displayed), and the +documentation string in the normal place. For purposes of sorting, any +leading whitespace and punctuation is ignored, except that if the first +non-whitespace character is not @samp{-}, this entry is displayed after +all options (and @code{OPTION_DOC} entries with a leading @samp{-}) in +the same group. + +@comment argp.h +@comment GNU +@item OPTION_NO_USAGE +This option shouldn't be included in `long' usage messages (but is still +included in help messages). This is mainly intended for options that +are completely documented in an argp's @code{args_doc} field +(@pxref{Argp Parsers}), in which case including the option +in the generic usage list would be redundant. + +For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the +@samp{-x} option's purpose is to distinguish these two cases, @samp{-x} +should probably be marked @code{OPTION_NO_USAGE}. +@end vtable + +@node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers +@subsection Argp Parser Functions + +The function pointed to by the @code{parser} field in a @code{struct +argp} (@pxref{Argp Parsers}) defines what actions take place in response +to each option or argument that is parsed, and is also used as a hook, +to allow a parser to do something at certain other points during +parsing. + +@need 2000 +Argp parser functions have the following type signature: + +@cindex argp parser functions +@smallexample +error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state}) +@end smallexample + +@noindent +where the arguments are as follows: + +@table @var +@item key +For each option that is parsed, @var{parser} is called with a value of +@var{key} from that option's @code{key} field in the option vector +(@pxref{Argp Option Vectors}). @var{parser} is also called at other +times with special reserved keys, such as @code{ARGP_KEY_ARG} for +non-option arguments. @xref{Argp Special Keys}. + +@item arg +If @var{key} is an option, @var{arg} is the value given for it, or zero +if no value was specified. Only options that have a non-zero @code{arg} +field can ever have a value, and those must @emph{always} have a value, +unless the @code{OPTION_ARG_OPTIONAL} flag was specified (if the input +being parsed specifies a value for an option that doesn't allow one, an +error results before @var{parser} ever gets called). + +If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option argument; +other special keys always have a zero @var{arg}. + +@item state +@var{state} points to a @code{struct argp_state}, containing useful +information about the current parsing state for use by @var{parser}. +@xref{Argp Parsing State}. +@end table + +When @var{parser} is called, it should perform whatever action is +appropriate for @var{key}, and return either @code{0} for success, +@code{ARGP_ERR_UNKNOWN}, if the value of @var{key} is not handled by +this parser function, or a unix error code if a real error occurred +(@pxref{Error Codes}). + +@comment argp.h +@comment GNU +@deftypevr Macro int ARGP_ERR_UNKNOWN +Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any +@var{key} value they do not recognize, or for non-option arguments +(@code{@var{key} == ARGP_KEY_ARG}) that they do not which to handle. +@end deftypevr + +@need 3000 +A typical parser function uses a switch statement on @var{key}: + +@smallexample +error_t +parse_opt (int key, char *arg, struct argp_state *state) +@{ + switch (key) + @{ + case @var{option_key}: + @var{action} + break; + @dots{} + default: + return ARGP_ERR_UNKNOWN; + @} + return 0; +@} +@end smallexample + +@menu +* Keys: Argp Special Keys. Special values for the @var{key} argument. +* State: Argp Parsing State. What the @var{state} argument refers to. +* Functions: Argp Helper Functions. Functions to help during argp parsing. +@end menu + +@node Argp Special Keys, Argp Parsing State, , Argp Parser Functions +@subsubsection Special Keys for Argp Parser Functions + +In addition to key values corresponding to user options, the @var{key} +argument to argp parser functions may have a number of other special +values (@var{arg} and @var{state} refer to parser function arguments; +@pxref{Argp Parser Functions}): + +@vtable @code +@comment argp.h +@comment GNU +@item ARGP_KEY_ARG +This is not an option at all, but rather a command line argument, whose +value is pointed to by @var{arg}. + +When there are multiple parser functions (due to argp parsers being +combined), it's impossible to know which one wants to handle an +argument, so each is called in turn, until one returns 0 or an error +other than @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one, +@code{argp_parse} immediately returns success, without parsing any more +arguments. + +Once a parser function returns success for this key, that fact is +recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be used. +@emph{However}, if while processing the argument, a parser function +decrements the @code{next} field of its @var{state} argument, the option +won't be considered processed; this is to allow you to actually modify +the argument (perhaps into an option), and have it processed again. + +@comment argp.h +@comment GNU +@item ARGP_KEY_END +There are no more command line arguments at all. + +@comment argp.h +@comment GNU +@item ARGP_KEY_NO_ARGS +Because it's common to want to do some special processing if there +aren't any non-option args, parser functions are called with this key if +they didn't successfully process any non-option arguments. Called just +before @code{ARGP_KEY_END} (where more general validity checks on +previously parsed arguments can take place). + +@comment argp.h +@comment GNU +@item ARGP_KEY_INIT +Passed in before any parsing is done. Afterwards, the values of each +element of the @code{child_input} field of @var{state}, if any, are +copied to each child's state to be the initial value of the @code{input} +when @emph{their} parsers are called. + +@comment argp.h +@comment GNU +@item ARGP_KEY_SUCCESS +Passed in when parsing has successfully been completed (even if there are +still arguments remaining). + +@comment argp.h +@comment GNU +@item ARGP_KEY_ERROR +Passed in if an error has occurred, and parsing terminated (in which case +a call with a key of @code{ARGP_KEY_SUCCESS} is never made). + +@comment argp.h +@comment GNU +@item ARGP_KEY_FINI +The final key ever seen by any parser (even after +@code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}). Any resources +allocated by @code{ARGP_KEY_INIT} may be freed here (although sometimes +certain resources allocated there are to be returned to the caller after +a successful parse; in that case, those particular resources can be +freed in the @code{ARGP_KEY_ERROR} case). +@end vtable + +In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser +functions, and @code{ARGP_KEY_FINI} the last (unless an error was +returned by the parser for @code{ARGP_KEY_INIT}). Other keys can occur +in one the following orders (@var{opt} refers to an arbitrary option +key): + +@table @asis +@item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} +The arguments being parsed contained no non-option arguments at all. + +@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} +All non-option arguments were successfully handled by a parser function +(there may be multiple parser functions if multiple argp parsers were +combined). + +@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS} +Some non-option argument was unrecognized. + +This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN} +for an argument, in which case parsing stops at that argument. If a +non-zero value for @var{arg_index} was passed to @code{argp_parse}, the +index of this argument is returned in it, otherwise an error occurs. +@end table + +If an error occurs (either detected by argp, or because a parser +function returned an error value), then each parser is called with +@code{ARGP_KEY_ERROR}, and no further calls are made except the final +call with @code{ARGP_KEY_FINI}. + +@node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions +@subsubsection Functions For Use in Argp Parsers + +Argp provides a number of functions for the user of argp parser +functions (@pxref{Argp Parser Functions}), mostly for producing error +messages. These take as their first argument the @var{state} argument +to the parser function (@pxref{Argp Parsing State}). + +@cindex usage messages, in argp +@comment argp.h +@comment GNU +@deftypefun void argp_usage (const struct argp_state *@var{state}) +Output the standard usage message for the argp parser referred to by +@var{state} to @code{@var{state}->err_stream} and terminate the program +with @code{exit (argp_err_exit_status)} (@pxref{Argp Global Variables}). +@end deftypefun + +@cindex syntax error messages, in argp +@comment argp.h +@comment GNU +@deftypefun void argp_error (const struct argp_state *@var{state}, @w{const char *@var{fmt}, @dots{}}) +Print the printf format string @var{fmt} and following args, preceded by +the program name and @samp{:}, and followed by a @w{@samp{Try @dots{} +--help}} message, and terminate the program with an exit status of +@code{argp_err_exit_status} (@pxref{Argp Global Variables}). +@end deftypefun + +@cindex error messages, in argp +@comment argp.h +@comment GNU +@deftypefun void argp_failure (const struct argp_state *@var{state}, @w{int @var{status}, int @var{errnum},} @w{const char *@var{fmt}, @dots{}}) +Similarly to the standard gnu error-reporting function @code{error}, +print the printf format string @var{fmt} and following args, preceded by +the program name and @samp{:}, and followed by the standard unix error +text for @var{errnum} if it is non-zero; then if @var{status} is +non-zero, terminate the program with that as its exit status. + +The difference between this function and @code{argp_error} is that +@code{argp_error} is for @emph{parsing errors}, whereas +@code{argp_failure} is for other problems that occur during parsing but +don't reflect a syntactic problem with the input---such as illegal +values for options, bad phase of the moon, etc. +@end deftypefun + +@comment argp.h +@comment GNU +@deftypefun void argp_state_help (const struct argp_state *@var{state}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}}) +Output a help message for the argp parser referred to by @var{state} to +@var{stream}. The @var{flags} argument determines what sort of help +message is produced. @xref{Argp Help Flags}. +@end deftypefun + +Error output is sent to @code{@var{state}->err_stream}, and the program +name printed is @code{@var{state}->name}. + +The output or program termination behavior of these functions may be +suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags, +respectively, were passed to @code{argp_parse}. @xref{Argp Flags}. + +This behavior is useful if an argp parser is exported for use by other +programs (e.g., by a library), and may be used in a context where it is +not desirable to terminate the program in response to parsing errors. +In argp parsers intended for such general use, calls to any of these +functions should be followed by code return of an appropriate error code +for the case where the program @emph{doesn't} terminate; for example: + +@smallexample +if (@var{bad argument syntax}) + @{ + argp_usage (@var{state}); + return EINVAL; + @} +@end smallexample + +@noindent +If it's known that a parser function will only be used when +@code{ARGP_NO_EXIT} is not set, the return may be omitted. + +@node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions +@subsubsection Argp Parsing State + +The third argument to argp parser functions (@pxref{Argp Parser +Functions}) is a pointer to a @code{struct argp_state}, which contains +information about the state of the option parsing. + +@comment argp.h +@comment GNU +@deftp {Data Type} {struct argp_state} +This structure has the following fields, which may be modified as noted: + +@table @code +@item const struct argp *const root_argp +The top level argp parser being parsed. Note that this is often +@emph{not} the same @code{struct argp} passed into @code{argp_parse} by +the invoking program (@pxref{Argp}), but instead an internal argp parser +that contains options implemented by @code{argp_parse} itself (such as +@samp{--help}). + +@item int argc +@itemx char **argv +The argument vector being parsed. May be modified. + +@item int next +The index in @code{argv} of the next argument to be parsed. May be modified. + +One way to consume all remaining arguments in the input is to set +@code{@var{state}->next = @var{state}->argc} (perhaps after recording +the value of the @code{next} field to find the consumed arguments). +Also, you can cause the current option to be re-parsed by decrementing +this field, and then modifying +@code{@var{state}->argv[@var{state}->next]} to be the option that should +be reexamined. + +@item unsigned flags +The flags supplied to @code{argp_parse}. May be modified, although some +flags may only take effect when @code{argp_parse} is first invoked. +@xref{Argp Flags}. + +@item unsigned arg_num +While calling a parsing function with the @var{key} argument +@code{ARGP_KEY_ARG}, this is the number of the current arg, starting at +0, and incremented after each such call returns. At all other times, +this is the number of such arguments that have been processed. + +@item int quoted +If non-zero, the index in @code{argv} of the first argument following a +special @samp{--} argument (which prevents anything following being +interpreted as an option). Only set once argument parsing has proceeded +past this point. + +@item void *input +An arbitrary pointer passed in from the caller of @code{argp_parse}, in +the @var{input} argument. + +@item void **child_inputs +Values to pass to child parsers. This vector will be the same length as +the number of children in the current parser, and each child parser will +be given the value of @code{@var{state}->child_inputs[@var{i}]} as +@emph{its} @code{@var{state}->input} field, where @var{i} is the index +of the child in the this parser's @code{children} field. @xref{Argp +Children}. + +@item void *hook +For the parser function's use. Initialized to 0, but otherwise ignored +by argp. + +@item char *name +The name used when printing messages. This is initialized to +@code{argv[0]}, or @code{program_invocation_name} if that is +unavailable. + +@item FILE *err_stream +@itemx FILE *out_stream +Stdio streams used when argp prints something; error messages are +printed to @code{err_stream}, and all other output (such as +@samp{--help} output) to @code{out_stream}. These are initialized to +@code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}). + +@item void *pstate +Private, for use by the argp implementation. +@end table +@end deftp + +@node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers +@subsection Combining Multiple Argp Parsers + +The @code{children} field in a @code{struct argp} allows other argp +parsers to be combined with the referencing one to parse a single set of +arguments. It should point to a vector of @code{struct argp_child}, +terminated by an entry having a value of zero in the @code{argp} field. + +Where conflicts between combined parsers arise (for instance, if two +specify an option with the same name), they are resolved in favor of +the parent argp parsers, or earlier argp parsers in the list of children. + +@comment argp.h +@comment GNU +@deftp {Data Type} {struct argp_child} +An entry in the list of subsidiary argp parsers pointed to by the +@code{children} field in a @code{struct argp}. The fields are as follows: + +@table @code +@item const struct argp *argp +The child argp parser, or zero to end the list. + +@item int flags +Flags for this child. + +@item const char *header +If non-zero, an optional header to be printed in help output before the +child options. As a side-effect, a non-zero value forces the child +options to be grouped together; to achieve this effect without actually +printing a header string, use a value of @code{""}. As with header +strings specified in an option entry, the value conventionally has +@samp{:} as the last character. @xref{Argp Option Vectors}. + +@item int group +Where to group the child options relative to the other (`consolidated') +options in the parent argp parser. The values are the same as the +@code{group} field in @code{struct argp_option} (@pxref{Argp Option +Vectors}), but all child-groupings follow parent options at a particular +group level. If both this field and @code{header} are zero, then the +child's options aren't grouped together at all, but rather merged with +the parent options (merging the child's grouping levels with the +parents). +@end table +@end deftp + +@node Argp Flags, Argp Help, Argp Parsers, Argp +@subsection Flags for @code{argp_parse} + +The default behavior of @code{argp_parse} is designed to be convenient +for the most common case of parsing program command line argument. To +modify these defaults, the following flags may be or'd together in the +@var{flags} argument to @code{argp_parse}: + +@vtable @code +@comment argp.h +@comment GNU +@item ARGP_PARSE_ARGV0 +Don't ignore the first element of the @var{argv} argument to +@code{argp_parse}. Normally (and always unless @code{ARGP_NO_ERRS} is +set) the first element of the argument vector is skipped for option +parsing purposes, as it corresponds to the program name in a command +line. + +@comment argp.h +@comment GNU +@item ARGP_NO_ERRS +Don't print error messages for unknown options to @code{stderr}; unless +this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]} +is used as the program name in the error messages. This flag implies +@code{ARGP_NO_EXIT} (on the assumption that silent exiting upon errors +is bad behaviour). + +@comment argp.h +@comment GNU +@item ARGP_NO_ARGS +Don't parse any non-option args. Normally non-option args are parsed by +calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the +actual arg as the value. This flag needn't normally be set, as the +normal behavior is to stop parsing as soon as some argument isn't +accepted by a parsing function. @xref{Argp Parser Functions}. + +@comment argp.h +@comment GNU +@item ARGP_IN_ORDER +Parse options and arguments in the same order they occur on the command +line---normally they're rearranged so that all options come first + +@comment argp.h +@comment GNU +@item ARGP_NO_HELP +Don't provide the standard long option @samp{--help}, which ordinarily +causes usage and option help information to be output to @code{stdout}, +and @code{exit (0)} called. + +@comment argp.h +@comment GNU +@item ARGP_NO_EXIT +Don't exit on errors (they may still result in error messages). + +@comment argp.h +@comment GNU +@item ARGP_LONG_ONLY +Use the gnu getopt `long-only' rules for parsing arguments. + +@comment argp.h +@comment GNU +@item ARGP_SILENT +Turns off any message-printing/exiting options, specifically +@code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}. +@end vtable + +@node Argp Help Filtering, , Argp Children, Argp Parsers +@need 2000 +@subsection Customizing Argp Help Output + +The @code{help_filter} field in a a @code{struct argp} is a pointer to a +function to filter the text of help messages before displaying them. +They have a function signature like: + +@smallexample +char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input}) +@end smallexample + +@noindent +where @var{key} is either a key from an option, in which case @var{text} +is that option's help text (@pxref{Argp Option Vectors}), or one of the +special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing +which other help text @var{text} is (@pxref{Argp Help Filter Keys}). + +The function should return either @var{text}, if it should be used +as-is, a replacement string, which should be allocated using +@code{malloc}, and will be freed by argp, or zero, meaning `print +nothing'. The value of @var{text} supplied is @emph{after} any +translation has been done, so if any of the replacement text also needs +translation, that should be done by the filter function. @var{input} is +either the input supplied to @code{argp_parse}, or zero, if +@code{argp_help} was called directly by the user. + +@menu +* Keys: Argp Help Filter Keys. Special @var{key} values for help filter functions. +@end menu + +@node Argp Help Filter Keys, , , Argp Help Filtering +@subsubsection Special Keys for Argp Help Filter Functions + +The following special values may be passed to an argp help filter +function as the first argument, in addition to key values for user +options, and specify which help text the @var{text} argument contains: + +@vtable @code +@comment argp.h +@comment GNU +@item ARGP_KEY_HELP_PRE_DOC +Help text preceding options. + +@comment argp.h +@comment GNU +@item ARGP_KEY_HELP_POST_DOC +Help text following options. + +@comment argp.h +@comment GNU +@item ARGP_KEY_HELP_HEADER +Option header string. + +@comment argp.h +@comment GNU +@item ARGP_KEY_HELP_EXTRA +After all other documentation; @var{text} is zero for this key. + +@comment argp.h +@comment GNU +@item ARGP_KEY_HELP_DUP_ARGS_NOTE +The explanatory note emitted when duplicate option arguments have been +suppressed. + +@comment argp.h +@comment GNU +@item ARGP_KEY_HELP_ARGS_DOC +The argument doc string (the @code{args_doc} field from the argp parser; +@pxref{Argp Parsers}). +@end vtable + +@node Argp Help, Argp Examples, Argp Flags, Argp +@subsection The @code{argp_help} Function + +Normally programs using argp need not worry too much about printing +argument-usage-type help messages, because the standard @samp{--help} +option is handled automatically by argp, and the typical error cases can +be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp +Helper Functions}). + +However, if it's desirable to print a standard help message in some +context other than parsing the program options, argp offers the +@code{argp_help} interface. + +@comment argp.h +@comment GNU +@deftypefun void argp_help (const struct argp *@var{argp}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}}, @w{char *@var{name}}) +Output a help message for the argp parser @var{argp} to @var{stream}. +What sort of messages is printed is determined by @var{flags}. + +Any options such as @samp{--help} that are implemented automatically by +argp itself will @emph{not} be present in the help output; for this +reason, it is better to use @code{argp_state_help} if calling from +within an argp parser function. @xref{Argp Helper Functions}. +@end deftypefun + +@menu +* Flags: Argp Help Flags. Specifying what sort of help message to print. +@end menu + +@node Argp Help Flags, , , Argp Help +@subsection Flags for the @code{argp_help} Function + +When calling @code{argp_help} (@pxref{Argp Help}), or +@code{argp_state_help} (@pxref{Argp Helper Functions}), exactly what is +output is determined by the @var{flags} argument, which should consist +of any of the following flags, or'd together: + +@vtable @code +@item ARGP_HELP_USAGE +A unix @samp{Usage:} message that explicitly lists all options. + +@item ARGP_HELP_SHORT_USAGE +A unix @samp{Usage:} message that displays only an appropriate +placeholder to indicate where the options go; useful for showing +the non-option argument syntax. + +@item ARGP_HELP_SEE +A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the +program name and @samp{--help}. + +@item ARGP_HELP_LONG +A verbose option help message that gives each option understood along +with its documentation string. + +@item ARGP_HELP_PRE_DOC +The part of the argp parser doc string that precedes the verbose option help. + +@item ARGP_HELP_POST_DOC +The part of the argp parser doc string that follows the verbose option help. + +@item ARGP_HELP_DOC +@code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)} + +@item ARGP_HELP_BUG_ADDR +A message saying where to report bugs for this program, if the +@code{argp_program_bug_address} variable contains one. + +@item ARGP_HELP_LONG_ONLY +Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode. +@end vtable + +The following flags are only understood when used with +@code{argp_state_help}, and control whether the function returns after +printing its output, or terminates the program: + +@vtable @code +@item ARGP_HELP_EXIT_ERR +Terminate the program with @code{exit (argp_err_exit_status)}. + +@item ARGP_HELP_EXIT_OK +Terminate the program with @code{exit (0)}. +@end vtable + +The following flags are combinations of the basic ones for printing +standard messages: + +@vtable @code +@item ARGP_HELP_STD_ERR +Assuming an error message for a parsing error has already printed, +prints a note on how to get help, and terminates the program with an +error. + +@item ARGP_HELP_STD_USAGE +Prints a standard usage message and terminates the program with an +error. This is used when no more specific error message is appropriate. + +@item ARGP_HELP_STD_HELP +Prints the standard response for a @samp{--help} option, and terminates +the program successfully. +@end vtable + +@node Argp Examples, Argp User Customization, Argp Help, Argp +@subsection Argp Examples + +These example programs demonstrate the basic usage of argp. + +@menu +* 1: Argp Example 1. A minimal program using argp. +* 2: Argp Example 2. A program using only default options. +* 3: Argp Example 3. A simple program with user options. +* 4: Argp Example 4. Combining multiple argp parsers. +@end menu + +@node Argp Example 1, Argp Example 2, , Argp Examples +@subsubsection A Minimal Program Using Argp + +This is (probably) the smallest possible program that uses argp. +It won't do much except give an error messages and exit when there are any +arguments, and print a (rather pointless) message for @samp{--help}. + +@smallexample +@include argp-ex1.c.texi +@end smallexample + +@node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples +@subsubsection A Program Using Argp with Only Default Options + +This program doesn't use any options or arguments, but uses argp to be +compliant with the GNU standard command line format. + +In addition to making sure no arguments are given, and implementing a +@samp{--help} option, this example will have a @samp{--version} option, +and will put the given documentation string and bug address in the +@samp{--help} output, as per GNU standards. + +The variable @code{argp} contains the argument parser specification; +adding fields to this structure is the way most parameters are passed to +@code{argp_parse} (the first three fields are usually used, but not in +this small program). There are also two global variables that argp +knows about defined here, @code{argp_program_version} and +@code{argp_program_bug_address} (they are global variables because they +will almost always be constant for a given program, even if it uses +different argument parsers for various tasks). + +@smallexample +@include argp-ex2.c.texi +@end smallexample + +@node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples +@subsubsection A Program Using Argp with User Options + +This program uses the same features as example 2, and adds user options +and arguments. + +We now use the first four fields in @code{argp} (@pxref{Argp Parsers}), +and specifies @code{parse_opt} as the parser function (@pxref{Argp +Parser Functions}). + +Note that in this example, @code{main} uses a structure to communicate +with the @code{parse_opt} function, a pointer to which it passes in the +@code{input} argument to @code{argp_parse} (@pxref{Argp}), and is +retrieved by @code{parse_opt} through the @code{input} field in its +@code{state} argument (@pxref{Argp Parsing State}). Of course, it's +also possible to use global variables instead, but using a structure +like this is somewhat more flexible and clean. + +@smallexample +@include argp-ex3.c.texi +@end smallexample + +@node Argp Example 4, , Argp Example 3, Argp Examples +@subsubsection A Program Using Multiple Combined Argp Parsers + +This program uses the same features as example 3, but has more options, +and somewhat more structure in the @samp{--help} output. It also shows +how you can `steal' the remainder of the input arguments past a certain +point, for programs that accept a list of items, and the special +@var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no +non-option arguments were supplied to the program (@pxref{Argp Special +Keys}). + +For structuring the help output, two features are used: @emph{headers}, +which are entries in the options vector (@pxref{Argp Option Vectors}) +with the first four fields being zero, and a two part documentation +string (in the variable @code{doc}), which allows documentation both +before and after the options (@pxref{Argp Parsers}); the +two parts of @code{doc} are separated by a vertical-tab character +(@code{'\v'}, or @code{'\013'}). By convention, the documentation +before the options is just a short string saying what the program does, +and that afterwards is longer, describing the behavior in more detail. +All documentation strings are automatically filled for output, although +newlines may be included to force a line break at a particular point. +All documentation strings are also passed to the @code{gettext} +function, for possible translation into the current locale. + +@smallexample +@include argp-ex4.c.texi +@end smallexample + +@node Argp User Customization, , Argp Examples, Argp +@subsection Argp User Customization + +@cindex ARGP_HELP_FMT environment variable +The way formatting of argp @samp{--help} output may be controlled to +some extent by a program's users, by setting the @code{ARGP_HELP_FMT} +environment variable to a comma-separated list (whitespace is ignored) +of the following tokens: + +@table @samp +@item dup-args +@itemx no-dup-args +Turn @dfn{duplicate-argument-mode} on or off. In duplicate argument +mode, if an option which accepts an argument has multiple names, the +argument is shown for each name; otherwise, it is only shown for the +first long option, and a note is emitted later so the user knows that it +applies to the other names as well. The default is @samp{no-dup-args}, +which is less consistent, but prettier. + +@item dup-args-note +@item no-dup-args-note +Enable or disable the note informing the user of suppressed option +argument duplication. The default is @samp{dup-args-note}. + +@item short-opt-col=@var{n} +Show the first short option in column @var{n} (default 2). + +@item long-opt-col=@var{n} +Show the first long option in column @var{n} (default 6). + +@item doc-opt-col=@var{n} +Show `documentation options' (@pxref{Argp Option Flags}) in column +@var{n} (default 2). + +@item opt-doc-col=@var{n} +Show the documentation for options starting in column @var{n} (default 29). + +@item header-col=@var{n} +Indent group headers (which document groups of options) to column +@var{n} (default 1). + +@item usage-indent=@var{n} +Indent continuation lines in @samp{Usage:} messages to column @var{n} +(default 12). + +@item rmargin=@var{n} +Word wrap help output at or before column @var{n} (default 79). +@end table diff --git a/manual/getopt.texi b/manual/getopt.texi new file mode 100644 index 0000000000..8e1102f911 --- /dev/null +++ b/manual/getopt.texi @@ -0,0 +1,257 @@ +@node Getopt, Argp, , Parsing Program Arguments +@section Parsing program options using @code{getopt} + +The @code{getopt} and @code{getopt_long} functions automate some of the +chore involved in parsing typical unix command line options. + +@menu +* Using Getopt:: Using the @code{getopt} function. +* Example of Getopt:: An example of parsing options with @code{getopt}. +* Getopt Long Options:: GNU suggests utilities accept long-named + options; here is one way to do. +* Getopt Long Option Example:: An example of using @code{getopt_long}. +@end menu + +@node Using Getopt, Example of Getopt, , Getopt +@subsection Using the @code{getopt} function + +Here are the details about how to call the @code{getopt} function. To +use this facility, your program must include the header file +@file{unistd.h}. +@pindex unistd.h + +@comment unistd.h +@comment POSIX.2 +@deftypevar int opterr +If the value of this variable is nonzero, then @code{getopt} prints an +error message to the standard error stream if it encounters an unknown +option character or an option with a missing required argument. This is +the default behavior. If you set this variable to zero, @code{getopt} +does not print any messages, but it still returns the character @code{?} +to indicate an error. +@end deftypevar + +@comment unistd.h +@comment POSIX.2 +@deftypevar int optopt +When @code{getopt} encounters an unknown option character or an option +with a missing required argument, it stores that option character in +this variable. You can use this for providing your own diagnostic +messages. +@end deftypevar + +@comment unistd.h +@comment POSIX.2 +@deftypevar int optind +This variable is set by @code{getopt} to the index of the next element +of the @var{argv} array to be processed. Once @code{getopt} has found +all of the option arguments, you can use this variable to determine +where the remaining non-option arguments begin. The initial value of +this variable is @code{1}. +@end deftypevar + +@comment unistd.h +@comment POSIX.2 +@deftypevar {char *} optarg +This variable is set by @code{getopt} to point at the value of the +option argument, for those options that accept arguments. +@end deftypevar + +@comment unistd.h +@comment POSIX.2 +@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options}) +The @code{getopt} function gets the next option argument from the +argument list specified by the @var{argv} and @var{argc} arguments. +Normally these values come directly from the arguments received by +@code{main}. + +The @var{options} argument is a string that specifies the option +characters that are valid for this program. An option character in this +string can be followed by a colon (@samp{:}) to indicate that it takes a +required argument. + +If the @var{options} argument string begins with a hyphen (@samp{-}), this +is treated specially. It permits arguments that are not options to be +returned as if they were associated with option character @samp{\0}. + +The @code{getopt} function returns the option character for the next +command line option. When no more option arguments are available, it +returns @code{-1}. There may still be more non-option arguments; you +must compare the external variable @code{optind} against the @var{argc} +parameter to check this. + +If the option has an argument, @code{getopt} returns the argument by +storing it in the variable @var{optarg}. You don't ordinarily need to +copy the @code{optarg} string, since it is a pointer into the original +@var{argv} array, not into a static area that might be overwritten. + +If @code{getopt} finds an option character in @var{argv} that was not +included in @var{options}, or a missing option argument, it returns +@samp{?} and sets the external variable @code{optopt} to the actual +option character. If the first character of @var{options} is a colon +(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to +indicate a missing option argument. In addition, if the external +variable @code{opterr} is nonzero (which is the default), @code{getopt} +prints an error message. +@end deftypefun + +@node Example of Getopt +@subsection Example of Parsing Arguments with @code{getopt} + +Here is an example showing how @code{getopt} is typically used. The +key points to notice are: + +@itemize @bullet +@item +Normally, @code{getopt} is called in a loop. When @code{getopt} returns +@code{-1}, indicating no more options are present, the loop terminates. + +@item +A @code{switch} statement is used to dispatch on the return value from +@code{getopt}. In typical use, each case just sets a variable that +is used later in the program. + +@item +A second loop is used to process the remaining non-option arguments. +@end itemize + +@smallexample +@include testopt.c.texi +@end smallexample + +Here are some examples showing what this program prints with different +combinations of arguments: + +@smallexample +% testopt +aflag = 0, bflag = 0, cvalue = (null) + +% testopt -a -b +aflag = 1, bflag = 1, cvalue = (null) + +% testopt -ab +aflag = 1, bflag = 1, cvalue = (null) + +% testopt -c foo +aflag = 0, bflag = 0, cvalue = foo + +% testopt -cfoo +aflag = 0, bflag = 0, cvalue = foo + +% testopt arg1 +aflag = 0, bflag = 0, cvalue = (null) +Non-option argument arg1 + +% testopt -a arg1 +aflag = 1, bflag = 0, cvalue = (null) +Non-option argument arg1 + +% testopt -c foo arg1 +aflag = 0, bflag = 0, cvalue = foo +Non-option argument arg1 + +% testopt -a -- -b +aflag = 1, bflag = 0, cvalue = (null) +Non-option argument -b + +% testopt -a - +aflag = 1, bflag = 0, cvalue = (null) +Non-option argument - +@end smallexample + +@node Getopt Long Options +@subsection Parsing Long Options with @code{getopt_long} + +To accept GNU-style long options as well as single-character options, +use @code{getopt_long} instead of @code{getopt}. This function is +declared in @file{getopt.h}, not @file{unistd.h}. You should make every +program accept long options if it uses any options, for this takes +little extra work and helps beginners remember how to use the program. + +@comment getopt.h +@comment GNU +@deftp {Data Type} {struct option} +This structure describes a single long option name for the sake of +@code{getopt_long}. The argument @var{longopts} must be an array of +these structures, one for each long option. Terminate the array with an +element containing all zeros. + +The @code{struct option} structure has these fields: + +@table @code +@item const char *name +This field is the name of the option. It is a string. + +@item int has_arg +This field says whether the option takes an argument. It is an integer, +and there are three legitimate values: @w{@code{no_argument}}, +@code{required_argument} and @code{optional_argument}. + +@item int *flag +@itemx int val +These fields control how to report or act on the option when it occurs. + +If @code{flag} is a null pointer, then the @code{val} is a value which +identifies this option. Often these values are chosen to uniquely +identify particular long options. + +If @code{flag} is not a null pointer, it should be the address of an +@code{int} variable which is the flag for this option. The value in +@code{val} is the value to store in the flag to indicate that the option +was seen. +@end table +@end deftp + +@comment getopt.h +@comment GNU +@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr}) +Decode options from the vector @var{argv} (whose length is @var{argc}). +The argument @var{shortopts} describes the short options to accept, just as +it does in @code{getopt}. The argument @var{longopts} describes the long +options to accept (see above). + +When @code{getopt_long} encounters a short option, it does the same +thing that @code{getopt} would do: it returns the character code for the +option, and stores the options argument (if it has one) in @code{optarg}. + +When @code{getopt_long} encounters a long option, it takes actions based +on the @code{flag} and @code{val} fields of the definition of that +option. + +If @code{flag} is a null pointer, then @code{getopt_long} returns the +contents of @code{val} to indicate which option it found. You should +arrange distinct values in the @code{val} field for options with +different meanings, so you can decode these values after +@code{getopt_long} returns. If the long option is equivalent to a short +option, you can use the short option's character code in @code{val}. + +If @code{flag} is not a null pointer, that means this option should just +set a flag in the program. The flag is a variable of type @code{int} +that you define. Put the address of the flag in the @code{flag} field. +Put in the @code{val} field the value you would like this option to +store in the flag. In this case, @code{getopt_long} returns @code{0}. + +For any long option, @code{getopt_long} tells you the index in the array +@var{longopts} of the options definition, by storing it into +@code{*@var{indexptr}}. You can get the name of the option with +@code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among +long options either by the values in their @code{val} fields or by their +indices. You can also distinguish in this way among long options that +set flags. + +When a long option has an argument, @code{getopt_long} puts the argument +value in the variable @code{optarg} before returning. When the option +has no argument, the value in @code{optarg} is a null pointer. This is +how you can tell whether an optional argument was supplied. + +When @code{getopt_long} has no more options to handle, it returns +@code{-1}, and leaves in the variable @code{optind} the index in +@var{argv} of the next remaining argument. +@end deftypefun + +@node Getopt Long Option Example +@subsection Example of Parsing Long Options with @code{getopt_long} + +@smallexample +@include longopt.c.texi +@end smallexample diff --git a/manual/libc.texinfo b/manual/libc.texinfo index aa72be16e3..e821807a17 100644 --- a/manual/libc.texinfo +++ b/manual/libc.texinfo @@ -745,11 +745,14 @@ Process Startup and Termination Program Arguments * Argument Syntax:: By convention, options start with a hyphen. -* Parsing Options:: The @code{getopt} function. -* Example of Getopt:: An example of parsing options with @code{getopt}. -* Long Options:: GNU utilities should accept long-named options. - Here is how to do that. -* Long Option Example:: An example of using @code{getopt_long}. +* Parsing Program Arguments:: Ways to parse program options and arguments. + +Parsing Program Arguments + +* Getopt:: Parsing program options using @code{getopt}. +* Argp:: Parsing program options using @code{argp_parse}. +* Suboptions:: Some programs need more detailed options. +* Suboptions Example:: This shows how it could be done for @code{mount}. Environment Variables diff --git a/manual/maint.texi b/manual/maint.texi index 9c542a3ce3..654182e6e1 100644 --- a/manual/maint.texi +++ b/manual/maint.texi @@ -902,6 +902,10 @@ David Mosberger-Tang contributed the port to Linux/Alpha (@code{alpha-@var{anything}-linux}). @item +Miles Bader wrote the argp argument-parsing package, and the argz/envz +interfaces. + +@item Stephen R. van den Berg contributed a highly-optimized @code{strstr} function. @item diff --git a/manual/startup.texi b/manual/startup.texi index db6a4c8e32..e61a755456 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -64,12 +64,6 @@ is this null pointer. For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}. -If the syntax for the command line arguments to your program is simple -enough, you can simply pick the arguments off from @var{argv} by hand. -But unless your program takes a fixed number of arguments, or all of the -arguments are interpreted in the same way (as file names, for example), -you are usually better off using @code{getopt} to do the parsing. - In Unix systems you can define @code{main} a third way, using three arguments: @smallexample @@ -84,13 +78,7 @@ allow this three-argument form, so to be portable it is best to write @menu * Argument Syntax:: By convention, options start with a hyphen. -* Parsing Options:: The @code{getopt} function. -* Example of Getopt:: An example of parsing options with @code{getopt}. -* Long Options:: GNU suggests utilities accept long-named options. - Here is how to do that. -* Long Option Example:: An example of using @code{getopt_long}. -* Suboptions:: Some programs need more detailed options. -* Suboptions Example:: This shows how it could be done for @code{mount}. +* Parsing Program Arguments:: Ways to parse program options and arguments. @end menu @node Argument Syntax @@ -100,7 +88,8 @@ allow this three-argument form, so to be portable it is best to write @cindex command argument syntax POSIX recommends these conventions for command line arguments. -@code{getopt} (@pxref{Parsing Options}) makes it easy to implement them. +@code{getopt} (@pxref{Getopt}) and @code{argp_parse} (@pxref{Argp}) make +it easy to implement them. @itemize @bullet @item @@ -127,14 +116,14 @@ other words, the whitespace separating them is optional.) Thus, @item Options typically precede other non-option arguments. -The implementation of @code{getopt} in the GNU C library normally makes -it appear as if all the option arguments were specified before all the -non-option arguments for the purposes of parsing, even if the user of -your program intermixed option and non-option arguments. It does this -by reordering the elements of the @var{argv} array. This behavior is -nonstandard; if you want to suppress it, define the -@code{_POSIX_OPTION_ORDER} environment variable. @xref{Standard -Environment}. +The implementations of @code{getopt} and @code{argp_parse} in the GNU C +library normally make it appear as if all the option arguments were +specified before all the non-option arguments for the purposes of +parsing, even if the user of your program intermixed option and +non-option arguments. They do this by reordering the elements of the +@var{argv} array. This behavior is nonstandard; if you want to suppress +it, define the @code{_POSIX_OPTION_ORDER} environment variable. +@xref{Standard Environment}. @item The argument @samp{--} terminates all options; any following arguments @@ -164,255 +153,41 @@ accept an argument that is itself optional. Eventually, the GNU system will provide completion for long option names in the shell. -@node Parsing Options -@subsection Parsing Program Options +@node Parsing Program Arguments +@subsection Parsing Program Arguments + @cindex program arguments, parsing @cindex command arguments, parsing @cindex parsing program arguments +If the syntax for the command line arguments to your program is simple +enough, you can simply pick the arguments off from @var{argv} by hand. +But unless your program takes a fixed number of arguments, or all of the +arguments are interpreted in the same way (as file names, for example), +you are usually better off using @code{getopt} (@pxref{Getopt}) or +@code{argp_parse} (@pxref{Argp}) to do the parsing. -Here are the details about how to call the @code{getopt} function. To -use this facility, your program must include the header file -@file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.2 -@deftypevar int opterr -If the value of this variable is nonzero, then @code{getopt} prints an -error message to the standard error stream if it encounters an unknown -option character or an option with a missing required argument. This is -the default behavior. If you set this variable to zero, @code{getopt} -does not print any messages, but it still returns the character @code{?} -to indicate an error. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypevar int optopt -When @code{getopt} encounters an unknown option character or an option -with a missing required argument, it stores that option character in -this variable. You can use this for providing your own diagnostic -messages. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypevar int optind -This variable is set by @code{getopt} to the index of the next element -of the @var{argv} array to be processed. Once @code{getopt} has found -all of the option arguments, you can use this variable to determine -where the remaining non-option arguments begin. The initial value of -this variable is @code{1}. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypevar {char *} optarg -This variable is set by @code{getopt} to point at the value of the -option argument, for those options that accept arguments. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options}) -The @code{getopt} function gets the next option argument from the -argument list specified by the @var{argv} and @var{argc} arguments. -Normally these values come directly from the arguments received by -@code{main}. - -The @var{options} argument is a string that specifies the option -characters that are valid for this program. An option character in this -string can be followed by a colon (@samp{:}) to indicate that it takes a -required argument. - -If the @var{options} argument string begins with a hyphen (@samp{-}), this -is treated specially. It permits arguments that are not options to be -returned as if they were associated with option character @samp{\0}. - -The @code{getopt} function returns the option character for the next -command line option. When no more option arguments are available, it -returns @code{-1}. There may still be more non-option arguments; you -must compare the external variable @code{optind} against the @var{argc} -parameter to check this. - -If the option has an argument, @code{getopt} returns the argument by -storing it in the variable @var{optarg}. You don't ordinarily need to -copy the @code{optarg} string, since it is a pointer into the original -@var{argv} array, not into a static area that might be overwritten. - -If @code{getopt} finds an option character in @var{argv} that was not -included in @var{options}, or a missing option argument, it returns -@samp{?} and sets the external variable @code{optopt} to the actual -option character. If the first character of @var{options} is a colon -(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to -indicate a missing option argument. In addition, if the external -variable @code{opterr} is nonzero (which is the default), @code{getopt} -prints an error message. -@end deftypefun - -@node Example of Getopt -@subsection Example of Parsing Arguments with @code{getopt} - -Here is an example showing how @code{getopt} is typically used. The -key points to notice are: - -@itemize @bullet -@item -Normally, @code{getopt} is called in a loop. When @code{getopt} returns -@code{-1}, indicating no more options are present, the loop terminates. - -@item -A @code{switch} statement is used to dispatch on the return value from -@code{getopt}. In typical use, each case just sets a variable that -is used later in the program. - -@item -A second loop is used to process the remaining non-option arguments. -@end itemize - -@smallexample -@include testopt.c.texi -@end smallexample - -Here are some examples showing what this program prints with different -combinations of arguments: - -@smallexample -% testopt -aflag = 0, bflag = 0, cvalue = (null) - -% testopt -a -b -aflag = 1, bflag = 1, cvalue = (null) - -% testopt -ab -aflag = 1, bflag = 1, cvalue = (null) - -% testopt -c foo -aflag = 0, bflag = 0, cvalue = foo - -% testopt -cfoo -aflag = 0, bflag = 0, cvalue = foo - -% testopt arg1 -aflag = 0, bflag = 0, cvalue = (null) -Non-option argument arg1 - -% testopt -a arg1 -aflag = 1, bflag = 0, cvalue = (null) -Non-option argument arg1 - -% testopt -c foo arg1 -aflag = 0, bflag = 0, cvalue = foo -Non-option argument arg1 - -% testopt -a -- -b -aflag = 1, bflag = 0, cvalue = (null) -Non-option argument -b - -% testopt -a - -aflag = 1, bflag = 0, cvalue = (null) -Non-option argument - -@end smallexample - -@node Long Options -@subsection Parsing Long Options - -To accept GNU-style long options as well as single-character options, -use @code{getopt_long} instead of @code{getopt}. This function is -declared in @file{getopt.h}, not @file{unistd.h}. You should make every -program accept long options if it uses any options, for this takes -little extra work and helps beginners remember how to use the program. - -@comment getopt.h -@comment GNU -@deftp {Data Type} {struct option} -This structure describes a single long option name for the sake of -@code{getopt_long}. The argument @var{longopts} must be an array of -these structures, one for each long option. Terminate the array with an -element containing all zeros. - -The @code{struct option} structure has these fields: +@code{getopt} is more standard (the short-option only version of it is a +part of the POSIX standard), but using @code{argp_parse} is often +easier, both for very simple and very complex option structures, because +it does more of the dirty work for you. -@table @code -@item const char *name -This field is the name of the option. It is a string. - -@item int has_arg -This field says whether the option takes an argument. It is an integer, -and there are three legitimate values: @w{@code{no_argument}}, -@code{required_argument} and @code{optional_argument}. - -@item int *flag -@itemx int val -These fields control how to report or act on the option when it occurs. - -If @code{flag} is a null pointer, then the @code{val} is a value which -identifies this option. Often these values are chosen to uniquely -identify particular long options. - -If @code{flag} is not a null pointer, it should be the address of an -@code{int} variable which is the flag for this option. The value in -@code{val} is the value to store in the flag to indicate that the option -was seen. -@end table -@end deftp - -@comment getopt.h -@comment GNU -@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr}) -Decode options from the vector @var{argv} (whose length is @var{argc}). -The argument @var{shortopts} describes the short options to accept, just as -it does in @code{getopt}. The argument @var{longopts} describes the long -options to accept (see above). - -When @code{getopt_long} encounters a short option, it does the same -thing that @code{getopt} would do: it returns the character code for the -option, and stores the options argument (if it has one) in @code{optarg}. - -When @code{getopt_long} encounters a long option, it takes actions based -on the @code{flag} and @code{val} fields of the definition of that -option. - -If @code{flag} is a null pointer, then @code{getopt_long} returns the -contents of @code{val} to indicate which option it found. You should -arrange distinct values in the @code{val} field for options with -different meanings, so you can decode these values after -@code{getopt_long} returns. If the long option is equivalent to a short -option, you can use the short option's character code in @code{val}. - -If @code{flag} is not a null pointer, that means this option should just -set a flag in the program. The flag is a variable of type @code{int} -that you define. Put the address of the flag in the @code{flag} field. -Put in the @code{val} field the value you would like this option to -store in the flag. In this case, @code{getopt_long} returns @code{0}. - -For any long option, @code{getopt_long} tells you the index in the array -@var{longopts} of the options definition, by storing it into -@code{*@var{indexptr}}. You can get the name of the option with -@code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among -long options either by the values in their @code{val} fields or by their -indices. You can also distinguish in this way among long options that -set flags. - -When a long option has an argument, @code{getopt_long} puts the argument -value in the variable @code{optarg} before returning. When the option -has no argument, the value in @code{optarg} is a null pointer. This is -how you can tell whether an optional argument was supplied. - -When @code{getopt_long} has no more options to handle, it returns -@code{-1}, and leaves in the variable @code{optind} the index in -@var{argv} of the next remaining argument. -@end deftypefun +@menu +* Getopt:: Parsing program options using @code{getopt}. +* Argp:: Parsing program options using @code{argp_parse}. +* Suboptions:: Some programs need more detailed options. +* Suboptions Example:: This shows how it could be done for @code{mount}. +@end menu -@node Long Option Example -@subsection Example of Parsing Long Options +@c Getopt and argp start at the @section level so that there's +@c enough room for their internal hierarchy (mostly a problem with +@c argp). -Miles -@smallexample -@include longopt.c.texi -@end smallexample +@include getopt.texi +@include argp.texi -@node Suboptions -@subsection Parsing of Suboptions +@node Suboptions, Suboptions Example, Argp, Parsing Program Arguments +@c This is a @section so that it's at the same level as getopt and argp +@section Parsing of Suboptions Having a single level of options is sometimes not enough. There might be too many options which have to be available or a set of options is @@ -452,7 +227,7 @@ possible value is returned in @var{valuep} and the return value of the function is @samp{-1}. @end deftypefun -@node Suboptions Example +@node Suboptions Example, , Suboptions, Parsing Program Arguments @subsection Parsing of Suboptions Example The code which might appear in the @code{mount}(8) program is a perfect @@ -699,7 +474,8 @@ This specifies what locale to use for formatting date/time values. @cindex _POSIX_OPTION_ORDER environment variable. If this environment variable is defined, it suppresses the usual -reordering of command line arguments by @code{getopt}. @xref{Argument Syntax}. +reordering of command line arguments by @code{getopt} and +@code{argp_parse}. @xref{Argument Syntax}. @c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS @end table diff --git a/manual/summary.awk b/manual/summary.awk index d997a2080f..3d4d19ea4a 100644 --- a/manual/summary.awk +++ b/manual/summary.awk @@ -1,6 +1,6 @@ # awk script to create summary.texinfo from the library texinfo files. -# Copyright (C) 1992, 1993 Free Software Foundation, Inc. +# Copyright (C) 1992, 1993, 1997 Free Software Foundation, Inc. # This file is part of the GNU C Library. # The GNU C Library is free software; you can redistribute it and/or @@ -86,7 +86,8 @@ print "@c This file is generated by summary.awk from the Texinfo sources." $1 == "@node" { node=$2; for (i = 3; i <= NF; ++i) { node=node " " $i; if ( $i ~ /,/ ) break; } - } + sub (/,[, ]*$/, "", node); + } $1 == "@comment" && $2 ~ /\.h$/ { header="@file{" $2 "}"; for (i = 3; i <= NF; ++i) diff --git a/manual/texinfo.tex b/manual/texinfo.tex index e5982dc386..95c825389d 100644 --- a/manual/texinfo.tex +++ b/manual/texinfo.tex @@ -1,5 +1,5 @@ %% TeX macros to handle Texinfo files. -%% $Id: texinfo.tex,v 2.200 1997/05/26 22:19:32 drepper Exp $ +%% $Id: texinfo.tex,v 2.201 1997/06/05 11:28:54 drepper Exp $ % Copyright (C) 1985, 86, 88, 90, 91, 92, 93, % 94, 95, 96, 97 Free Software Foundation, Inc. @@ -36,7 +36,7 @@ % This automatically updates the version number based on RCS. \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 2.200 $ +\deftexinfoversion$Revision: 2.201 $ \message{Loading texinfo package [Version \texinfoversion]:} % If in a .fmt file, print the version number @@ -1041,8 +1041,9 @@ where each line of input produces a line of output.} % We don't need math for this one. \def\ttsl{\tenttsl} -%% Try out Computer Modern fonts at \magstephalf -\let\mainmagstep=\magstephalf +% Use Computer Modern fonts at \magstephalf (11pt). +\newcount\mainmagstep +\mainmagstep=\magstephalf % Set the font macro #1 to the font named #2, adding on the % specified font prefix (normally `cm'). @@ -1337,8 +1338,9 @@ where each line of input produces a line of output.} \else{\tclose{\ttsl\look}}\fi \else{\tclose{\ttsl\look}}\fi} -% @url, @email. Quotes do not seem necessary. +% @url, @uref, @email. Quotes do not seem necessary. \let\url=\code % perhaps include a hypertex \special eventually +\let\uref=\code % rms does not like the angle brackets --karl, 17may97. %\def\email#1{$\langle${\tt #1}$\rangle$} \let\email=\code |