Debian Codegraph @

upstream/debian-unstable/man7/attributes.7

raw
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)