This manual documents various safety properties of GNU C Library functions, in lines that follow their prototypes and look like:
Preliminary: | MT-Safe | AS-Safe | AC-Safe |
The properties are assessed according to the criteria set forth in the POSIX standard for such safety contexts as Thread-, Async-Signal- and Async-Cancel- -Safety. Intuitive definitions of these properties, attempting to capture the meaning of the standard definitions, follow.
MT-Safe or Thread-Safe functions are safe to call in the presence
of other threads. 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. 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, since concurrent calls in other threads may interfere in a destructive way.
Whole-program optimizations that could inline functions across library interfaces may expose unsafe reordering, and so performing inlining across the GNU C Library interface is not recommended. The documented MT-Safety status is not guaranteed under whole-program optimization. However, functions defined in user-visible headers are designed to be safe for inlining.
AS-Safe or Async-Signal-Safe functions are safe to call from
asynchronous signal handlers. AS, in AS-Safe, stands for Asynchronous
Signal.
Many functions that are AS-Safe may set errno, or modify the
floating-point environment, because their doing so does not make them
unsuitable for use in signal handlers. However, programs could
misbehave should asynchronous signal handlers modify this thread-local
state, and the signal handling machinery cannot be counted on to
preserve it. Therefore, signal handlers that call functions that may
set errno or modify the floating-point environment must
save their original values, and restore them before returning.
AC-Safe or Async-Cancel-Safe functions are safe to call when
asynchronous cancellation is enabled. AC in AC-Safe stands for
Asynchronous Cancellation.
The POSIX standard defines only three functions to be AC-Safe, namely
pthread_cancel, pthread_setcancelstate, and
pthread_setcanceltype. At present the GNU C Library provides no
guarantees beyond these three functions, but does document which
functions are presently AC-Safe. This documentation is provided for use
by the GNU C Library developers.
Just like signal handlers, cancellation cleanup routines must configure the floating point environment they require. The routines cannot assume a floating point environment, particularly when asynchronous cancellation is enabled. If the configuration of the floating point environment cannot be performed atomically then it is also possible that the environment encountered is internally inconsistent.
MT-Unsafe, AS-Unsafe, AC-Unsafe functions are not
safe to call within the safety contexts described above. Calling them
within such contexts invokes undefined behavior.
Functions not explicitly documented as safe in a safety context should be regarded as Unsafe.
Preliminary safety properties are documented, indicating these
properties may not be counted on in future releases of
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.
Although we strive to abide by the standards, in some cases our
implementation is safe even when the standard does not demand safety,
and in other cases our implementation does not meet the standard safety
requirements. The latter are most likely bugs; the former, when marked
as Preliminary, should not be counted on: future standards may
require changes that are not compatible with the additional safety
properties afforded by the current implementation.
Furthermore, the POSIX standard does not offer a detailed definition of safety. We assume that, by “safe to call”, POSIX means that, as long as the program does not invoke undefined behavior, the “safe to call” function behaves as specified, and does not cause other functions to deviate from their specified behavior. We have chosen to use its loose definitions of safety, not because they are the best definitions to use, but because choosing them harmonizes this manual with POSIX.
Please keep in mind that these are preliminary definitions and annotations, and certain aspects of the definitions are still under discussion and might be subject to clarification or change.
Over time, we envision evolving the preliminary safety notes into stable
commitments, as stable as those of our interfaces. As we do, we will
remove the Preliminary keyword from safety notes. As long as the
keyword remains, however, they are not to be regarded as a promise of
future behavior.
Other keywords that appear in safety notes are defined in subsequent sections.