POSIX Safety Concepts
lastmod 2022-10-07created 2017-09-247 edits
Levels indicating the degree of safety of the functions defined by POSIX.
Preliminary
This manual documents various safety properties of GNU C Library functions, in lines that follow their prototypes and look like:
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.
- AS-Safe or Async-Signal-Safe functions are safe to call from asynchronous signal handlers. AS, in AS-Safe, stands for Asynchronous Signal.
- AC-Safe or Async-Cancel-Safe functions are safe to call when asynchronous cancellation is enabled. AC in AC-Safe stands for Asynchronous Cancellation.
- 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.
- Preliminary safety properties are documented, indicating these properties may not be counted on in future releases of the GNU C Library.
Thread-Safe functions
MT-Safe (Multi Thread)
Safe to use in a multithreaded environment, since memory synchronization techniques and the like are not used
Being MT-Safe does not imply that a function is atomic, nor that it uses any of the memory synchronization mechanisms POSIX exposes to users. Calling MT-Safe functions in sequence may not yield an MT-Safe combination. For example, a thread calling 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, 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.
Async-Signal-Safe functions
- (SP) async-signal safe :: Moment Log
- Signal Handlers and Async-Signal Safety (Multithreaded Programming Guide)
- signal-safety(7) - Linux manual page
- Async-signal-safe functions
AS-Safe (Asynchronous Signal)
Safe to use in asynchronous signal handlers
Many AS-Safe functions may set errno or modify the floating-point environment, because doing so makes them unsuitable for use in signal handlers. However, programs could misbehave if asynchronous signal handlers modify this thread-local state, and the signal handling machinery cannot be relied 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.
Async-Cancel-Safe functions
AC-Safe (Asynchronous Cancellation)
Safe to call during asynchronous cancellation
The POSIX standard defines three functions as 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.
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, the resulting environment may also be internally inconsistent.
MT-Unsafe, AS-Unsafe, AC-Unsafe
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.