From 743c01ad28e6a90c82d9b000a29420d6cafb2bdb Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sat, 18 Oct 2014 11:13:26 +0200 Subject: [PATCH] attributes.7: srcfix Signed-off-by: Michael Kerrisk --- man7/attributes.7 | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/man7/attributes.7 b/man7/attributes.7 index 4b0e61c45..ac50f6c21 100644 --- a/man7/attributes.7 +++ b/man7/attributes.7 @@ -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.