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

["Carlos O'Donell" <carlos at redhat dot com>]

On 01/23/2014 10:10 AM, Alexandre Oliva wrote:
> Are long comments describing the overall behavior of a function, as in
> sysconf, desirable to retain in the manual?
 
Yes. They are as good a place as any until we decide to do some
kind of source->manual translation working (impossible with current
licenses).
 
OK to checkin.

> for ChangeLog
> 
> 	* manual/conf.texi: Document MTASC-safety properties.
> ---
>  manual/conf.texi |   19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/manual/conf.texi b/manual/conf.texi
> index c720063..82a8766 100644
> --- a/manual/conf.texi
> +++ b/manual/conf.texi
> @@ -288,6 +288,17 @@ constants are declared in the header file @file{unistd.h}.
>  @comment unistd.h
>  @comment POSIX.1
>  @deftypefun {long int} sysconf (int @var{parameter})
> +@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
> +@c Some parts of the implementation open /proc and /sys files and dirs
> +@c to collect system details, using fd and stream I/O depending on the
> +@c case.  _SC_TZNAME_MAX calls __tzname_max, that (while holding a lock)
> +@c calls tzset_internal, that calls getenv if it's called the first
> +@c time; there are free and strdup calls in there too.  The returned max
> +@c value may change over time for TZNAME_MAX, depending on selected
> +@c timezones; NPROCS, NPROCS_CONF, PHYS_PAGES, AVPHYS_PAGES,
> +@c NGROUPS_MAX, SIGQUEUE_MAX, depending on variable values read from
> +@c /proc at each call, and from rlimit-obtained values CHILD_MAX,
> +@c OPEN_MAX, ARG_MAX, SIGQUEUE_MAX.
>  This function is used to inquire about runtime system parameters.  The
>  @var{parameter} argument should be one of the @samp{_SC_} symbols listed
>  below.
> @@ -1348,6 +1359,11 @@ argument are declared in the header file @file{unistd.h}.
>  @comment unistd.h
>  @comment POSIX.1
>  @deftypefun {long int} pathconf (const char *@var{filename}, int @var{parameter})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
> +@c When __statfs_link_max finds an ext* filesystem, it may read
> +@c /proc/mounts or similar as a mntent stream.
> +@c __statfs_chown_restricted may read from
> +@c /proc/sys/fs/xfs/restrict_chown as a file descriptor.
>  This function is used to inquire about the limits that apply to
>  the file named @var{filename}.
>  
> @@ -1375,6 +1391,8 @@ support the @var{parameter} for the specific file.
>  @comment unistd.h
>  @comment POSIX.1
>  @deftypefun {long int} fpathconf (int @var{filedes}, int @var{parameter})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
> +@c Same caveats as pathconf.
>  This is just like @code{pathconf} except that an open file descriptor
>  is used to specify the file for which information is requested, instead
>  of a file name.
> @@ -1624,6 +1642,7 @@ system with the function @code{confstr}:
>  @comment unistd.h
>  @comment POSIX.2
>  @deftypefun size_t confstr (int @var{parameter}, char *@var{buf}, size_t @var{len})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>  This function reads the value of a string-valued system parameter,
>  storing the string into @var{len} bytes of memory space starting at
>  @var{buf}.  The @var{parameter} argument should be one of the
>