This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
[MTASCsft PATCH WIP4 02/28] Thread safety documentation.
- From: Alexandre Oliva <aoliva at redhat dot com>
- To: libc-alpha at sourceware dot org
- Cc: carlos at redhat dot com, mtk dot manpages at gmail dot com
- Date: Sat, 12 Oct 2013 04:10:28 -0300
- Subject: [MTASCsft PATCH WIP4 02/28] Thread safety documentation.
- Authentication-results: sourceware.org; auth=none
- References: <20131012070020 dot 7511 dot 90546 dot stgit at frit dot home>
for ChangeLog
* manual/argp.texi: Document thread safety properties.
---
manual/argp.texi | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 181 insertions(+)
diff --git a/manual/argp.texi b/manual/argp.texi
index c9fbe97..22e7b9e 100644
--- a/manual/argp.texi
+++ b/manual/argp.texi
@@ -36,6 +36,35 @@ needed in @code{main}.
@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})
+@safety{@mtunsafe{xguargs, envromt}@asunsafe{asmalloc, asi18n, selfdeadlock, asynconsist}@acunsafe{memleak, lockleak, incansist}}
+@c Optionally alloca()tes standard help options, initializes the parser,
+@c then parses individual args in a loop, and then finalizes.
+@c parser_init
+@c calc_sizes ok
+@c option_is_end ok
+@c malloc
+@c parser_convert glocale
+@c convert_options glocale
+@c option_is_end ok
+@c option_is_short ok
+@c isprint, but locale may change within the loop
+@c find_long_option ok
+@c group_parse
+@c group->parser (from argp->parser)
+@c parser_parse_next
+@c getopt_long(_only)_r many issues, same as non_r minus staticbuf
+@c parser_parse_arg
+@c group_parse
+@c parser_parse_opt
+@c group_parse
+@c argp_error
+@c dgettext (bad key error)
+@c parser_finalize
+@c group_parse
+@c fprintf
+@c dgettext
+@c arg_state_help
+@c free
The @code{argp_parse} function parses the arguments in @var{argv}, of
length @var{argc}, using the argp parser @var{argp}. @xref{Argp
Parsers}. Passing a null pointer for @var{argp} is the same as using
@@ -660,6 +689,8 @@ parser function. @xref{Argp Parsing State}.
@comment argp.h
@comment GNU
@deftypefun void argp_usage (const struct argp_state *@var{state})
+@safety{@mtunsafe{staticbuf, envromt, glocale}@asunsafe{asmalloc, asi18n, asynconsist}@acunsafe{memleak, incansist, lockleak}}
+@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
@var{state} to @code{@var{state}->err_stream} and terminate the program
with @code{exit (argp_err_exit_status)}. @xref{Argp Global Variables}.
@@ -669,6 +700,13 @@ with @code{exit (argp_err_exit_status)}. @xref{Argp Global Variables}.
@comment argp.h
@comment GNU
@deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{})
+@safety{@mtunsafe{staticbuf, envromt, glocale}@asunsafe{asmalloc, asi18n, asynconsist}@acunsafe{memleak, incansist, lockleak}}
+@c Lock stream, vasprintf the formatted message into a buffer, print the
+@c buffer prefixed by the short program name (in libc,
+@c argp_short_program_name is a macro that expands to
+@c program_invocation_short_name), releases the buffer, then call
+@c argp_state_help with stream and ARGP_HELP_STD_ERR, unlocking the
+@c stream at the end.
Prints 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 terminates the program with an exit status of
@@ -679,6 +717,12 @@ by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
@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{})
+@safety{@mtsafe{}@asunsafe{asynconsist, asmalloc}@acunsafe{lockleak, incansist, memleak}}
+@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
+@c blank, release the buffer, call strerror_r with an automatic buffer,
+@c print it out after colon and blank, put[w]c a line break, unlock the
+@c stream, then exit unless ARGP_NO_EXIT.
Similar to the standard gnu error-reporting function @code{error}, this
prints the program name and @samp{:}, the printf format string
@var{fmt}, and the appropriate following args. If it is non-zero, the
@@ -695,6 +739,141 @@ for options, bad phase of the moon, etc.
@comment argp.h
@comment GNU
@deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags})
+@safety{@mtunsafe{staticbuf, envromt, glocale}@asunsafe{asmalloc, asi18n, asynconsist}@acunsafe{memleak, incansist, lockleak}}
+@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
+@c and translation, are the use of a static buffer (uparams) that makes
+@c the whole thing thread-unsafe, reading from the environment for
+@c ARGP_HELP_FMT, accessing the locale object multiple times.
+
+@c _help envromt, staticbuf (uparams), glocale, asmalloc, asi18n, asynconsist, memleak, incansist, lockleak
+@c dgettext asi18n
+@c flockfile lockleak
+@c funlockfile lockleak
+@c fill_in_uparams envromt, staticbuf (uparams), glocale, asynconsist, asmalloc, lockleak, incansist, memleak
+@c argp_failure dup (status = errnum = 0)
+@c atoi dup
+@c argp_hol asmalloc, memleak
+@c make_hol asmalloc, memleak
+@c hol_add_cluster asmalloc, memleak
+@c hol_append asmalloc, memleak
+@c hol_set_group ok
+@c hol_find_entry ok
+@c hol_sort glocale, asmalloc, memleak
+@c qsort asmalloc, memleak
+@c hol_entry_qcmp glocale
+@c hol_entry_cmp glocale
+@c group_cmp ok
+@c hol_cluster_cmp ok
+@c group_cmp ok
+@c hol_entry_first_short glocale
+@c hol_entry_short_iterate [glocale]
+@c until_short ok
+@c oshort ok
+@c isprint ok
+@c odoc ok
+@c hol_entry_first_long ok
+@c canon_doc_option glocale
+@c tolower dup
+@c hol_usage glocale, asi18n, asmalloc, memleak
+@c hol_entry_short_iterate ok
+@c add_argless_short_opt ok
+@c argp_fmtstream_printf dup
+@c hol_entry_short_iterate glocale, asi18n, asmalloc, memleak
+@c usage_argful_short_opt glocale, asi18n, asmalloc, memleak
+@c dgettext dup
+@c argp_fmtstream_printf dup
+@c hol_entry_long_iterate glocale, asi18n, asmalloc, memleak
+@c usage_long_opt glocale, asi18n, asmalloc, memleak
+@c dgettext dup
+@c argp_fmtstream_printf dup
+@c hol_help glocale, staticbuf (uparams), asmalloc, asi18n, asynconsist, memleak, incansist, lockleak
+@c hol_entry_help glocale, staticbuf (uparams), asmalloc, asi18n, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_set_lmargin dup
+@c argp_fmtstream_wmargin dup
+@c argp_fmtstream_set_wmargin dup
+@c comma glocale, asmalloc, asi18n, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_putc dup
+@c hol_cluster_is_child ok
+@c argp_fmtstream_wmargin dup
+@c print_header dup
+@c argp_fmtstream_set_wmargin dup
+@c argp_fmtstream_puts dup
+@c indent_to dup
+@c argp_fmtstream_putc dup
+@c arg glocale, asmalloc, memleak
+@c argp_fmtstream_printf dup
+@c odoc dup
+@c argp_fmtstream_puts dup
+@c argp_fmtstream_printf dup
+@c print_header glocale, staticbuf (uparams), asmalloc, asi18n, asynconsist, memleak, incansist, lockleak
+@c dgettext dup
+@c filter_doc dup
+@c argp_fmtstream_putc dup
+@c indent_to dup
+@c argp_fmtstream_set_lmargin dup
+@c argp_fmtstream_set_wmargin dup
+@c argp_fmtstream_puts dup
+@c free dup
+@c filter_doc dup
+@c argp_fmtstream_point dup
+@c indent_to glocale, asmalloc, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_point dup
+@c argp_fmtstream_putc dup
+@c dgettext dup
+@c filter_doc dup
+@c argp_fmtstream_putc dup
+@c argp_fmtstream_puts dup
+@c free dup
+@c hol_free asmalloc, memleak
+@c free dup
+@c argp_args_levels ok
+@c argp_args_usage glocale, asi18n, asmalloc, asynconsist, memleak, incansist, lockleak
+@c dgettext dup
+@c filter_doc ok
+@c argp_input ok
+@c argp->help_filter
+@c space glocale, asmalloc, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_point dup
+@c argp_fmtstream_rmargin glocale, asynconsist, incansist, lockleak
+@c argp_fmtstream_update dup
+@c argp_fmtstream_putc dup
+@c argp_fmtstream_write dup
+@c free dup
+@c argp_doc glocale, asmalloc, asi18n, asynconsist, memleak, incansist, lockleak
+@c dgettext asi18n
+@c strndup asmalloc, memleak
+@c argp_input dup
+@c argp->help_filter
+@c argp_fmtstream_putc glocale, asmalloc, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_ensure dup
+@c argp_fmtstream_write dup
+@c argp_fmtstream_puts dup
+@c argp_fmtstream_point glocale, asynconsist, incansist, lockleak
+@c argp_fmtstream_update dup
+@c argp_fmtstream_lmargin dup
+@c free dup
+@c argp_make_fmtstream asmalloc, memleak
+@c argp_fmtstream_free glocale, asmalloc, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_update glocale, asynconsist, incansist, lockleak
+@c put[w]c_unlocked dup
+@c isblank in loop glocale
+@c fxprintf lockleak
+@c fxprintf lockleak
+@c free dup
+@c argp_fmtstream_set_wmargin glocale, asynconsist, incansist, lockleak
+@c argp_fmtstream_update dup
+@c argp_fmtstream_printf glocale, asmalloc, memleak
+@c argp_fmtstream_ensure dup
+@c vsnprintf dup
+@c argp_fmtstream_set_lmargin glocale, asynconsist, incansist, lockleak
+@c argp_fmtstream_update dup
+@c argp_fmtstream_puts glocale, asmalloc, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_write glocale, asmalloc, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_ensure glocale, asmalloc, asynconsist, memleak, incansist, lockleak
+@c argp_fmtstream_update dup
+@c fxprintf lockleak
+@c realloc asmalloc, memleak
Outputs 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}.
@@ -928,6 +1107,8 @@ 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})
+@safety{@mtunsafe{staticbuf, envromt, glocale}@asunsafe{asmalloc, asi18n, asynconsist}@acunsafe{memleak, incansist, lockleak}}
+@c Just calls _help.
This outputs a help message for the argp parser @var{argp} to
@var{stream}. The type of messages printed will be determined by
@var{flags}.