Unsafe Features (The GNU C Library)

#### 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.