1.2.2.2 Unsafe Features

Functions that are unsafe to call in certain contexts are annotated with keywords that document their features that make them unsafe to call. AS-Unsafe features in this section indicate the functions are never safe to call when asynchronous signals are enabled. AC-Unsafe features indicate they are never safe to call when asynchronous cancellation is enabled. There are no MT-Unsafe marks in this section.

• lock

  Functions marked with lock as an AS-Unsafe feature may be interrupted by a signal while holding a non-recursive lock. If the signal handler calls another such function that takes the same lock, the result is a deadlock.

  Functions annotated with lock as an AC-Unsafe feature may, if cancelled asynchronously, fail to release a lock that would have been released if their execution had not been interrupted by asynchronous thread cancellation. Once a lock is left taken, attempts to take that lock will block indefinitely.

• corrupt

  Functions marked with corrupt as an AS-Unsafe feature may corrupt data structures and misbehave when they interrupt, or are interrupted by, another such function. Unlike functions marked with lock, these take recursive locks to avoid MT-Safety problems, but this is not enough to stop a signal handler from observing a partially-updated data structure. Further corruption may arise from the interrupted function’s failure to notice updates made by signal handlers.

  Functions marked with corrupt as an AC-Unsafe feature may leave data structures in a corrupt, partially updated state. Subsequent uses of the data structure may misbehave.

• heap

  Functions marked with heap may call heap memory management functions from the malloc/free family of functions and are only as safe as those functions. This note is thus equivalent to:

  | AS-Unsafe lock | AC-Unsafe lock fd mem |

• dlopen

  Functions marked with dlopen use the dynamic loader to load shared libraries into the current execution image. This involves opening files, mapping them into memory, allocating additional memory, resolving symbols, applying relocations and more, all of this while holding internal dynamic loader locks.

  The locks are enough for these functions to be AS- and AC-Unsafe, but other issues may arise. At present this is a placeholder for all potential safety issues raised by dlopen.

• plugin

  Functions annotated with plugin may run code from plugins that may be external to the GNU C Library. Such plugin functions are assumed to be MT-Safe, AS-Unsafe and AC-Unsafe. Examples of such plugins are stack unwinding libraries, name service switch (NSS) and character set conversion (iconv) back-ends.

  Although the plugins mentioned as examples are all brought in by means of dlopen, the plugin keyword does not imply any direct involvement of the dynamic loader or the libdl interfaces, those are covered by dlopen. For example, if one function loads a module and finds the addresses of some of its functions, while another just calls those already-resolved functions, the former will be marked with dlopen, whereas the latter will get the plugin. When a single function takes all of these actions, then it gets both marks.

• i18n

  Functions marked with i18n may call internationalization functions of the gettext family and will be only as safe as those functions. This note is thus equivalent to:

  | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt |

• timer

  Functions marked with timer use the alarm function or similar to set a time-out for a system call or a long-running operation. In a multi-threaded program, there is a risk that the time-out signal will be delivered to a different thread, thus failing to interrupt the intended thread. Besides being MT-Unsafe, such functions are always AS-Unsafe, because calling them in signal handlers may interfere with timers set in the interrupted code, and AC-Unsafe, because there is no safe way to guarantee an earlier timer will be reset in case of asynchronous cancellation.