aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
authorAlexandre Oliva <aoliva@redhat.com>2014-02-01 01:04:59 -0200
committerAlexandre Oliva <aoliva@redhat.com>2014-02-01 01:04:59 -0200
commit663b02d7bdf874a21b7e1404b381c86cea448226 (patch)
treeb93ee22946379c1910ac937c014a54dcbbe80555 /manual
parent973f180bd5e3084367ebc75e380bfb79ec5346ba (diff)
downloadglibc-663b02d7bdf874a21b7e1404b381c86cea448226.zip
glibc-663b02d7bdf874a21b7e1404b381c86cea448226.tar.gz
glibc-663b02d7bdf874a21b7e1404b381c86cea448226.tar.bz2
* manual/startup.texi: Document MTASC-safety properties.
Diffstat (limited to 'manual')
-rw-r--r--manual/startup.texi79
1 files 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