This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [MTASCsft PATCH 02/??] MT-, AS- and AC-Safety docs: manual/argp.texi
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Alexandre Oliva <aoliva at redhat dot com>, codonell at redhat dot com
- Cc: libc-alpha at sourceware dot org
- Date: Wed, 29 Jan 2014 00:29:31 -0500
- Subject: Re: [MTASCsft PATCH 02/??] MT-, AS- and AC-Safety docs: manual/argp.texi
- Authentication-results: sourceware.org; auth=none
- References: <ortxelb5zd dot fsf at livre dot home> <or4n4uoncj dot fsf at livre dot home> <orvbxan3qf dot fsf_-_ at livre dot home>
On 01/23/2014 09:59 AM, Alexandre Oliva wrote:
> This patch contains a number of functions with (partial) call graphs
> encoded as comments. It's from a time when I started using them, and I
> didn't fill in all the details of all dependencies, unlike later
> patches, but it's a good opportunity to decide whether we're keeping
> these notes in the .texi files, moving them elsewhere, or dropping them
> on the floor.
Keep them. They are just comments after all and that's fine.
OK to commit.
> for ChangeLog
>
> * manual/argp.texi: Document MTASC-safety properties.
> ---
> manual/argp.texi | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 182 insertions(+)
>
> diff --git a/manual/argp.texi b/manual/argp.texi
> index c9fbe97..be1d158 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{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtslocale{} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
OK.
> +@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 @ascuheap @acsmem
> +@c parser_convert @mtslocale
> +@c convert_options @mtslocale
> +@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 @mtasurace
> +@c parser_parse_arg
> +@c group_parse dup
> +@c parser_parse_opt
> +@c group_parse dup
> +@c argp_error dup @mtasurace:argpbuf @mtsenv @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
> +@c dgettext (bad key error) dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
> +@c parser_finalize
> +@c group_parse
> +@c fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem]
> +@c dgettext dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
> +@c arg_state_help
> +@c free dup @ascuhelp @acsmem
> 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{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
OK.
> +@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{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
OK.
> +@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{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
OK.
> +@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,142 @@ 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{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
OK.
> +@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, thus
> +@c @mtasurace:argpbuf) that makes the whole thing thread-unsafe, reading
> +@c from the environment for ARGP_HELP_FMT, accessing the locale object
> +@c multiple times.
> +
> +@c _help @mtsenv @mtasurace:argpbuf @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
> +@c dgettext @ascuintl
> +@c flockfile @aculock
> +@c funlockfile @aculock
> +@c fill_in_uparams @mtsenv @mtasurace:argpbuf @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
> +@c argp_failure dup (status = errnum = 0)
> +@c atoi dup @mtslocale
> +@c argp_hol @ascuheap @acsmem
> +@c make_hol @ascuheap @acsmem
> +@c hol_add_cluster @ascuheap @acsmem
> +@c hol_append @ascuheap @acsmem
> +@c hol_set_group ok
> +@c hol_find_entry ok
> +@c hol_sort @mtslocale @acucorrupt
> +@c qsort dup @acucorrupt
> +@c hol_entry_qcmp @mtslocale
> +@c hol_entry_cmp @mtslocale
> +@c group_cmp ok
> +@c hol_cluster_cmp ok
> +@c group_cmp ok
> +@c hol_entry_first_short @mtslocale
> +@c hol_entry_short_iterate [@mtslocale]
> +@c until_short ok
> +@c oshort ok
> +@c isprint ok
> +@c odoc ok
> +@c hol_entry_first_long ok
> +@c canon_doc_option @mtslocale
> +@c tolower dup
> +@c hol_usage @mtslocale @ascuintl @ascuheap @acsmem
> +@c hol_entry_short_iterate ok
> +@c add_argless_short_opt ok
> +@c argp_fmtstream_printf dup
> +@c hol_entry_short_iterate @mtslocale @ascuintl @ascuheap @acsmem
> +@c usage_argful_short_opt @mtslocale @ascuintl @ascuheap @acsmem
> +@c dgettext dup
> +@c argp_fmtstream_printf dup
> +@c hol_entry_long_iterate @mtslocale @ascuintl @ascuheap @acsmem
> +@c usage_long_opt @mtslocale @ascuintl @ascuheap @acsmem
> +@c dgettext dup
> +@c argp_fmtstream_printf dup
> +@c hol_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
> +@c hol_entry_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
> +@c argp_fmtstream_set_lmargin dup
> +@c argp_fmtstream_wmargin dup
> +@c argp_fmtstream_set_wmargin dup
> +@c comma @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
> +@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 @mtslocale @ascuheap @acsmem
> +@c argp_fmtstream_printf dup
> +@c odoc dup
> +@c argp_fmtstream_puts dup
> +@c argp_fmtstream_printf dup
> +@c print_header @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
> +@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 @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@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 @ascuheap @acsmem
> +@c free dup
> +@c argp_args_levels ok
> +@c argp_args_usage @mtslocale @ascuintl @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@c dgettext dup
> +@c filter_doc ok
> +@c argp_input ok
> +@c argp->help_filter
> +@c space @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@c argp_fmtstream_point dup
> +@c argp_fmtstream_rmargin @mtslocale @asucorrupt @acucorrupt @aculock
> +@c argp_fmtstream_update dup
> +@c argp_fmtstream_putc dup
> +@c argp_fmtstream_write dup
> +@c free dup
> +@c argp_doc @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
> +@c dgettext @ascuintl
> +@c strndup @ascuheap @acsmem
> +@c argp_input dup
> +@c argp->help_filter
> +@c argp_fmtstream_putc @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@c argp_fmtstream_ensure dup
> +@c argp_fmtstream_write dup
> +@c argp_fmtstream_puts dup
> +@c argp_fmtstream_point @mtslocale @asucorrupt @acucorrupt @aculock
> +@c argp_fmtstream_update dup
> +@c argp_fmtstream_lmargin dup
> +@c free dup
> +@c argp_make_fmtstream @ascuheap @acsmem
> +@c argp_fmtstream_free @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@c argp_fmtstream_update @mtslocale @asucorrupt @acucorrupt @aculock
> +@c put[w]c_unlocked dup
> +@c isblank in loop @mtslocale
> +@c fxprintf @aculock
> +@c fxprintf @aculock
> +@c free dup
> +@c argp_fmtstream_set_wmargin @mtslocale @asucorrupt @acucorrupt @aculock
> +@c argp_fmtstream_update dup
> +@c argp_fmtstream_printf @mtslocale @ascuheap @acsmem
> +@c argp_fmtstream_ensure dup
> +@c vsnprintf dup
> +@c argp_fmtstream_set_lmargin @mtslocale @asucorrupt @acucorrupt @aculock
> +@c argp_fmtstream_update dup
> +@c argp_fmtstream_puts @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@c argp_fmtstream_write @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@c argp_fmtstream_ensure @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
> +@c argp_fmtstream_update dup
> +@c fxprintf @aculock
> +@c realloc @ascuheap @acsmem
> 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 +1108,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{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
OK.
> +@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}.
>
>
Cheers,
Carlos.