attributes.7: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2014-10-18 11:13:26 +02:00
parent 8fd8d7d766
commit 743c01ad28
1 changed files with 21 additions and 13 deletions

View File

@ -47,8 +47,8 @@ MT, in MT-Safe, stands for Multi Thread.
Being MT-Safe does not imply a function is atomic, nor that it uses any Being MT-Safe does not imply a function is atomic, nor that it uses any
of the memory synchronization mechanisms POSIX exposes to users. of the memory synchronization mechanisms POSIX exposes to users.
It is even possible that calling MT-Safe functions in sequence does not yield It is even possible that calling MT-Safe functions in sequence
an MT-Safe combination. does not yield an MT-Safe combination.
For example, having a thread call two MT-Safe For example, having a thread call two MT-Safe
functions one right after the other does not guarantee behavior functions one right after the other does not guarantee behavior
equivalent to atomic execution of a combination of both functions, equivalent to atomic execution of a combination of both functions,
@ -128,7 +128,8 @@ the GNU C Library.
Such preliminary properties are the result of an assessment of the Such preliminary properties are the result of an assessment of the
properties of our current implementation, properties of our current implementation,
rather than of what is mandated and permitted by current and future standards. rather than of what is mandated and permitted
by current and future standards.
Although we strive to abide by the standards, in some cases our Although we strive to abide by the standards, in some cases our
implementation is safe even when the standard does not demand safety, implementation is safe even when the standard does not demand safety,
@ -451,8 +452,9 @@ even though the implicit locking may be disabled on a per-stream basis.
In either case, we will not regard as MT-Unsafe functions that may In either case, we will not regard as MT-Unsafe functions that may
access user-supplied objects in unsafe ways should users fail to ensure access user-supplied objects in unsafe ways should users fail to ensure
the accesses are well defined. the accesses are well defined.
The notion prevails that users are expected to safeguard against data races The notion prevails that users are expected to safeguard against
any user-supplied objects that the library accesses on their behalf. data races any user-supplied objects that the library accesses
on their behalf.
.\" The above describes @mtsrace; @mtasurace is described below. .\" The above describes @mtsrace; @mtasurace is described below.
@ -473,13 +475,15 @@ with unguarded concurrent access to such internal objects by creating a
non-recursive mutex related with the identifier, non-recursive mutex related with the identifier,
and always holding the mutex when calling any function marked and always holding the mutex when calling any function marked
as racy on that identifier, as racy on that identifier,
as they would have to should the identifier be an object under user control. as they would have to should the identifier be
an object under user control.
The non-recursive mutex avoids the MT-Safety issue, The non-recursive mutex avoids the MT-Safety issue,
but it trades one AS-Safety issue for another, but it trades one AS-Safety issue for another,
so use in asynchronous signals remains undefined. so use in asynchronous signals remains undefined.
When the identifier relates to a static buffer used to hold return values, When the identifier relates to a static buffer used to hold return values,
the mutex must be held for as long as the buffer remains in use by the caller. the mutex must be held for as long as the buffer remains in use
by the caller.
Many functions that return pointers to static buffers offer reentrant Many functions that return pointers to static buffers offer reentrant
variants that store return values in caller-supplied buffers instead. variants that store return values in caller-supplied buffers instead.
In some cases, such as In some cases, such as
@ -548,7 +552,8 @@ Functions marked with
as a MT-Safety issue as a MT-Safety issue
(that implies an identical AS-Safety issue, omitted for brevity) (that implies an identical AS-Safety issue, omitted for brevity)
may temporarily install a signal handler for internal purposes, may temporarily install a signal handler for internal purposes,
which may interfere with other uses of the signal, identified after a colon. which may interfere with other uses of the signal,
identified after a colon.
This safety problem can be worked around by ensuring that no other uses This safety problem can be worked around by ensuring that no other uses
of the signal will take place for the duration of the call. of the signal will take place for the duration of the call.
@ -593,7 +598,8 @@ concurrent and reentrant interactions with it,
by not using it in signal handlers or blocking signals that might use it, by not using it in signal handlers or blocking signals that might use it,
and holding a lock while calling these functions and interacting and holding a lock while calling these functions and interacting
with the terminal. with the terminal.
This lock should also be used for mutual exclusion with functions marked with This lock should also be used for mutual exclusion with
functions marked with
.IR race:tcattr(fd) , .IR race:tcattr(fd) ,
where where
.I fd .I fd
@ -644,7 +650,8 @@ because functions that modify the locale object are marked with
and regarded as unsafe. and regarded as unsafe.
Being unsafe, the latter are not to be called when multiple threads Being unsafe, the latter are not to be called when multiple threads
are running or asynchronous signals are enabled, are running or asynchronous signals are enabled,
and so the locale can be considered effectively constant in these contexts, and so the locale can be considered effectively constant
in these contexts,
which makes the former safe. which makes the former safe.
.\" Should the locking strategy suggested under @code{const} be used, .\" Should the locking strategy suggested under @code{const} be used,
@ -784,8 +791,8 @@ Functions marked with
.I cwd .I cwd
as an MT-Safety issue may temporarily as an MT-Safety issue may temporarily
change the current working directory during their execution, change the current working directory during their execution,
which may cause relative pathnames to be resolved in unexpected ways in other which may cause relative pathnames to be resolved in unexpected ways in
threads or within asynchronous signal or cancellation handlers. other threads or within asynchronous signal or cancellation handlers.
This is not enough of a reason to mark so-marked functions as MT-Unsafe or This is not enough of a reason to mark so-marked functions as MT-Unsafe or
AS-Unsafe, but when this behavior is optional (e.g., AS-Unsafe, but when this behavior is optional (e.g.,
@ -861,6 +868,7 @@ is NULL, or global variable
.I one_per_line .I one_per_line
is nonzero. is nonzero.
When all marks that render a function unsafe are adorned with such conditions, When all marks that render a function unsafe are
adorned with such conditions,
and none of the named conditions hold, and none of the named conditions hold,
then the function can be regarded as safe. then the function can be regarded as safe.