This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [MTASCsft PATCH 29/??] MT-, AS- and AC-Safety docs: manual/startup.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: Fri, 31 Jan 2014 20:55:43 -0500
- Subject: Re: [MTASCsft PATCH 29/??] MT-, AS- and AC-Safety docs: manual/startup.texi
- Authentication-results: sourceware.org; auth=none
- References: <ortxelb5zd dot fsf at livre dot home> <or4n4uoncj dot fsf at livre dot home> <orha8og5ka dot fsf_-_ at livre dot home>
On 01/27/2014 10:15 PM, Alexandre Oliva wrote:
>
> for ChangeLog
>
> * manual/startup.texi: Document MTASC-safety properties.
OK to checkin.
> ---
> manual/startup.texi | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 77 insertions(+), 2 deletions(-)
>
> diff --git a/manual/startup.texi b/manual/startup.texi
> index edd1de4..8078a53 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -221,6 +221,11 @@ available.
>
> @comment stdlib.h
> @deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c getsubopt ok
> +@c strchrnul dup ok
> +@c memchr dup ok
> +@c strncmp dup ok
>
> The @var{optionp} parameter must be a pointer to a variable containing
> the address of the string to process. When the function returns the
> @@ -322,6 +327,8 @@ functions can be safely used in multi-threaded programs.
> @comment stdlib.h
> @comment ISO
> @deftypefun {char *} getenv (const char *@var{name})
> +@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
> +@c Unguarded access to __environ.
> This function returns a string that is the value of the environment
> variable @var{name}. You must not modify this string. In some non-Unix
> systems not using @theglibc{}, it might be overwritten by subsequent
> @@ -333,6 +340,8 @@ pointer.
> @comment stdlib.h
> @comment GNU
> @deftypefun {char *} secure_getenv (const char *@var{name})
> +@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
> +@c Calls getenv unless secure mode is enabled.
> This function is similar to @code{getenv}, but it returns a null
> pointer if the environment is untrusted. This happens when the
> program file has SUID or SGID bits set. General-purpose libraries
> @@ -346,6 +355,13 @@ This function is a GNU extension.
> @comment stdlib.h
> @comment SVID
> @deftypefun int putenv (char *@var{string})
> +@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
> +@c putenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
> +@c strchr dup ok
> +@c strndup dup @ascuheap @acsmem
> +@c add_to_environ dup @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
> +@c free dup @ascuheap @acsmem
> +@c unsetenv dup @mtasuconst:@mtsenv @asulock @aculock
> The @code{putenv} function adds or removes definitions from the environment.
> If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
> definition is added to the environment. Otherwise, the @var{string} is
> @@ -358,8 +374,8 @@ value is nonzero and @code{errno} is set to indicate the error.
> The difference to the @code{setenv} function is that the exact string
> given as the parameter @var{string} is put into the environment. If the
> user should change the string after the @code{putenv} call this will
> -reflect in automatically in the environment. This also requires that
> -@var{string} is no automatic variable which scope is left before the
> +reflect automatically in the environment. This also requires that
> +@var{string} not be an automatic variable whose scope is left before the
> variable is removed from the environment. The same applies of course to
> dynamically allocated variables which are freed later.
>
> @@ -372,6 +388,24 @@ available in old SVID libraries you should define either
> @comment stdlib.h
> @comment BSD
> @deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace})
> +@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
> +@c setenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
> +@c add_to_environ @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
> +@c strlen dup ok
> +@c libc_lock_lock @asulock @aculock
> +@c strncmp dup ok
> +@c realloc dup @ascuheap @acsmem
> +@c libc_lock_unlock @aculock
> +@c malloc dup @ascuheap @acsmem
> +@c free dup @ascuheap @acsmem
> +@c mempcpy dup ok
> +@c memcpy dup ok
> +@c KNOWN_VALUE ok
> +@c tfind(strcmp) [no @mtsrace guarded access]
> +@c strcmp dup ok
> +@c STORE_VALUE @ascuheap @acucorrupt @acsmem
> +@c tsearch(strcmp) @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt guarded access makes for mtsafe and @asulock]
> +@c strcmp dup ok
> The @code{setenv} function can be used to add a new definition to the
> environment. The entry with the name @var{name} is replaced by the
> value @samp{@var{name}=@var{value}}. Please note that this is also true
> @@ -395,6 +429,13 @@ the Unix standard.
> @comment stdlib.h
> @comment BSD
> @deftypefun int unsetenv (const char *@var{name})
> +@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
> +@c unsetenv @mtasuconst:@mtsenv @asulock @aculock
> +@c strchr dup ok
> +@c strlen dup ok
> +@c libc_lock_lock @asulock @aculock
> +@c strncmp dup ok
> +@c libc_lock_unlock @aculock
> Using this function one can remove an entry completely from the
> environment. If the environment contains an entry with the key
> @var{name} this whole entry is removed. A call to this function is
> @@ -418,6 +459,11 @@ to enable writing standard compliant Fortran environments.
> @comment stdlib.h
> @comment GNU
> @deftypefun int clearenv (void)
> +@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
> +@c clearenv @mtasuconst:@mtsenv @ascuheap @asulock @aculock @acsmem
> +@c libc_lock_lock @asulock @aculock
> +@c free dup @ascuheap @acsmem
> +@c libc_lock_unlock @aculock
> The @code{clearenv} function removes all entries from the environment.
> Using @code{putenv} and @code{setenv} new entries can be added again
> later.
> @@ -622,6 +668,8 @@ basis there may be information that is not available any other way.
> @subsection Definition of @code{getauxval}
> @comment sys/auxv.h
> @deftypefun {unsigned long int} getauxval (unsigned long int @var{type})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Reads from hwcap or iterates over constant auxv.
> This function is used to inquire about the entries in the auxiliary
> vector. The @var{type} argument should be one of the @samp{AT_} symbols
> defined in @file{elf.h}. If a matching entry is found, the value is
> @@ -678,6 +726,7 @@ anyway.
> @comment unistd.h
> @comment ???
> @deftypefun {long int} syscall (long int @var{sysno}, @dots{})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>
> @code{syscall} performs a generic system call.
>
> @@ -783,6 +832,10 @@ the argument to @code{exit}.
> @comment stdlib.h
> @comment ISO
> @deftypefun void exit (int @var{status})
> +@safety{@prelim{}@mtunsafe{@mtasurace{:exit}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
> +@c Access to the atexit/on_exit list, the libc_atexit hook and tls dtors
> +@c is not guarded. Streams must be flushed, and that triggers the usual
> +@c AS and AC issues with streams.
> The @code{exit} function tells the system that the program is done, which
> causes it to terminate the process.
>
> @@ -899,6 +952,15 @@ using @code{atexit} or @code{on_exit}.
> @comment stdlib.h
> @comment ISO
> @deftypefun int atexit (void (*@var{function}) (void))
> +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
> +@c atexit @ascuheap @asulock @aculock @acsmem
> +@c cxa_atexit @ascuheap @asulock @aculock @acsmem
> +@c __internal_atexit @ascuheap @asulock @aculock @acsmem
> +@c __new_exitfn @ascuheap @asulock @aculock @acsmem
> +@c __libc_lock_lock @asulock @aculock
> +@c calloc dup @ascuheap @acsmem
> +@c __libc_lock_unlock @aculock
> +@c atomic_write_barrier dup ok
> The @code{atexit} function registers the function @var{function} to be
> called at normal program termination. The @var{function} is called with
> no arguments.
> @@ -910,6 +972,10 @@ the function cannot be registered.
> @comment stdlib.h
> @comment SunOS
> @deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
> +@c on_exit @ascuheap @asulock @aculock @acsmem
> +@c new_exitfn dup @ascuheap @asulock @aculock @acsmem
> +@c atomic_write_barrier dup ok
> This function is a somewhat more powerful variant of @code{atexit}. It
> accepts two arguments, a function @var{function} and an arbitrary
> pointer @var{arg}. At normal program termination, the @var{function} is
> @@ -941,6 +1007,10 @@ for this function is in @file{stdlib.h}.
> @comment stdlib.h
> @comment ISO
> @deftypefun void abort (void)
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
> +@c The implementation takes a recursive lock and attempts to support
> +@c calls from signal handlers, but if we're in the middle of flushing or
> +@c using streams, we may encounter them in inconsistent states.
> The @code{abort} function causes abnormal program termination. This
> does not execute cleanup functions registered with @code{atexit} or
> @code{on_exit}.
> @@ -968,6 +1038,9 @@ by @code{exit}. It is declared in the header file @file{unistd.h}.
> @comment unistd.h
> @comment POSIX.1
> @deftypefun void _exit (int @var{status})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Direct syscall (exit_group or exit); calls __task_terminate on hurd,
> +@c and abort in the generic posix implementation.
> The @code{_exit} function is the primitive for causing a process to
> terminate with status @var{status}. Calling this function does not
> execute cleanup functions registered with @code{atexit} or
> @@ -977,6 +1050,8 @@ execute cleanup functions registered with @code{atexit} or
> @comment stdlib.h
> @comment ISO
> @deftypefun void _Exit (int @var{status})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Alias for _exit.
> The @code{_Exit} function is the @w{ISO C} equivalent to @code{_exit}.
> The @w{ISO C} committee members were not sure whether the definitions of
> @code{_exit} and @code{_Exit} were compatible so they have not used the
>
Cheers,
Carlos.