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
of the memory synchronization mechanisms POSIX exposes to users.
It is even possible that calling MT-Safe functions in sequence does not yield
an MT-Safe combination.
It is even possible that calling MT-Safe functions in sequence
does not yield an MT-Safe combination.
For example, having a thread call two MT-Safe
functions one right after the other does not guarantee behavior
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
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
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
access user-supplied objects in unsafe ways should users fail to ensure
the accesses are well defined.
The notion prevails that users are expected to safeguard against data races
any user-supplied objects that the library accesses on their behalf.
The notion prevails that users are expected to safeguard against
data races any user-supplied objects that the library accesses
on their behalf.
.\" 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,
and always holding the mutex when calling any function marked
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,
but it trades one AS-Safety issue for another,
so use in asynchronous signals remains undefined.
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
variants that store return values in caller-supplied buffers instead.
In some cases, such as
@ -548,7 +552,8 @@ Functions marked with
as a MT-Safety issue
(that implies an identical AS-Safety issue, omitted for brevity)
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
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,
and holding a lock while calling these functions and interacting
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) ,
where
.I fd
@ -644,7 +650,8 @@ because functions that modify the locale object are marked with
and regarded as unsafe.
Being unsafe, the latter are not to be called when multiple threads
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.
.\" Should the locking strategy suggested under @code{const} be used,
@ -784,8 +791,8 @@ Functions marked with
.I cwd
as an MT-Safety issue may temporarily
change the current working directory during their execution,
which may cause relative pathnames to be resolved in unexpected ways in other
threads or within asynchronous signal or cancellation handlers.
which may cause relative pathnames to be resolved in unexpected ways in
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
AS-Unsafe, but when this behavior is optional (e.g.,
@ -861,6 +868,7 @@ is NULL, or global variable
.I one_per_line
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,
then the function can be regarded as safe.