This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [MTASCsft PATCH 02/??] MT-, AS- and AC-Safety docs: manual/argp.texi


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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]