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.
lockFunctions marked with
lockas 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.
corruptFunctions marked with
corruptas 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.
heapFunctions marked with
heapmay call heap memory management functions from the
freefamily of functions and are only as safe as those functions. This note is thus equivalent to:
| AS-Unsafe lock | AC-Unsafe lock fd mem |
dlopenFunctions marked with
dlopenuse 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
pluginFunctions annotated with
pluginmay 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
dlopen, whereas the latter will get the
a single function takes all of these actions, then it gets both marks.
i18nFunctions marked with
i18nmay call internationalization functions of the
gettextfamily 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 |
timerFunctions marked with
alarmfunction 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.