mirror of https://github.com/mkerrisk/man-pages
attributes.7: srcfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
8fd8d7d766
commit
743c01ad28
|
@ -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.
|
||||||
|
|
Loading…
Reference in New Issue