| 1 |
.\" Copyright 2014, Red Hat, Inc. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 5 |
.\" |
| 6 |
.TH attributes 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
attributes \- POSIX safety concepts |
| 9 |
.SH DESCRIPTION |
| 10 |
.\" |
| 11 |
.\" |
| 12 |
.IR Note : |
| 13 |
the text of this man page is based on the material taken from |
| 14 |
the "POSIX Safety Concepts" section of the GNU C Library manual. |
| 15 |
Further details on the topics described here can be found in that |
| 16 |
manual. |
| 17 |
.P |
| 18 |
Various function manual pages include a section ATTRIBUTES |
| 19 |
that describes the safety of calling the function in various contexts. |
| 20 |
This section annotates functions with the following safety markings: |
| 21 |
.TP |
| 22 |
.I MT-Safe |
| 23 |
.I MT-Safe |
| 24 |
or |
| 25 |
Thread-Safe functions are safe to call in the presence |
| 26 |
of other threads. |
| 27 |
MT, in MT-Safe, stands for Multi Thread. |
| 28 |
.IP |
| 29 |
Being MT-Safe does not imply a function is atomic, nor that it uses any |
| 30 |
of the memory synchronization mechanisms POSIX exposes to users. |
| 31 |
It is even possible that calling MT-Safe functions in sequence |
| 32 |
does not yield an MT-Safe combination. |
| 33 |
For example, having a thread call two MT-Safe |
| 34 |
functions one right after the other does not guarantee behavior |
| 35 |
equivalent to atomic execution of a combination of both functions, |
| 36 |
since concurrent calls in other threads may interfere in a destructive way. |
| 37 |
.IP |
| 38 |
Whole-program optimizations that could inline functions across library |
| 39 |
interfaces may expose unsafe reordering, and so performing inlining |
| 40 |
across the GNU C Library interface is not recommended. |
| 41 |
The documented |
| 42 |
MT-Safety status is not guaranteed under whole-program optimization. |
| 43 |
However, functions defined in user-visible headers are designed to be |
| 44 |
safe for inlining. |
| 45 |
.\" .TP |
| 46 |
.\" .I AS-Safe |
| 47 |
.\" .I AS-Safe |
| 48 |
.\" or Async-Signal-Safe functions are safe to call from |
| 49 |
.\" asynchronous signal handlers. |
| 50 |
.\" AS, in AS-Safe, stands for Asynchronous Signal. |
| 51 |
.\" |
| 52 |
.\" Many functions that are AS-Safe may set |
| 53 |
.\" .IR errno , |
| 54 |
.\" or modify the floating-point environment, |
| 55 |
.\" because their doing so does not make them |
| 56 |
.\" unsuitable for use in signal handlers. |
| 57 |
.\" However, programs could misbehave should asynchronous signal handlers |
| 58 |
.\" modify this thread-local state, |
| 59 |
.\" and the signal handling machinery cannot be counted on to |
| 60 |
.\" preserve it. |
| 61 |
.\" Therefore, signal handlers that call functions that may set |
| 62 |
.\" .I errno |
| 63 |
.\" or modify the floating-point environment |
| 64 |
.\" .I must |
| 65 |
.\" save their original values, and restore them before returning. |
| 66 |
.\" .TP |
| 67 |
.\" .I AC-Safe |
| 68 |
.\" .I AC-Safe |
| 69 |
.\" or Async-Cancel-Safe functions are safe to call when |
| 70 |
.\" asynchronous cancelation is enabled. |
| 71 |
.\" AC in AC-Safe stands for Asynchronous Cancelation. |
| 72 |
.\" |
| 73 |
.\" The POSIX standard defines only three functions to be AC-Safe, namely |
| 74 |
.\" .BR pthread_cancel (3), |
| 75 |
.\" .BR pthread_setcancelstate (3), |
| 76 |
.\" and |
| 77 |
.\" .BR pthread_setcanceltype (3). |
| 78 |
.\" At present the GNU C Library provides no |
| 79 |
.\" guarantees beyond these three functions, |
| 80 |
.\" but does document which functions are presently AC-Safe. |
| 81 |
.\" This documentation is provided for use |
| 82 |
.\" by the GNU C Library developers. |
| 83 |
.\" |
| 84 |
.\" Just like signal handlers, cancelation cleanup routines must configure |
| 85 |
.\" the floating point environment they require. |
| 86 |
.\" The routines cannot assume a floating point environment, |
| 87 |
.\" particularly when asynchronous cancelation is enabled. |
| 88 |
.\" If the configuration of the floating point |
| 89 |
.\" environment cannot be performed atomically then it is also possible that |
| 90 |
.\" the environment encountered is internally inconsistent. |
| 91 |
.TP |
| 92 |
.I MT-Unsafe \" ,\~ AS-Unsafe ,\~ AC-Unsafe |
| 93 |
.I MT-Unsafe \" ,\~ AS-Unsafe ,\~ AC-Unsafe |
| 94 |
functions are not safe to call in a multithreaded programs. |
| 95 |
.\" functions are not |
| 96 |
.\" safe to call within the safety contexts described above. |
| 97 |
.\" Calling them |
| 98 |
.\" within such contexts invokes undefined behavior. |
| 99 |
.\" |
| 100 |
.\" Functions not explicitly documented as safe in a safety context should |
| 101 |
.\" be regarded as Unsafe. |
| 102 |
.\" .TP |
| 103 |
.\" .I Preliminary |
| 104 |
.\" .I Preliminary |
| 105 |
.\" safety properties are documented, indicating these |
| 106 |
.\" properties may |
| 107 |
.\" .I not |
| 108 |
.\" be counted on in future releases of |
| 109 |
.\" the GNU C Library. |
| 110 |
.\" |
| 111 |
.\" Such preliminary properties are the result of an assessment of the |
| 112 |
.\" properties of our current implementation, |
| 113 |
.\" rather than of what is mandated and permitted |
| 114 |
.\" by current and future standards. |
| 115 |
.\" |
| 116 |
.\" Although we strive to abide by the standards, in some cases our |
| 117 |
.\" implementation is safe even when the standard does not demand safety, |
| 118 |
.\" and in other cases our implementation does not meet the standard safety |
| 119 |
.\" requirements. |
| 120 |
.\" The latter are most likely bugs; the former, when marked |
| 121 |
.\" as |
| 122 |
.\" .IR Preliminary , |
| 123 |
.\" should not be counted on: future standards may |
| 124 |
.\" require changes that are not compatible with the additional safety |
| 125 |
.\" properties afforded by the current implementation. |
| 126 |
.\" |
| 127 |
.\" Furthermore, |
| 128 |
.\" the POSIX standard does not offer a detailed definition of safety. |
| 129 |
.\" We assume that, by "safe to call", POSIX means that, |
| 130 |
.\" as long as the program does not invoke undefined behavior, |
| 131 |
.\" the "safe to call" function behaves as specified, |
| 132 |
.\" and does not cause other functions to deviate from their specified behavior. |
| 133 |
.\" We have chosen to use its loose |
| 134 |
.\" definitions of safety, not because they are the best definitions to use, |
| 135 |
.\" but because choosing them harmonizes this manual with POSIX. |
| 136 |
.\" |
| 137 |
.\" Please keep in mind that these are preliminary definitions and annotations, |
| 138 |
.\" and certain aspects of the definitions are still under |
| 139 |
.\" discussion and might be subject to clarification or change. |
| 140 |
.\" |
| 141 |
.\" Over time, |
| 142 |
.\" we envision evolving the preliminary safety notes into stable commitments, |
| 143 |
.\" as stable as those of our interfaces. |
| 144 |
.\" As we do, we will remove the |
| 145 |
.\" .I Preliminary |
| 146 |
.\" keyword from safety notes. |
| 147 |
.\" As long as the keyword remains, however, |
| 148 |
.\" they are not to be regarded as a promise of future behavior. |
| 149 |
.P |
| 150 |
Other keywords that appear in safety notes are defined in subsequent sections. |
| 151 |
.\" |
| 152 |
.\" |
| 153 |
.\" .SS Unsafe features |
| 154 |
.\" Functions that are unsafe to call in certain contexts are annotated with |
| 155 |
.\" keywords that document their features that make them unsafe to call. |
| 156 |
.\" AS-Unsafe features in this section indicate the functions are never safe |
| 157 |
.\" to call when asynchronous signals are enabled. |
| 158 |
.\" AC-Unsafe features |
| 159 |
.\" indicate they are never safe to call when asynchronous cancelation is |
| 160 |
.\" .\" enabled. |
| 161 |
.\" There are no MT-Unsafe marks in this section. |
| 162 |
.\" .TP |
| 163 |
.\" .\" .I code |
| 164 |
.\" Functions marked with |
| 165 |
.\" .I lock |
| 166 |
.\" as an AS-Unsafe feature may be |
| 167 |
.\" .\" interrupted by a signal while holding a non-recursive lock. |
| 168 |
.\" If the signal handler calls another such function that takes the same lock, |
| 169 |
.\" the result is a deadlock. |
| 170 |
.\" |
| 171 |
.\" Functions annotated with |
| 172 |
.\" .I lock |
| 173 |
.\" as an AC-Unsafe feature may, if canceled asynchronously, |
| 174 |
.\" fail to release a lock that would have been released if their execution |
| 175 |
.\" had not been interrupted by asynchronous thread cancelation. |
| 176 |
.\" Once a lock is left taken, |
| 177 |
.\" attempts to take that lock will block indefinitely. |
| 178 |
.\" .TP |
| 179 |
.\" .I corrupt |
| 180 |
.\" Functions marked with |
| 181 |
.\" .\" .I corrupt |
| 182 |
.\" as an AS-Unsafe feature may corrupt |
| 183 |
.\" data structures and misbehave when they interrupt, |
| 184 |
.\" or are interrupted by, another such function. |
| 185 |
.\" Unlike functions marked with |
| 186 |
.\" .IR lock , |
| 187 |
.\" these take recursive locks to avoid MT-Safety problems, |
| 188 |
.\" but this is not enough to stop a signal handler from observing |
| 189 |
.\" a partially-updated data structure. |
| 190 |
.\" Further corruption may arise from the interrupted function's |
| 191 |
.\" failure to notice updates made by signal handlers. |
| 192 |
.\" |
| 193 |
.\" Functions marked with |
| 194 |
.\" .I corrupt |
| 195 |
.\" as an AC-Unsafe feature may leave |
| 196 |
.\" data structures in a corrupt, partially updated state. |
| 197 |
.\" Subsequent uses of the data structure may misbehave. |
| 198 |
.\" |
| 199 |
.\" .\" A special case, probably not worth documenting separately, involves |
| 200 |
.\" .\" reallocing, or even freeing pointers. Any case involving free could |
| 201 |
.\" .\" be easily turned into an ac-safe leak by resetting the pointer before |
| 202 |
.\" .\" releasing it; I don't think we have any case that calls for this sort |
| 203 |
.\" .\" of fixing. Fixing the realloc cases would require a new interface: |
| 204 |
.\" .\" instead of @code{ptr=realloc(ptr,size)} we'd have to introduce |
| 205 |
.\" .\" @code{acsafe_realloc(&ptr,size)} that would modify ptr before |
| 206 |
.\" .\" releasing the old memory. The ac-unsafe realloc could be implemented |
| 207 |
.\" .\" in terms of an internal interface with this semantics (say |
| 208 |
.\" .\" __acsafe_realloc), but since realloc can be overridden, the function |
| 209 |
.\" .\" we call to implement realloc should not be this internal interface, |
| 210 |
.\" .\" but another internal interface that calls __acsafe_realloc if realloc |
| 211 |
.\" .\" was not overridden, and calls the overridden realloc with async |
| 212 |
.\" .\" cancel disabled. --lxoliva |
| 213 |
.\" .TP |
| 214 |
.\" .I heap |
| 215 |
.\" Functions marked with |
| 216 |
.\" .I heap |
| 217 |
.\" may call heap memory management functions from the |
| 218 |
.\" .BR malloc (3)/ free (3) |
| 219 |
.\" family of functions and are only as safe as those functions. |
| 220 |
.\" This note is thus equivalent to: |
| 221 |
.\" |
| 222 |
.\" | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| 223 |
.\" .\" @sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} |
| 224 |
.\" .\" |
| 225 |
.\" .\" Check for cases that should have used plugin instead of or in |
| 226 |
.\" .\" addition to this. Then, after rechecking gettext, adjust i18n if |
| 227 |
.\" .\" needed. |
| 228 |
.\" .TP |
| 229 |
.\" .I dlopen |
| 230 |
.\" Functions marked with |
| 231 |
.\" .I dlopen |
| 232 |
.\" use the dynamic loader to load |
| 233 |
.\" shared libraries into the current execution image. |
| 234 |
.\" This involves opening files, mapping them into memory, |
| 235 |
.\" allocating additional memory, resolving symbols, |
| 236 |
.\" applying relocations and more, |
| 237 |
.\" all of this while holding internal dynamic loader locks. |
| 238 |
.\" |
| 239 |
.\" The locks are enough for these functions to be AS-Unsafe and AC-Unsafe, |
| 240 |
.\" but other issues may arise. |
| 241 |
.\" At present this is a placeholder for all |
| 242 |
.\" potential safety issues raised by |
| 243 |
.\" .BR dlopen (3). |
| 244 |
.\" |
| 245 |
.\" .\" dlopen runs init and fini sections of the module; does this mean |
| 246 |
.\" .\" dlopen always implies plugin? |
| 247 |
.\" .TP |
| 248 |
.\" .I plugin |
| 249 |
.\" Functions annotated with |
| 250 |
.\" .I plugin |
| 251 |
.\" may run code from plugins that |
| 252 |
.\" may be external to the GNU C Library. |
| 253 |
.\" Such plugin functions are assumed to be |
| 254 |
.\" MT-Safe, AS-Unsafe and AC-Unsafe. |
| 255 |
.\" Examples of such plugins are stack unwinding libraries, |
| 256 |
.\" name service switch (NSS) and character set conversion (iconv) back-ends. |
| 257 |
.\" |
| 258 |
.\" Although the plugins mentioned as examples are all brought in by means |
| 259 |
.\" of dlopen, the |
| 260 |
.\" .I plugin |
| 261 |
.\" keyword does not imply any direct |
| 262 |
.\" involvement of the dynamic loader or the |
| 263 |
.\" .I libdl |
| 264 |
.\" interfaces, |
| 265 |
.\" those are covered by |
| 266 |
.\" .IR dlopen . |
| 267 |
.\" For example, if one function loads a module and finds the addresses |
| 268 |
.\" of some of its functions, |
| 269 |
.\" while another just calls those already-resolved functions, |
| 270 |
.\" the former will be marked with |
| 271 |
.\" .IR dlopen , |
| 272 |
.\" whereas the latter will get the |
| 273 |
.\" .IR plugin . |
| 274 |
.\" When a single function takes all of these actions, then it gets both marks. |
| 275 |
.\" .TP |
| 276 |
.\" .I i18n |
| 277 |
.\" Functions marked with |
| 278 |
.\" .I i18n |
| 279 |
.\" may call internationalization |
| 280 |
.\" functions of the |
| 281 |
.\" .BR gettext (3) |
| 282 |
.\" family and will be only as safe as those |
| 283 |
.\" functions. |
| 284 |
.\" This note is thus equivalent to: |
| 285 |
.\" |
| 286 |
.\" | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt | |
| 287 |
.\" |
| 288 |
.\" .\" @sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}} |
| 289 |
.\" .TP |
| 290 |
.\" .I timer |
| 291 |
.\" Functions marked with |
| 292 |
.\" .I timer |
| 293 |
.\" use the |
| 294 |
.\" .BR alarm (3) |
| 295 |
.\" function or |
| 296 |
.\" similar to set a time-out for a system call or a long-running operation. |
| 297 |
.\" In a multi-threaded program, there is a risk that the time-out signal |
| 298 |
.\" will be delivered to a different thread, |
| 299 |
.\" thus failing to interrupt the intended thread. |
| 300 |
.\" Besides being MT-Unsafe, such functions are always |
| 301 |
.\" AS-Unsafe, because calling them in signal handlers may interfere with |
| 302 |
.\" timers set in the interrupted code, and AC-Unsafe, |
| 303 |
.\" because there is no safe way to guarantee an earlier timer |
| 304 |
.\" will be reset in case of asynchronous cancelation. |
| 305 |
.\" |
| 306 |
.\" |
| 307 |
.SS Conditionally safe features |
| 308 |
For some features that make functions unsafe to call in certain contexts, |
| 309 |
there are known ways to avoid the safety problem other than |
| 310 |
refraining from calling the function altogether. |
| 311 |
The keywords that follow refer to such features, |
| 312 |
and each of their definitions indicates |
| 313 |
how the whole program needs to be constrained in order to remove the |
| 314 |
safety problem indicated by the keyword. |
| 315 |
Only when all the reasons that |
| 316 |
make a function unsafe are observed and addressed, |
| 317 |
by applying the documented constraints, |
| 318 |
does the function become safe to call in a context. |
| 319 |
.TP |
| 320 |
.I init |
| 321 |
Functions marked with |
| 322 |
.I init |
| 323 |
as an MT-Unsafe feature perform |
| 324 |
MT-Unsafe initialization when they are first called. |
| 325 |
.IP |
| 326 |
Calling such a function at least once in single-threaded mode removes |
| 327 |
this specific cause for the function to be regarded as MT-Unsafe. |
| 328 |
If no other cause for that remains, |
| 329 |
the function can then be safely called after other threads are started. |
| 330 |
.\" |
| 331 |
.\" Functions marked with |
| 332 |
.\" .I init |
| 333 |
.\" as an AS-Unsafe or AC-Unsafe feature use the GNU C Library internal |
| 334 |
.\" .I libc_once |
| 335 |
.\" machinery or similar to initialize internal data structures. |
| 336 |
.\" |
| 337 |
.\" If a signal handler interrupts such an initializer, |
| 338 |
.\" and calls any function that also performs |
| 339 |
.\" .I libc_once |
| 340 |
.\" initialization, it will deadlock if the thread library has been loaded. |
| 341 |
.\" |
| 342 |
.\" Furthermore, if an initializer is partially complete before it is canceled |
| 343 |
.\" or interrupted by a signal whose handler requires the same initialization, |
| 344 |
.\" some or all of the initialization may be performed more than once, |
| 345 |
.\" leaking resources or even resulting in corrupt internal data. |
| 346 |
.\" |
| 347 |
.\" Applications that need to call functions marked with |
| 348 |
.\" .I init |
| 349 |
.\" as an AS-Safety or AC-Unsafe feature should ensure |
| 350 |
.\" the initialization is performed |
| 351 |
.\" before configuring signal handlers or enabling cancelation, |
| 352 |
.\" so that the AS-Safety and AC-Safety issues related with |
| 353 |
.\" .I libc_once |
| 354 |
.\" do not arise. |
| 355 |
.\" |
| 356 |
.\" .\" We may have to extend the annotations to cover conditions in which |
| 357 |
.\" .\" initialization may or may not occur, since an initial call in a safe |
| 358 |
.\" .\" context is no use if the initialization doesn't take place at that |
| 359 |
.\" .\" time: it doesn't remove the risk for later calls. |
| 360 |
.TP |
| 361 |
.I race |
| 362 |
Functions annotated with |
| 363 |
.I race |
| 364 |
as an MT-Safety issue operate on |
| 365 |
objects in ways that may cause data races or similar forms of |
| 366 |
destructive interference out of concurrent execution. |
| 367 |
In some cases, |
| 368 |
the objects are passed to the functions by users; |
| 369 |
in others, they are used by the functions to return values to users; |
| 370 |
in others, they are not even exposed to users. |
| 371 |
.\" |
| 372 |
.\" We consider access to objects passed as (indirect) arguments to |
| 373 |
.\" functions to be data race free. |
| 374 |
.\" The assurance of data race free objects |
| 375 |
.\" is the caller's responsibility. |
| 376 |
.\" We will not mark a function as MT-Unsafe or AS-Unsafe |
| 377 |
.\" if it misbehaves when users fail to take the measures required by |
| 378 |
.\" POSIX to avoid data races when dealing with such objects. |
| 379 |
.\" As a general rule, if a function is documented as reading from |
| 380 |
.\" an object passed (by reference) to it, or modifying it, |
| 381 |
.\" users ought to use memory synchronization primitives |
| 382 |
.\" to avoid data races just as they would should they perform |
| 383 |
.\" the accesses themselves rather than by calling the library function. |
| 384 |
.\" Standard I/O |
| 385 |
.\" .RI ( "FILE *" ) |
| 386 |
.\" streams are the exception to the general rule, |
| 387 |
.\" in that POSIX mandates the library to guard against data races |
| 388 |
.\" in many functions that manipulate objects of this specific opaque type. |
| 389 |
.\" We regard this as a convenience provided to users, |
| 390 |
.\" rather than as a general requirement whose expectations |
| 391 |
.\" should extend to other types. |
| 392 |
.\" |
| 393 |
.\" In order to remind users that guarding certain arguments is their |
| 394 |
.\" responsibility, we will annotate functions that take objects of certain |
| 395 |
.\" types as arguments. |
| 396 |
.\" We draw the line for objects passed by users as follows: |
| 397 |
.\" objects whose types are exposed to users, |
| 398 |
.\" and that users are expected to access directly, |
| 399 |
.\" such as memory buffers, strings, |
| 400 |
.\" and various user-visible structured types, do |
| 401 |
.\" .I not |
| 402 |
.\" give reason for functions to be annotated with |
| 403 |
.\" .IR race . |
| 404 |
.\" It would be noisy and redundant with the general requirement, |
| 405 |
.\" and not many would be surprised by the library's lack of internal |
| 406 |
.\" guards when accessing objects that can be accessed directly by users. |
| 407 |
.\" |
| 408 |
.\" As for objects that are opaque or opaque-like, |
| 409 |
.\" in that they are to be manipulated only by passing them |
| 410 |
.\" to library functions (e.g., |
| 411 |
.\" .IR FILE , |
| 412 |
.\" .IR DIR , |
| 413 |
.\" .IR obstack , |
| 414 |
.\" .IR iconv_t ), |
| 415 |
.\" there might be additional expectations as to internal coordination |
| 416 |
.\" of access by the library. |
| 417 |
.\" We will annotate, with |
| 418 |
.\" .I race |
| 419 |
.\" followed by a colon and the argument name, |
| 420 |
.\" functions that take such objects but that do not take |
| 421 |
.\" care of synchronizing access to them by default. |
| 422 |
.\" For example, |
| 423 |
.\" .I FILE |
| 424 |
.\" stream |
| 425 |
.\" .I unlocked |
| 426 |
.\" functions |
| 427 |
.\" .RB ( unlocked_stdio (3)) |
| 428 |
.\" will be annotated, |
| 429 |
.\" but those that perform implicit locking on |
| 430 |
.\" .I FILE |
| 431 |
.\" streams by default will not, |
| 432 |
.\" even though the implicit locking may be disabled on a per-stream basis. |
| 433 |
.\" |
| 434 |
.\" In either case, we will not regard as MT-Unsafe functions that may |
| 435 |
.\" access user-supplied objects in unsafe ways should users fail to ensure |
| 436 |
.\" the accesses are well defined. |
| 437 |
.\" The notion prevails that users are expected to safeguard against |
| 438 |
.\" data races any user-supplied objects that the library accesses |
| 439 |
.\" on their behalf. |
| 440 |
.\" |
| 441 |
.\" .\" The above describes @mtsrace; @mtasurace is described below. |
| 442 |
.\" |
| 443 |
.\" This user responsibility does not apply, however, |
| 444 |
.\" to objects controlled by the library itself, |
| 445 |
.\" such as internal objects and static buffers used |
| 446 |
.\" to return values from certain calls. |
| 447 |
.\" When the library doesn't guard them against concurrent uses, |
| 448 |
.\" these cases are regarded as MT-Unsafe and AS-Unsafe (although the |
| 449 |
.\" .I race |
| 450 |
.\" mark under AS-Unsafe will be omitted |
| 451 |
.\" as redundant with the one under MT-Unsafe). |
| 452 |
.\" As in the case of user-exposed objects, |
| 453 |
.\" the mark may be followed by a colon and an identifier. |
| 454 |
.\" The identifier groups all functions that operate on a |
| 455 |
.\" certain unguarded object; users may avoid the MT-Safety issues related |
| 456 |
.\" with unguarded concurrent access to such internal objects by creating a |
| 457 |
.\" non-recursive mutex related with the identifier, |
| 458 |
.\" and always holding the mutex when calling any function marked |
| 459 |
.\" as racy on that identifier, |
| 460 |
.\" as they would have to should the identifier be |
| 461 |
.\" an object under user control. |
| 462 |
.\" The non-recursive mutex avoids the MT-Safety issue, |
| 463 |
.\" but it trades one AS-Safety issue for another, |
| 464 |
.\" so use in asynchronous signals remains undefined. |
| 465 |
.\" |
| 466 |
.\" When the identifier relates to a static buffer used to hold return values, |
| 467 |
.\" the mutex must be held for as long as the buffer remains in use |
| 468 |
.\" by the caller. |
| 469 |
.\" Many functions that return pointers to static buffers offer reentrant |
| 470 |
.\" variants that store return values in caller-supplied buffers instead. |
| 471 |
.\" In some cases, such as |
| 472 |
.\" .BR tmpname (3), |
| 473 |
.\" the variant is chosen not by calling an alternate entry point, |
| 474 |
.\" but by passing a non-null pointer to the buffer in which the |
| 475 |
.\" returned values are to be stored. |
| 476 |
.\" These variants are generally preferable in multi-threaded programs, |
| 477 |
.\" although some of them are not MT-Safe because of other internal buffers, |
| 478 |
.\" also documented with |
| 479 |
.\" .I race |
| 480 |
.\" notes. |
| 481 |
.TP |
| 482 |
.I const |
| 483 |
Functions marked with |
| 484 |
.I const |
| 485 |
as an MT-Safety issue non-atomically |
| 486 |
modify internal objects that are better regarded as constant, |
| 487 |
because a substantial portion of the GNU C Library accesses them without |
| 488 |
synchronization. |
| 489 |
Unlike |
| 490 |
.IR race , |
| 491 |
which causes both readers and |
| 492 |
writers of internal objects to be regarded as MT-Unsafe,\" and AS-Unsafe, |
| 493 |
this mark is applied to writers only. |
| 494 |
Writers remain\" equally |
| 495 |
MT-Unsafe\" and AS-Unsafe |
| 496 |
to call, |
| 497 |
but the then-mandatory constness of objects they |
| 498 |
modify enables readers to be regarded as MT-Safe\" and AS-Safe |
| 499 |
(as long as no other reasons for them to be unsafe remain), |
| 500 |
since the lack of synchronization is not a problem when the |
| 501 |
objects are effectively constant. |
| 502 |
.IP |
| 503 |
The identifier that follows the |
| 504 |
.I const |
| 505 |
mark will appear by itself as a safety note in readers. |
| 506 |
Programs that wish to work around this safety issue, |
| 507 |
so as to call writers, may use a non-recursive |
| 508 |
read-write lock |
| 509 |
associated with the identifier, and guard |
| 510 |
.I all |
| 511 |
calls to functions marked with |
| 512 |
.I const |
| 513 |
followed by the identifier with a write lock, and |
| 514 |
.I all |
| 515 |
calls to functions marked with the identifier |
| 516 |
by itself with a read lock. |
| 517 |
.\" The non-recursive locking removes the MT-Safety problem, |
| 518 |
.\" but it trades one AS-Safety problem for another, |
| 519 |
.\" so use in asynchronous signals remains undefined. |
| 520 |
.\" |
| 521 |
.\" .\" But what if, instead of marking modifiers with const:id and readers |
| 522 |
.\" .\" with just id, we marked writers with race:id and readers with ro:id? |
| 523 |
.\" .\" Instead of having to define each instance of 'id', we'd have a |
| 524 |
.\" .\" general pattern governing all such 'id's, wherein race:id would |
| 525 |
.\" .\" suggest the need for an exclusive/write lock to make the function |
| 526 |
.\" .\" safe, whereas ro:id would indicate 'id' is expected to be read-only, |
| 527 |
.\" .\" but if any modifiers are called (while holding an exclusive lock), |
| 528 |
.\" .\" then ro:id-marked functions ought to be guarded with a read lock for |
| 529 |
.\" .\" safe operation. ro:env or ro:locale, for example, seems to convey |
| 530 |
.\" .\" more clearly the expectations and the meaning, than just env or |
| 531 |
.\" .\" locale. |
| 532 |
.TP |
| 533 |
.I sig |
| 534 |
Functions marked with |
| 535 |
.I sig |
| 536 |
as a MT-Safety issue |
| 537 |
.\" (that implies an identical AS-Safety issue, omitted for brevity) |
| 538 |
may temporarily install a signal handler for internal purposes, |
| 539 |
which may interfere with other uses of the signal, |
| 540 |
identified after a colon. |
| 541 |
.IP |
| 542 |
This safety problem can be worked around by ensuring that no other uses |
| 543 |
of the signal will take place for the duration of the call. |
| 544 |
Holding a non-recursive mutex while calling all functions that use the same |
| 545 |
temporary signal; |
| 546 |
blocking that signal before the call and resetting its |
| 547 |
handler afterwards is recommended. |
| 548 |
.\" |
| 549 |
.\" There is no safe way to guarantee the original signal handler is |
| 550 |
.\" restored in case of asynchronous cancelation, |
| 551 |
.\" therefore so-marked functions are also AC-Unsafe. |
| 552 |
.\" |
| 553 |
.\" .\" fixme: at least deferred cancelation should get it right, and would |
| 554 |
.\" .\" obviate the restoring bit below, and the qualifier above. |
| 555 |
.\" |
| 556 |
.\" Besides the measures recommended to work around the |
| 557 |
.\" MT-Safety and AS-Safety problem, |
| 558 |
.\" in order to avert the cancelation problem, |
| 559 |
.\" disabling asynchronous cancelation |
| 560 |
.\" .I and |
| 561 |
.\" installing a cleanup handler to restore the signal to the desired state |
| 562 |
.\" and to release the mutex are recommended. |
| 563 |
.TP |
| 564 |
.I term |
| 565 |
Functions marked with |
| 566 |
.I term |
| 567 |
as an MT-Safety issue may change the |
| 568 |
terminal settings in the recommended way, namely: call |
| 569 |
.BR tcgetattr (3), |
| 570 |
modify some flags, and then call |
| 571 |
.BR tcsetattr (3), |
| 572 |
this creates a window in which changes made by other threads are lost. |
| 573 |
Thus, functions marked with |
| 574 |
.I term |
| 575 |
are MT-Unsafe. |
| 576 |
.\" The same window enables changes made by asynchronous signals to be lost. |
| 577 |
.\" These functions are also AS-Unsafe, |
| 578 |
.\" but the corresponding mark is omitted as redundant. |
| 579 |
.IP |
| 580 |
It is thus advisable for applications using the terminal to avoid |
| 581 |
concurrent and reentrant interactions with it, |
| 582 |
by not using it in signal handlers or blocking signals that might use it, |
| 583 |
and holding a lock while calling these functions and interacting |
| 584 |
with the terminal. |
| 585 |
This lock should also be used for mutual exclusion with |
| 586 |
functions marked with |
| 587 |
.IR race:tcattr(fd) , |
| 588 |
where |
| 589 |
.I fd |
| 590 |
is a file descriptor for the controlling terminal. |
| 591 |
The caller may use a single mutex for simplicity, |
| 592 |
or use one mutex per terminal, |
| 593 |
even if referenced by different file descriptors. |
| 594 |
.\" |
| 595 |
.\" Functions marked with |
| 596 |
.\" .I term |
| 597 |
.\" as an AC-Safety issue are supposed to |
| 598 |
.\" restore terminal settings to their original state, |
| 599 |
.\" after temporarily changing them, but they may fail to do so if canceled. |
| 600 |
.\" |
| 601 |
.\" .\" fixme: at least deferred cancelation should get it right, and would |
| 602 |
.\" .\" obviate the restoring bit below, and the qualifier above. |
| 603 |
.\" |
| 604 |
.\" Besides the measures recommended to work around the |
| 605 |
.\" MT-Safety and AS-Safety problem, |
| 606 |
.\" in order to avert the cancelation problem, |
| 607 |
.\" disabling asynchronous cancelation |
| 608 |
.\" .I and |
| 609 |
.\" installing a cleanup handler to |
| 610 |
.\" restore the terminal settings to the original state and to release the |
| 611 |
.\" mutex are recommended. |
| 612 |
.\" |
| 613 |
.\" |
| 614 |
.SS Other safety remarks |
| 615 |
Additional keywords may be attached to functions, |
| 616 |
indicating features that do not make a function unsafe to call, |
| 617 |
but that may need to be taken into account in certain classes of programs: |
| 618 |
.TP |
| 619 |
.I locale |
| 620 |
Functions annotated with |
| 621 |
.I locale |
| 622 |
as an MT-Safety issue read from |
| 623 |
the locale object without any form of synchronization. |
| 624 |
Functions |
| 625 |
annotated with |
| 626 |
.I locale |
| 627 |
called concurrently with locale changes may |
| 628 |
behave in ways that do not correspond to any of the locales active |
| 629 |
during their execution, but an unpredictable mix thereof. |
| 630 |
.IP |
| 631 |
We do not mark these functions as MT-Unsafe,\" or AS-Unsafe, |
| 632 |
however, |
| 633 |
because functions that modify the locale object are marked with |
| 634 |
.I const:locale |
| 635 |
and regarded as unsafe. |
| 636 |
Being unsafe, the latter are not to be called when multiple threads |
| 637 |
are running or asynchronous signals are enabled, |
| 638 |
and so the locale can be considered effectively constant |
| 639 |
in these contexts, |
| 640 |
which makes the former safe. |
| 641 |
.\" Should the locking strategy suggested under @code{const} be used, |
| 642 |
.\" failure to guard locale uses is not as fatal as data races in |
| 643 |
.\" general: unguarded uses will @emph{not} follow dangling pointers or |
| 644 |
.\" access uninitialized, unmapped or recycled memory. Each access will |
| 645 |
.\" read from a consistent locale object that is or was active at some |
| 646 |
.\" point during its execution. Without synchronization, however, it |
| 647 |
.\" cannot even be assumed that, after a change in locale, earlier |
| 648 |
.\" locales will no longer be used, even after the newly-chosen one is |
| 649 |
.\" used in the thread. Nevertheless, even though unguarded reads from |
| 650 |
.\" the locale will not violate type safety, functions that access the |
| 651 |
.\" locale multiple times may invoke all sorts of undefined behavior |
| 652 |
.\" because of the unexpected locale changes. |
| 653 |
.TP |
| 654 |
.I env |
| 655 |
Functions marked with |
| 656 |
.I env |
| 657 |
as an MT-Safety issue access the |
| 658 |
environment with |
| 659 |
.BR getenv (3) |
| 660 |
or similar, without any guards to ensure |
| 661 |
safety in the presence of concurrent modifications. |
| 662 |
.IP |
| 663 |
We do not mark these functions as MT-Unsafe,\" or AS-Unsafe, |
| 664 |
however, |
| 665 |
because functions that modify the environment are all marked with |
| 666 |
.I const:env |
| 667 |
and regarded as unsafe. |
| 668 |
Being unsafe, the latter are not to be called when multiple threads |
| 669 |
are running or asynchronous signals are enabled, |
| 670 |
and so the environment can be considered |
| 671 |
effectively constant in these contexts, |
| 672 |
which makes the former safe. |
| 673 |
.TP |
| 674 |
.I hostid |
| 675 |
Functions marked with |
| 676 |
.I hostid |
| 677 |
as an MT-Safety issue read from the system-wide data structures that |
| 678 |
hold the "host ID" of the machine. |
| 679 |
These data structures cannot generally be modified atomically. |
| 680 |
Since it is expected that the "host ID" will not normally change, |
| 681 |
the function that reads from it |
| 682 |
.RB ( gethostid (3)) |
| 683 |
is regarded as safe, |
| 684 |
whereas the function that modifies it |
| 685 |
.RB ( sethostid (3)) |
| 686 |
is marked with |
| 687 |
.IR const:hostid , |
| 688 |
indicating it may require special care if it is to be called. |
| 689 |
In this specific case, |
| 690 |
the special care amounts to system-wide |
| 691 |
(not merely intra-process) coordination. |
| 692 |
.TP |
| 693 |
.I sigintr |
| 694 |
Functions marked with |
| 695 |
.I sigintr |
| 696 |
as an MT-Safety issue access the |
| 697 |
GNU C Library |
| 698 |
.I _sigintr |
| 699 |
internal data structure without any guards to ensure |
| 700 |
safety in the presence of concurrent modifications. |
| 701 |
.IP |
| 702 |
We do not mark these functions as MT-Unsafe,\" or AS-Unsafe, |
| 703 |
however, |
| 704 |
because functions that modify this data structure are all marked with |
| 705 |
.I const:sigintr |
| 706 |
and regarded as unsafe. |
| 707 |
Being unsafe, |
| 708 |
the latter are not to be called when multiple threads are |
| 709 |
running or asynchronous signals are enabled, |
| 710 |
and so the data structure can be considered |
| 711 |
effectively constant in these contexts, |
| 712 |
which makes the former safe. |
| 713 |
.\" .TP |
| 714 |
.\" .I fd |
| 715 |
.\" Functions annotated with |
| 716 |
.\" .I fd |
| 717 |
.\" as an AC-Safety issue may leak file |
| 718 |
.\" descriptors if asynchronous thread cancelation interrupts their |
| 719 |
.\" execution. |
| 720 |
.\" |
| 721 |
.\" Functions that allocate or deallocate file descriptors will generally be |
| 722 |
.\" marked as such. |
| 723 |
.\" Even if they attempted to protect the file descriptor |
| 724 |
.\" allocation and deallocation with cleanup regions, |
| 725 |
.\" allocating a new descriptor and storing its number where the cleanup region |
| 726 |
.\" could release it cannot be performed as a single atomic operation. |
| 727 |
.\" Similarly, |
| 728 |
.\" releasing the descriptor and taking it out of the data structure |
| 729 |
.\" normally responsible for releasing it cannot be performed atomically. |
| 730 |
.\" There will always be a window in which the descriptor cannot be released |
| 731 |
.\" because it was not stored in the cleanup handler argument yet, |
| 732 |
.\" or it was already taken out before releasing it. |
| 733 |
.\" .\" It cannot be taken out after release: |
| 734 |
.\" an open descriptor could mean either that the descriptor still |
| 735 |
.\" has to be closed, |
| 736 |
.\" or that it already did so but the descriptor was |
| 737 |
.\" reallocated by another thread or signal handler. |
| 738 |
.\" |
| 739 |
.\" Such leaks could be internally avoided, with some performance penalty, |
| 740 |
.\" by temporarily disabling asynchronous thread cancelation. |
| 741 |
.\" However, |
| 742 |
.\" since callers of allocation or deallocation functions would have to do |
| 743 |
.\" this themselves, to avoid the same sort of leak in their own layer, |
| 744 |
.\" it makes more sense for the library to assume they are taking care of it |
| 745 |
.\" than to impose a performance penalty that is redundant when the problem |
| 746 |
.\" is solved in upper layers, and insufficient when it is not. |
| 747 |
.\" |
| 748 |
.\" This remark by itself does not cause a function to be regarded as |
| 749 |
.\" AC-Unsafe. |
| 750 |
.\" However, cumulative effects of such leaks may pose a |
| 751 |
.\" problem for some programs. |
| 752 |
.\" If this is the case, |
| 753 |
.\" suspending asynchronous cancelation for the duration of calls |
| 754 |
.\" to such functions is recommended. |
| 755 |
.\" .TP |
| 756 |
.\" .I mem |
| 757 |
.\" Functions annotated with |
| 758 |
.\" .I mem |
| 759 |
.\" as an AC-Safety issue may leak |
| 760 |
.\" memory if asynchronous thread cancelation interrupts their execution. |
| 761 |
.\" |
| 762 |
.\" The problem is similar to that of file descriptors: there is no atomic |
| 763 |
.\" interface to allocate memory and store its address in the argument to a |
| 764 |
.\" cleanup handler, |
| 765 |
.\" or to release it and remove its address from that argument, |
| 766 |
.\" without at least temporarily disabling asynchronous cancelation, |
| 767 |
.\" which these functions do not do. |
| 768 |
.\" |
| 769 |
.\" This remark does not by itself cause a function to be regarded as |
| 770 |
.\" generally AC-Unsafe. |
| 771 |
.\" However, cumulative effects of such leaks may be |
| 772 |
.\" severe enough for some programs that disabling asynchronous cancelation |
| 773 |
.\" for the duration of calls to such functions may be required. |
| 774 |
.TP |
| 775 |
.I cwd |
| 776 |
Functions marked with |
| 777 |
.I cwd |
| 778 |
as an MT-Safety issue may temporarily |
| 779 |
change the current working directory during their execution, |
| 780 |
which may cause relative pathnames to be resolved in unexpected ways in |
| 781 |
other threads or within asynchronous signal or cancelation handlers. |
| 782 |
.IP |
| 783 |
This is not enough of a reason to mark so-marked functions as MT-Unsafe, |
| 784 |
.\" or AS-Unsafe, |
| 785 |
but when this behavior is optional (e.g., |
| 786 |
.BR nftw (3) |
| 787 |
with |
| 788 |
.BR FTW_CHDIR ), |
| 789 |
avoiding the option may be a good alternative to |
| 790 |
using full pathnames or file descriptor-relative (e.g., |
| 791 |
.BR openat (2)) |
| 792 |
system calls. |
| 793 |
.\" .TP |
| 794 |
.\" .I !posix |
| 795 |
.\" This remark, as an MT-Safety, AS-Safety or AC-Safety |
| 796 |
.\" note to a function, |
| 797 |
.\" indicates the safety status of the function is known to differ |
| 798 |
.\" from the specified status in the POSIX standard. |
| 799 |
.\" For example, POSIX does not require a function to be Safe, |
| 800 |
.\" but our implementation is, or vice-versa. |
| 801 |
.\" |
| 802 |
.\" For the time being, the absence of this remark does not imply the safety |
| 803 |
.\" properties we documented are identical to those mandated by POSIX for |
| 804 |
.\" the corresponding functions. |
| 805 |
.TP |
| 806 |
.I :identifier |
| 807 |
Annotations may sometimes be followed by identifiers, |
| 808 |
intended to group several functions that, for example, |
| 809 |
access the data structures in an unsafe way, as in |
| 810 |
.I race |
| 811 |
and |
| 812 |
.IR const , |
| 813 |
or to provide more specific information, |
| 814 |
such as naming a signal in a function marked with |
| 815 |
.IR sig . |
| 816 |
It is envisioned that it may be applied to |
| 817 |
.I lock |
| 818 |
and |
| 819 |
.I corrupt |
| 820 |
as well in the future. |
| 821 |
.IP |
| 822 |
In most cases, the identifier will name a set of functions, |
| 823 |
but it may name global objects or function arguments, |
| 824 |
or identifiable properties or logical components associated with them, |
| 825 |
with a notation such as, for example, |
| 826 |
.I :buf(arg) |
| 827 |
to denote a buffer associated with the argument |
| 828 |
.IR arg , |
| 829 |
or |
| 830 |
.I :tcattr(fd) |
| 831 |
to denote the terminal attributes of a file descriptor |
| 832 |
.IR fd . |
| 833 |
.IP |
| 834 |
The most common use for identifiers is to provide logical groups of |
| 835 |
functions and arguments that need to be protected by the same |
| 836 |
synchronization primitive in order to ensure safe operation in a given |
| 837 |
context. |
| 838 |
.TP |
| 839 |
.I /condition |
| 840 |
Some safety annotations may be conditional, |
| 841 |
in that they only apply if a boolean expression involving arguments, |
| 842 |
global variables or even the underlying kernel evaluates to true. |
| 843 |
.\" Such conditions as |
| 844 |
.\" .I /hurd |
| 845 |
.\" or |
| 846 |
.\" .I /!linux!bsd |
| 847 |
.\" indicate the preceding marker only |
| 848 |
.\" applies when the underlying kernel is the HURD, |
| 849 |
.\" or when it is neither Linux nor a BSD kernel, respectively. |
| 850 |
For example, |
| 851 |
.I /!ps |
| 852 |
and |
| 853 |
.I /one_per_line |
| 854 |
indicate the preceding marker only applies when argument |
| 855 |
.I ps |
| 856 |
is NULL, or global variable |
| 857 |
.I one_per_line |
| 858 |
is nonzero. |
| 859 |
.IP |
| 860 |
When all marks that render a function unsafe are |
| 861 |
adorned with such conditions, |
| 862 |
and none of the named conditions hold, |
| 863 |
then the function can be regarded as safe. |
| 864 |
.SH SEE ALSO |
| 865 |
.BR pthreads (7), |
| 866 |
.BR signal\-safety (7) |