aboutsummaryrefslogtreecommitdiff
path: root/manual/argp.texi
diff options
context:
space:
mode:
authorRical Jasan <ricaljasan@pacific.net>2017-06-15 21:12:39 -0700
committerRical Jasan <ricaljasan@pacific.net>2017-06-15 21:26:20 -0700
commitd08a7e4cbe43d5e4e4b14dea950fea623d96c1a1 (patch)
tree6f27987046ae0e8804f4d641c99ff1666652117a /manual/argp.texi
parent27691d5cec9b896ea0792151a27c6d7d7a4065ea (diff)
downloadglibc-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.tar
glibc-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.tar.gz
glibc-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.tar.bz2
glibc-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.zip
manual: Replace summary.awk with summary.pl.
The Summary is now generated from @standards, and syntax-checking is performed. If invalid @standards syntax is detected, summary.pl will fail, reporting all errors. Failure and error reporting is disabled for now, however, since much of the manual is still incomplete wrt. header and standards annotations. Note that the sorting order of the Summary has changed; summary.pl respects the locale, like summary.awk did, but the use of LC_ALL=C is introduced in the Makefile. Other notable deviations are improved detection of the annotated elements' names, which are used for sorting, and improved detection of the @node used to reference into the manual. The most noticeable difference in the rendered Summary is that entries may now contain multiple lines, one for each header and standard combination. summary.pl accepts a `--help' option, which details the expected syntax of @standards. If errors are reported, the user is directed to this feature for further information. * manual/Makefile: Generate summary.texi with summary.pl. Force use of the C locale. Update Perl dependency comment. * manual/header.texi: Update reference to summary.awk. * manual/macros.texi: Refer authors to `summary.pl --help'. * manual/summary.awk: Remove file. * manual/summary.pl: New file. Generate summary.texi, and check for @standards-related syntax errors. * manual/argp.texi: Convert header and standards @comments to @standards. * manual/arith.texi: Likewise. * manual/charset.texi: Likewise. * manual/conf.texi: Likewise. * manual/creature.texi: Likewise. * manual/crypt.texi: Likewise. * manual/ctype.texi: Likewise. * manual/debug.texi: Likewise. * manual/errno.texi: Likewise. * manual/filesys.texi: Likewise. * manual/getopt.texi: Likewise. * manual/job.texi: Likewise. * manual/lang.texi: Likewise. * manual/llio.texi: Likewise. * manual/locale.texi: Likewise. * manual/math.texi: Likewise. * manual/memory.texi: Likewise. * manual/message.texi: Likewise. * manual/pattern.texi: Likewise. * manual/pipe.texi: Likewise. * manual/process.texi: Likewise. * manual/resource.texi: Likewise. * manual/search.texi: Likewise. * manual/setjmp.texi: Likewise. * manual/signal.texi: Likewise. * manual/socket.texi: Likewise. * manual/startup.texi: Likewise. * manual/stdio.texi: Likewise. * manual/string.texi: Likewise. * manual/sysinfo.texi: Likewise. * manual/syslog.texi: Likewise. * manual/terminal.texi: Likewise. * manual/threads.texi: Likewise. * manual/time.texi: Likewise. * manual/users.texi: Likewise.
Diffstat (limited to 'manual/argp.texi')
-rw-r--r--manual/argp.texi126
1 files changed, 42 insertions, 84 deletions
diff --git a/manual/argp.texi b/manual/argp.texi
index bca3ca5ed9..854c71b017 100644
--- a/manual/argp.texi
+++ b/manual/argp.texi
@@ -33,9 +33,8 @@ cases, calling @code{argp_parse} is the only argument-parsing code
needed in @code{main}.
@xref{Program Arguments}.
-@comment argp.h
-@comment GNU
@deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input})
+@standards{GNU, argp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtslocale{} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@c Optionally alloca()tes standard help options, initializes the parser,
@c then parses individual args in a loop, and then finalizes.
@@ -108,18 +107,16 @@ These variables make it easy for user programs to implement the
@samp{--version} option and provide a bug-reporting address in the
@samp{--help} output. These are implemented in argp by default.
-@comment argp.h
-@comment GNU
@deftypevar {const char *} argp_program_version
+@standards{GNU, argp.h}
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},
which will print the @samp{--version} string followed by a newline and
exit. The exception to this is if the @code{ARGP_NO_EXIT} flag is used.
@end deftypevar
-@comment argp.h
-@comment GNU
@deftypevar {const char *} argp_program_bug_address
+@standards{GNU, argp.h}
If defined or set by the user program to a non-zero value,
@code{argp_program_bug_address} should point to a string that will be
printed at the end of the standard output for the @samp{--help} option,
@@ -127,9 +124,8 @@ embedded in a sentence that says @samp{Report bugs to @var{address}.}.
@end deftypevar
@need 1500
-@comment argp.h
-@comment GNU
@defvar argp_program_version_hook
+@standards{GNU, argp.h}
If defined or set by the user program to a non-zero value, a
@samp{--version} option is added when parsing with @code{arg_parse},
which prints the program version and exits with a status of zero. This
@@ -152,9 +148,8 @@ useful if a program has version information not easily expressed in a
simple string.
@end defvar
-@comment argp.h
-@comment GNU
@deftypevar error_t argp_err_exit_status
+@standards{GNU, argp.h}
This is the exit status used when argp exits due to a parsing error. If
not defined or set by the user program, this defaults to:
@code{EX_USAGE} from @file{<sysexits.h>}.
@@ -166,9 +161,8 @@ not defined or set by the user program, this defaults to:
The first argument to the @code{argp_parse} function is a pointer to a
@code{struct argp}, which is known as an @dfn{argp parser}:
-@comment argp.h
-@comment GNU
@deftp {Data Type} {struct argp}
+@standards{GNU, argp.h}
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:
@@ -243,9 +237,8 @@ option provided it has multiple names. This 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}
+@standards{GNU, argp.h}
This structure specifies a single option that an argp parser
understands, as well as how to parse and document that option. It has
the following fields:
@@ -317,28 +310,24 @@ that option is parsed or displayed in help messages:
@vtable @code
-@comment argp.h
-@comment GNU
@item OPTION_ARG_OPTIONAL
+@standards{GNU, argp.h}
The argument associated with this option is optional.
-@comment argp.h
-@comment GNU
@item OPTION_HIDDEN
+@standards{GNU, argp.h}
This option isn't displayed in any help messages.
-@comment argp.h
-@comment GNU
@item OPTION_ALIAS
+@standards{GNU, argp.h}
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 option being
aliased.
-@comment argp.h
-@comment GNU
@item OPTION_DOC
+@standards{GNU, argp.h}
This option isn't actually an option and should be ignored by the actual
option parser. It is an arbitrary section of documentation that should
be displayed in much the same manner as the options. This is known as a
@@ -353,9 +342,8 @@ first non-whitespace character is @samp{-}. This entry is displayed
after all options, after @code{OPTION_DOC} entries with a leading
@samp{-}, in the same group.
-@comment argp.h
-@comment GNU
@item OPTION_NO_USAGE
+@standards{GNU, argp.h}
This option shouldn't be included in `long' usage messages, but should
still be included in other help messages. This is intended for options
that are completely documented in an argp's @code{args_doc}
@@ -417,9 +405,8 @@ appropriate for @var{key}, and return @code{0} for success,
parser function, or a unix error code if a real error
occurred. @xref{Error Codes}.
-@comment argp.h
-@comment GNU
@deftypevr Macro int ARGP_ERR_UNKNOWN
+@standards{GNU, argp.h}
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 are not equipped to handle.
@@ -460,9 +447,8 @@ values. In the following example @var{arg} and @var{state} refer to
parser function arguments. @xref{Argp Parser Functions}.
@vtable @code
-@comment argp.h
-@comment GNU
@item ARGP_KEY_ARG
+@standards{GNU, argp.h}
This is not an option at all, but rather a command line argument, whose
value is pointed to by @var{arg}.
@@ -480,9 +466,8 @@ 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_ARGS
+@standards{GNU, argp.h}
If a parser function returns @code{ARGP_ERR_UNKNOWN} for
@code{ARGP_KEY_ARG}, it is immediately called again with the key
@code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
@@ -511,45 +496,39 @@ case ARGP_KEY_ARGS:
break;
@end smallexample
-@comment argp.h
-@comment GNU
@item ARGP_KEY_END
+@standards{GNU, argp.h}
This indicates that there are no more command line arguments. Parser
functions are called in a different order, children first. This allows
each parser to clean up its state for the parent.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_NO_ARGS
+@standards{GNU, argp.h}
Because it's common 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. This is called
just before @code{ARGP_KEY_END}, where more general validity checks on
previously parsed arguments take place.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_INIT
+@standards{GNU, argp.h}
This is 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
+@standards{GNU, argp.h}
Passed in when parsing has successfully been completed, even if
arguments remain.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_ERROR
+@standards{GNU, argp.h}
Passed in if an error has occurred and parsing is terminated. In this
case a call with a key of @code{ARGP_KEY_SUCCESS} is never made.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_FINI
+@standards{GNU, argp.h}
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. At times, certain
@@ -597,9 +576,8 @@ 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}
+@standards{GNU, argp.h}
This structure has the following fields, which may be modified as noted:
@table @code
@@ -686,9 +664,8 @@ parser function. @xref{Argp Parsing State}.
@cindex usage messages, in argp
-@comment argp.h
-@comment GNU
@deftypefun void argp_usage (const struct argp_state *@var{state})
+@standards{GNU, argp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
@c Just calls argp_state_help with stderr and ARGP_HELP_STD_USAGE.
Outputs the standard usage message for the argp parser referred to by
@@ -697,9 +674,8 @@ with @code{exit (argp_err_exit_status)}. @xref{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}, const char *@var{fmt}, @dots{})
+@standards{GNU, argp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
@c Lock stream, vasprintf the formatted message into a buffer, print the
@c buffer prefixed by the short program name (in libc,
@@ -714,9 +690,8 @@ by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
@end deftypefun
@cindex error messages, in argp
-@comment argp.h
-@comment GNU
@deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{})
+@standards{GNU, argp.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
@c Lock stream, write out the short program name, vasprintf the optional
@c formatted message to a buffer, print the buffer prefixed by colon and
@@ -736,9 +711,8 @@ 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}, FILE *@var{stream}, unsigned @var{flags})
+@standards{GNU, argp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
@c Just calls _help with the short program name and optionally exit.
@c The main problems in _help, besides the usual issues with stream I/O
@@ -920,9 +894,8 @@ option with the same name, the parser conflicts are resolved in favor of
the parent argp parser(s), or the earlier of the argp parsers in the
list of children.
-@comment argp.h
-@comment GNU
@deftp {Data Type} {struct argp_child}
+@standards{GNU, argp.h}
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:
@@ -963,62 +936,54 @@ 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
+@standards{GNU, argp.h}
Don't ignore the first element of the @var{argv} argument to
@code{argp_parse}. 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
+@standards{GNU, argp.h}
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}. This is based on the assumption that silent exiting
upon errors is bad behavior.
-@comment argp.h
-@comment GNU
@item ARGP_NO_ARGS
+@standards{GNU, argp.h}
Don't parse any non-option args. Normally these are parsed by calling
the parse functions with a key of @code{ARGP_KEY_ARG}, the actual
argument being the value. This flag needn't normally be set, as the
default behavior is to stop parsing as soon as an argument fails to be
parsed. @xref{Argp Parser Functions}.
-@comment argp.h
-@comment GNU
@item ARGP_IN_ORDER
+@standards{GNU, argp.h}
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
+@standards{GNU, argp.h}
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)}.
-@comment argp.h
-@comment GNU
@item ARGP_NO_EXIT
+@standards{GNU, argp.h}
Don't exit on errors, although they may still result in error messages.
-@comment argp.h
-@comment GNU
@item ARGP_LONG_ONLY
+@standards{GNU, argp.h}
Use the GNU getopt `long-only' rules for parsing arguments. This allows
long-options to be recognized with only a single @samp{-}
(i.e., @samp{-help}). This results in a less useful interface, and its
use is discouraged as it conflicts with the way most GNU programs work
as well as the GNU coding standards.
-@comment argp.h
-@comment GNU
@item ARGP_SILENT
+@standards{GNU, argp.h}
Turns off any message-printing/exiting options, specifically
@code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
@end vtable
@@ -1063,34 +1028,28 @@ function as the first argument in addition to key values for user
options. They specify which help text the @var{text} argument contains:
@vtable @code
-@comment argp.h
-@comment GNU
@item ARGP_KEY_HELP_PRE_DOC
+@standards{GNU, argp.h}
The help text preceding options.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_HELP_POST_DOC
+@standards{GNU, argp.h}
The help text following options.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_HELP_HEADER
+@standards{GNU, argp.h}
The option header string.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_HELP_EXTRA
+@standards{GNU, argp.h}
This is used after all other documentation; @var{text} is zero for this key.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_HELP_DUP_ARGS_NOTE
+@standards{GNU, argp.h}
The explanatory note printed when duplicate option arguments have been suppressed.
-@comment argp.h
-@comment GNU
@item ARGP_KEY_HELP_ARGS_DOC
+@standards{GNU, argp.h}
The argument doc string; formally the @code{args_doc} field from the argp parser. @xref{Argp Parsers}.
@end vtable
@@ -1105,9 +1064,8 @@ cases can be handled using @code{argp_usage} and
desirable to print a 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}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name})
+@standards{GNU, argp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
@c Just calls _help.
This outputs a help message for the argp parser @var{argp} to