1 .\" Copyright (c) 2014, Red Hat, Inc.
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" The GNU General Public License's references to "object code"
10 .\" and "executables" are to be interpreted as the output of any
11 .\" document formatting or typesetting system, including
12 .\" intermediate and printed output.
14 .\" This manual is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public
20 .\" License along with this manual; if not, see
21 .\" <http://www.gnu.org/licenses/>.
23 .TH ATTRIBUTES 7 2014-10-16 "Linux" "Linux Programmer's Manual"
25 attributes \- POSIX safety concepts
29 .SS POSIX safety concepts
30 This manual documents various safety properties of GNU C Library
31 functions, in lines that follow their prototypes and look like:
33 @sampsafety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
35 The properties are assessed according to the criteria set forth in the
36 POSIX standard for such safety contexts as
37 Thread-Safety, Async-Signal-Safety and Async-Cancel-Safety.
38 Intuitive definitions of these properties,
39 attempting to capture the meaning of the standard definitions, follow.
44 Thread-Safe functions are safe to call in the presence
46 MT, in MT-Safe, stands for Multi Thread.
48 Being MT-Safe does not imply a function is atomic, nor that it uses any
49 of the memory synchronization mechanisms POSIX exposes to users.
50 It is even possible that calling MT-Safe functions in sequence
51 does not yield an MT-Safe combination.
52 For example, having a thread call two MT-Safe
53 functions one right after the other does not guarantee behavior
54 equivalent to atomic execution of a combination of both functions,
55 since concurrent calls in other threads may interfere in a destructive way.
57 Whole-program optimizations that could inline functions across library
58 interfaces may expose unsafe reordering, and so performing inlining
59 across the GNU C Library interface is not recommended.
61 MT-Safety status is not guaranteed under whole-program optimization.
62 However, functions defined in user-visible headers are designed to be
67 .\" or Async-Signal-Safe functions are safe to call from
68 .\" asynchronous signal handlers.
69 .\" AS, in AS-Safe, stands for Asynchronous Signal.
71 .\" Many functions that are AS-Safe may set
73 .\" or modify the floating-point environment,
74 .\" because their doing so does not make them
75 .\" unsuitable for use in signal handlers.
76 .\" However, programs could misbehave should asynchronous signal handlers
77 .\" modify this thread-local state,
78 .\" and the signal handling machinery cannot be counted on to
80 .\" Therefore, signal handlers that call functions that may set
82 .\" or modify the floating-point environment
84 .\" save their original values, and restore them before returning.
88 .\" or Async-Cancel-Safe functions are safe to call when
89 .\" asynchronous cancellation is enabled.
90 .\" AC in AC-Safe stands for Asynchronous Cancellation.
92 .\" The POSIX standard defines only three functions to be AC-Safe, namely
93 .\" .BR pthread_cancel (3),
94 .\" .BR pthread_setcancelstate (3),
96 .\" .BR pthread_setcanceltype (3).
97 .\" At present the GNU C Library provides no
98 .\" guarantees beyond these three functions,
99 .\" but does document which functions are presently AC-Safe.
100 .\" This documentation is provided for use
101 .\" by the GNU C Library developers.
103 .\" Just like signal handlers, cancellation cleanup routines must configure
104 .\" the floating point environment they require.
105 .\" The routines cannot assume a floating point environment,
106 .\" particularly when asynchronous cancellation is enabled.
107 .\" If the configuration of the floating point
108 .\" environment cannot be performed atomically then it is also possible that
109 .\" the environment encountered is internally inconsistent.
111 .IR MT-Unsafe ", " AS-Unsafe ", " AC-Unsafe
112 .IR MT-Unsafe ", " AS-Unsafe ", " AC-Unsafe
114 safe to call within the safety contexts described above.
116 within such contexts invokes undefined behavior.
118 Functions not explicitly documented as safe in a safety context should
119 be regarded as Unsafe.
123 safety properties are documented, indicating these
126 be counted on in future releases of
129 Such preliminary properties are the result of an assessment of the
130 properties of our current implementation,
131 rather than of what is mandated and permitted
132 by current and future standards.
134 Although we strive to abide by the standards, in some cases our
135 implementation is safe even when the standard does not demand safety,
136 and in other cases our implementation does not meet the standard safety
138 The latter are most likely bugs; the former, when marked
141 should not be counted on: future standards may
142 require changes that are not compatible with the additional safety
143 properties afforded by the current implementation.
146 the POSIX standard does not offer a detailed definition of safety.
147 We assume that, by "safe to call", POSIX means that,
148 as long as the program does not invoke undefined behavior,
149 the "safe to call" function behaves as specified,
150 and does not cause other functions to deviate from their specified behavior.
151 We have chosen to use its loose
152 definitions of safety, not because they are the best definitions to use,
153 but because choosing them harmonizes this manual with POSIX.
155 Please keep in mind that these are preliminary definitions and annotations,
156 and certain aspects of the definitions are still under
157 discussion and might be subject to clarification or change.
160 we envision evolving the preliminary safety notes into stable commitments,
161 as stable as those of our interfaces.
162 As we do, we will remove the
164 keyword from safety notes.
165 As long as the keyword remains, however,
166 they are not to be regarded as a promise of future behavior.
168 Other keywords that appear in safety notes are defined in subsequent sections.
171 .\" .SS Unsafe features
172 .\" Functions that are unsafe to call in certain contexts are annotated with
173 .\" keywords that document their features that make them unsafe to call.
174 .\" AS-Unsafe features in this section indicate the functions are never safe
175 .\" to call when asynchronous signals are enabled.
176 .\" AC-Unsafe features
177 .\" indicate they are never safe to call when asynchronous cancellation is
179 .\" There are no MT-Unsafe marks in this section.
182 .\" Functions marked with
184 .\" as an AS-Unsafe feature may be
185 .\" .\" interrupted by a signal while holding a non-recursive lock.
186 .\" If the signal handler calls another such function that takes the same lock,
187 .\" the result is a deadlock.
189 .\" Functions annotated with
191 .\" as an AC-Unsafe feature may, if canceled asynchronously,
192 .\" fail to release a lock that would have been released if their execution
193 .\" had not been interrupted by asynchronous thread cancellation.
194 .\" Once a lock is left taken,
195 .\" attempts to take that lock will block indefinitely.
198 .\" Functions marked with
200 .\" as an AS-Unsafe feature may corrupt
201 .\" data structures and misbehave when they interrupt,
202 .\" or are interrupted by, another such function.
203 .\" Unlike functions marked with
205 .\" these take recursive locks to avoid MT-Safety problems,
206 .\" but this is not enough to stop a signal handler from observing
207 .\" a partially-updated data structure.
208 .\" Further corruption may arise from the interrupted function's
209 .\" failure to notice updates made by signal handlers.
211 .\" Functions marked with
213 .\" as an AC-Unsafe feature may leave
214 .\" data structures in a corrupt, partially updated state.
215 .\" Subsequent uses of the data structure may misbehave.
217 .\" .\" A special case, probably not worth documenting separately, involves
218 .\" .\" reallocing, or even freeing pointers. Any case involving free could
219 .\" .\" be easily turned into an ac-safe leak by resetting the pointer before
220 .\" .\" releasing it; I don't think we have any case that calls for this sort
221 .\" .\" of fixing. Fixing the realloc cases would require a new interface:
222 .\" .\" instead of @code{ptr=realloc(ptr,size)} we'd have to introduce
223 .\" .\" @code{acsafe_realloc(&ptr,size)} that would modify ptr before
224 .\" .\" releasing the old memory. The ac-unsafe realloc could be implemented
225 .\" .\" in terms of an internal interface with this semantics (say
226 .\" .\" __acsafe_realloc), but since realloc can be overridden, the function
227 .\" .\" we call to implement realloc should not be this internal interface,
228 .\" .\" but another internal interface that calls __acsafe_realloc if realloc
229 .\" .\" was not overridden, and calls the overridden realloc with async
230 .\" .\" cancel disabled. --lxoliva
233 .\" Functions marked with
235 .\" may call heap memory management functions from the
236 .\" .BR malloc (3)/ free (3)
237 .\" family of functions and are only as safe as those functions.
238 .\" This note is thus equivalent to:
240 .\" | AS-Unsafe lock | AC-Unsafe lock fd mem |
241 .\" .\" @sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
243 .\" .\" Check for cases that should have used plugin instead of or in
244 .\" .\" addition to this. Then, after rechecking gettext, adjust i18n if
248 .\" Functions marked with
250 .\" use the dynamic loader to load
251 .\" shared libraries into the current execution image.
252 .\" This involves opening files, mapping them into memory,
253 .\" allocating additional memory, resolving symbols,
254 .\" applying relocations and more,
255 .\" all of this while holding internal dynamic loader locks.
257 .\" The locks are enough for these functions to be AS-Unsafe and AC-Unsafe,
258 .\" but other issues may arise.
259 .\" At present this is a placeholder for all
260 .\" potential safety issues raised by
263 .\" .\" dlopen runs init and fini sections of the module; does this mean
264 .\" .\" dlopen always implies plugin?
267 .\" Functions annotated with
269 .\" may run code from plugins that
270 .\" may be external to the GNU C Library.
271 .\" Such plugin functions are assumed to be
272 .\" MT-Safe, AS-Unsafe and AC-Unsafe.
273 .\" Examples of such plugins are stack unwinding libraries,
274 .\" name service switch (NSS) and character set conversion (iconv) back-ends.
276 .\" Although the plugins mentioned as examples are all brought in by means
279 .\" keyword does not imply any direct
280 .\" involvement of the dynamic loader or the
283 .\" those are covered by
285 .\" For example, if one function loads a module and finds the addresses
286 .\" of some of its functions,
287 .\" while another just calls those already-resolved functions,
288 .\" the former will be marked with
290 .\" whereas the latter will get the
292 .\" When a single function takes all of these actions, then it gets both marks.
295 .\" Functions marked with
297 .\" may call internationalization
300 .\" family and will be only as safe as those
302 .\" This note is thus equivalent to:
304 .\" | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt |
306 .\" .\" @sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}}
309 .\" Functions marked with
314 .\" similar to set a time-out for a system call or a long-running operation.
315 .\" In a multi-threaded program, there is a risk that the time-out signal
316 .\" will be delivered to a different thread,
317 .\" thus failing to interrupt the intended thread.
318 .\" Besides being MT-Unsafe, such functions are always
319 .\" AS-Unsafe, because calling them in signal handlers may interfere with
320 .\" timers set in the interrupted code, and AC-Unsafe,
321 .\" because there is no safe way to guarantee an earlier timer
322 .\" will be reset in case of asynchronous cancellation.
325 .SS Conditionally safe features
326 For some features that make functions unsafe to call in certain contexts,
327 there are known ways to avoid the safety problem other than
328 refraining from calling the function altogether.
329 The keywords that follow refer to such features,
330 and each of their definitions indicate
331 how the whole program needs to be constrained in order to remove the
332 safety problem indicated by the keyword.
333 Only when all the reasons that
334 make a function unsafe are observed and addressed,
335 by applying the documented constraints,
336 does the function become safe to call in a context.
339 Functions marked with
341 as an MT-Unsafe feature perform
342 MT-Unsafe initialization when they are first called.
344 Calling such a function at least once in single-threaded mode removes
345 this specific cause for the function to be regarded as MT-Unsafe.
346 If no other cause for that remains,
347 the function can then be safely called after other threads are started.
349 .\" Functions marked with
351 .\" as an AS-Unsafe or AC-Unsafe feature use the GNU C Library internal
353 .\" machinery or similar to initialize internal data structures.
355 .\" If a signal handler interrupts such an initializer,
356 .\" and calls any function that also performs
358 .\" initialization, it will deadlock if the thread library has been loaded.
360 .\" Furthermore, if an initializer is partially complete before it is canceled
361 .\" or interrupted by a signal whose handler requires the same initialization,
362 .\" some or all of the initialization may be performed more than once,
363 .\" leaking resources or even resulting in corrupt internal data.
365 .\" Applications that need to call functions marked with
367 .\" as an AS-Safety or AC-Unsafe feature should ensure
368 .\" the initialization is performed
369 .\" before configuring signal handlers or enabling cancellation,
370 .\" so that the AS-Safety and AC-Safety issues related with
374 .\" .\" We may have to extend the annotations to cover conditions in which
375 .\" .\" initialization may or may not occur, since an initial call in a safe
376 .\" .\" context is no use if the initialization doesn't take place at that
377 .\" .\" time: it doesn't remove the risk for later calls.
380 Functions annotated with
382 as an MT-Safety issue operate on
383 objects in ways that may cause data races or similar forms of
384 destructive interference out of concurrent execution.
386 the objects are passed to the functions by users;
387 in others, they are used by the functions to return values to users;
388 in others, they are not even exposed to users.
390 We consider access to objects passed as (indirect) arguments to
391 functions to be data race free.
392 The assurance of data race free objects
393 is the caller's responsibility.
394 We will not mark a function as MT-Unsafe or AS-Unsafe
395 if it misbehaves when users fail to take the measures required by
396 POSIX to avoid data races when dealing with such objects.
397 As a general rule, if a function is documented as reading from
398 an object passed (by reference) to it, or modifying it,
399 users ought to use memory synchronization primitives
400 to avoid data races just as they would should they perform
401 the accesses themselves rather than by calling the library function.
404 streams are the exception to the general rule,
405 in that POSIX mandates the library to guard against data races
406 in many functions that manipulate objects of this specific opaque type.
407 We regard this as a convenience provided to users,
408 rather than as a general requirement whose expectations
409 should extend to other types.
411 In order to remind users that guarding certain arguments is their
412 responsibility, we will annotate functions that take objects of certain
414 We draw the line for objects passed by users as follows:
415 objects whose types are exposed to users,
416 and that users are expected to access directly,
417 such as memory buffers, strings,
418 and various user-visible structured types, do
420 give reason for functions to be annotated with
422 It would be noisy and redundant with the general requirement,
423 and not many would be surprised by the library's lack of internal
424 guards when accessing objects that can be accessed directly by users.
426 As for objects that are opaque or opaque-like,
427 in that they are to be manipulated only by passing them
428 to library functions (e.g.,
433 there might be additional expectations as to internal coordination
434 of access by the library.
435 We will annotate, with
437 followed by a colon and the argument name,
438 functions that take such objects but that do not take
439 care of synchronizing access to them by default.
445 .RB ( unlocked_stdio (3))
447 but those that perform implicit locking on
449 streams by default will not,
450 even though the implicit locking may be disabled on a per-stream basis.
452 In either case, we will not regard as MT-Unsafe functions that may
453 access user-supplied objects in unsafe ways should users fail to ensure
454 the accesses are well defined.
455 The notion prevails that users are expected to safeguard against
456 data races any user-supplied objects that the library accesses
459 .\" The above describes @mtsrace; @mtasurace is described below.
461 This user responsibility does not apply, however,
462 to objects controlled by the library itself,
463 such as internal objects and static buffers used
464 to return values from certain calls.
465 When the library doesn't guard them against concurrent uses,
466 these cases are regarded as MT-Unsafe and AS-Unsafe (although the
468 mark under AS-Unsafe will be omitted
469 as redundant with the one under MT-Unsafe).
470 As in the case of user-exposed objects,
471 the mark may be followed by a colon and an identifier.
472 The identifier groups all functions that operate on a
473 certain unguarded object; users may avoid the MT-Safety issues related
474 with unguarded concurrent access to such internal objects by creating a
475 non-recursive mutex related with the identifier,
476 and always holding the mutex when calling any function marked
477 as racy on that identifier,
478 as they would have to should the identifier be
479 an object under user control.
480 The non-recursive mutex avoids the MT-Safety issue,
481 but it trades one AS-Safety issue for another,
482 so use in asynchronous signals remains undefined.
484 When the identifier relates to a static buffer used to hold return values,
485 the mutex must be held for as long as the buffer remains in use
487 Many functions that return pointers to static buffers offer reentrant
488 variants that store return values in caller-supplied buffers instead.
489 In some cases, such as
491 the variant is chosen not by calling an alternate entry point,
492 but by passing a non-NULL pointer to the buffer in which the
493 returned values are to be stored.
494 These variants are generally preferable in multi-threaded programs,
495 although some of them are not MT-Safe because of other internal buffers,
501 Functions marked with
503 as an MT-Safety issue non-atomically
504 modify internal objects that are better regarded as constant,
505 because a substantial portion of the GNU C Library accesses them without
509 that causes both readers and
510 writers of internal objects to be regarded as MT-Unsafe and AS-Unsafe,
511 this mark is applied to writers only.
512 Writers remain equally MT-Unsafe and AS-Unsafe to call,
513 but the then-mandatory constness of objects they
514 modify enables readers to be regarded as MT-Safe and AS-Safe (as long as
515 no other reasons for them to be unsafe remain),
516 since the lack of synchronization is not a problem when the
517 objects are effectively constant.
519 The identifier that follows the
521 mark will appear by itself as a safety note in readers.
522 Programs that wish to work around this safety issue,
523 so as to call writers, may use a non-recursive
525 associated with the identifier, and guard
527 calls to functions marked with
529 followed by the identifier with a write lock, and
531 calls to functions marked with the identifier
532 by itself with a read lock.
533 The non-recursive locking removes the MT-Safety problem,
534 but it trades one AS-Safety problem for another,
535 so use in asynchronous signals remains undefined.
537 .\" But what if, instead of marking modifiers with const:id and readers
538 .\" with just id, we marked writers with race:id and readers with ro:id?
539 .\" Instead of having to define each instance of 'id', we'd have a
540 .\" general pattern governing all such 'id's, wherein race:id would
541 .\" suggest the need for an exclusive/write lock to make the function
542 .\" safe, whereas ro:id would indicate 'id' is expected to be read-only,
543 .\" but if any modifiers are called (while holding an exclusive lock),
544 .\" then ro:id-marked functions ought to be guarded with a read lock for
545 .\" safe operation. ro:env or ro:locale, for example, seems to convey
546 .\" more clearly the expectations and the meaning, than just env or
550 Functions marked with
553 (that implies an identical AS-Safety issue, omitted for brevity)
554 may temporarily install a signal handler for internal purposes,
555 which may interfere with other uses of the signal,
556 identified after a colon.
558 This safety problem can be worked around by ensuring that no other uses
559 of the signal will take place for the duration of the call.
560 Holding a non-recursive mutex while calling all functions that use the same
562 blocking that signal before the call and resetting its
563 handler afterwards is recommended.
565 There is no safe way to guarantee the original signal handler is
566 restored in case of asynchronous cancellation,
567 therefore so-marked functions are also AC-Unsafe.
569 .\" fixme: at least deferred cancellation should get it right, and would
570 .\" obviate the restoring bit below, and the qualifier above.
572 Besides the measures recommended to work around the
573 MT-Safety and AS-Safety problem,
574 in order to avert the cancellation problem,
575 disabling asynchronous cancellation
577 installing a cleanup handler to restore the signal to the desired state
578 and to release the mutex are recommended.
581 Functions marked with
583 as an MT-Safety issue may change the
584 terminal settings in the recommended way, namely: call
586 modify some flags, and then call
588 this creates a window in which changes made by other threads are lost.
589 Thus, functions marked with
592 The same window enables changes made by asynchronous signals to be lost.
593 These functions are also AS-Unsafe,
594 but the corresponding mark is omitted as redundant.
596 It is thus advisable for applications using the terminal to avoid
597 concurrent and reentrant interactions with it,
598 by not using it in signal handlers or blocking signals that might use it,
599 and holding a lock while calling these functions and interacting
601 This lock should also be used for mutual exclusion with
602 functions marked with
603 .IR race:tcattr(fd) ,
606 is a file descriptor for the controlling terminal.
607 The caller may use a single mutex for simplicity,
608 or use one mutex per terminal,
609 even if referenced by different file descriptors.
611 Functions marked with
613 as an AC-Safety issue are supposed to
614 restore terminal settings to their original state,
615 after temporarily changing them, but they may fail to do so if canceled.
617 .\" fixme: at least deferred cancellation should get it right, and would
618 .\" obviate the restoring bit below, and the qualifier above.
620 Besides the measures recommended to work around the
621 MT-Safety and AS-Safety problem,
622 in order to avert the cancellation problem,
623 disabling asynchronous cancellation
625 installing a cleanup handler to
626 restore the terminal settings to the original state and to release the
627 mutex are recommended.
630 .SS Other safety remarks
631 Additional keywords may be attached to functions,
632 indicating features that do not make a function unsafe to call,
633 but that may need to be taken into account in certain classes of programs:
636 Functions annotated with
638 as an MT-Safety issue read from
639 the locale object without any form of synchronization.
643 called concurrently with locale changes may
644 behave in ways that do not correspond to any of the locales active
645 during their execution, but an unpredictable mix thereof.
647 We do not mark these functions as MT-Unsafe or AS-Unsafe, however,
648 because functions that modify the locale object are marked with
650 and regarded as unsafe.
651 Being unsafe, the latter are not to be called when multiple threads
652 are running or asynchronous signals are enabled,
653 and so the locale can be considered effectively constant
655 which makes the former safe.
657 .\" Should the locking strategy suggested under @code{const} be used,
658 .\" failure to guard locale uses is not as fatal as data races in
659 .\" general: unguarded uses will @emph{not} follow dangling pointers or
660 .\" access uninitialized, unmapped or recycled memory. Each access will
661 .\" read from a consistent locale object that is or was active at some
662 .\" point during its execution. Without synchronization, however, it
663 .\" cannot even be assumed that, after a change in locale, earlier
664 .\" locales will no longer be used, even after the newly-chosen one is
665 .\" used in the thread. Nevertheless, even though unguarded reads from
666 .\" the locale will not violate type safety, functions that access the
667 .\" locale multiple times may invoke all sorts of undefined behavior
668 .\" because of the unexpected locale changes.
671 Functions marked with
673 as an MT-Safety issue access the
676 or similar, without any guards to ensure
677 safety in the presence of concurrent modifications.
679 We do not mark these functions as MT-Unsafe or AS-Unsafe, however,
680 because functions that modify the environment are all marked with
682 and regarded as unsafe.
683 Being unsafe, the latter are not to be called when multiple threads
684 are running or asynchronous signals are enabled,
685 and so the environment can be considered
686 effectively constant in these contexts,
687 which makes the former safe.
690 The function marked with
692 as an MT-Safety issue reads from the system-wide data structures that
693 hold the "host ID" of the machine.
694 These data structures cannot generally be modified atomically.
695 Since it is expected that the "host ID" will not normally change,
696 the function that reads from it
699 whereas the function that modifies it
703 indicating it may require special care if it is to be called.
704 In this specific case,
705 the special care amounts to system-wide
706 (not merely intra-process) coordination.
709 Functions marked with
711 as an MT-Safety issue access the
714 internal data structure without any guards to ensure
715 safety in the presence of concurrent modifications.
717 We do not mark these functions as MT-Unsafe or AS-Unsafe, however,
718 because functions that modify the this data structure are all marked with
720 and regarded as unsafe.
722 the latter are not to be called when multiple threads are
723 running or asynchronous signals are enabled,
724 and so the data structure can be considered
725 effectively constant in these contexts,
726 which makes the former safe.
729 Functions annotated with
731 as an AC-Safety issue may leak file
732 descriptors if asynchronous thread cancellation interrupts their
735 Functions that allocate or deallocate file descriptors will generally be
737 Even if they attempted to protect the file descriptor
738 allocation and deallocation with cleanup regions,
739 allocating a new descriptor and storing its number where the cleanup region
740 could release it cannot be performed as a single atomic operation.
742 releasing the descriptor and taking it out of the data structure
743 normally responsible for releasing it cannot be performed atomically.
744 There will always be a window in which the descriptor cannot be released
745 because it was not stored in the cleanup handler argument yet,
746 or it was already taken out before releasing it.
747 It cannot be taken out after release:
748 an open descriptor could mean either that the descriptor still
750 or that it already did so but the descriptor was
751 reallocated by another thread or signal handler.
753 Such leaks could be internally avoided, with some performance penalty,
754 by temporarily disabling asynchronous thread cancellation.
756 since callers of allocation or deallocation functions would have to do
757 this themselves, to avoid the same sort of leak in their own layer,
758 it makes more sense for the library to assume they are taking care of it
759 than to impose a performance penalty that is redundant when the problem
760 is solved in upper layers, and insufficient when it is not.
762 This remark by itself does not cause a function to be regarded as
764 However, cumulative effects of such leaks may pose a
765 problem for some programs.
767 suspending asynchronous cancellation for the duration of calls
768 to such functions is recommended.
771 Functions annotated with
773 as an AC-Safety issue may leak
774 memory if asynchronous thread cancellation interrupts their execution.
776 The problem is similar to that of file descriptors: there is no atomic
777 interface to allocate memory and store its address in the argument to a
779 or to release it and remove its address from that argument,
780 without at least temporarily disabling asynchronous cancellation,
781 which these functions do not do.
783 This remark does not by itself cause a function to be regarded as
785 However, cumulative effects of such leaks may be
786 severe enough for some programs that disabling asynchronous cancellation
787 for the duration of calls to such functions may be required.
790 Functions marked with
792 as an MT-Safety issue may temporarily
793 change the current working directory during their execution,
794 which may cause relative pathnames to be resolved in unexpected ways in
795 other threads or within asynchronous signal or cancellation handlers.
797 This is not enough of a reason to mark so-marked functions as MT-Unsafe or
798 AS-Unsafe, but when this behavior is optional (e.g.,
802 avoiding the option may be a good alternative to
803 using full pathnames or file descriptor-relative (e.g.,
808 This remark, as an MT-Safety, AS-Safety or AC-Safety note to a function,
809 indicates the safety status of the function is known to differ
810 from the specified status in the POSIX standard.
811 For example, POSIX does not require a function to be Safe,
812 but our implementation is, or vice-versa.
814 For the time being, the absence of this remark does not imply the safety
815 properties we documented are identical to those mandated by POSIX for
816 the corresponding functions.
819 Annotations may sometimes be followed by identifiers,
820 intended to group several functions that, for example,
821 access the data structures in an unsafe way, as in
825 or to provide more specific information,
826 such as naming a signal in a function marked with
828 It is envisioned that it may be applied to
832 as well in the future.
834 In most cases, the identifier will name a set of functions,
835 but it may name global objects or function arguments,
836 or identifiable properties or logical components associated with them,
837 with a notation such as, for example,
839 to denote a buffer associated with the argument
843 to denote the terminal attributes of a file descriptor
846 The most common use for identifiers is to provide logical groups of
847 functions and arguments that need to be protected by the same
848 synchronization primitive in order to ensure safe operation in a given
852 Some safety annotations may be conditional,
853 in that they only apply if a boolean expression involving arguments,
854 global variables or even the underlying kernel evaluates evaluates to true.
859 indicate the preceding marker only
860 applies when the underlying kernel is the HURD,
861 or when it is neither Linux nor a BSD kernel, respectively.
865 indicate the preceding marker only applies when argument
867 is NULL, or global variable
871 When all marks that render a function unsafe are
872 adorned with such conditions,
873 and none of the named conditions hold,
874 then the function can be regarded as safe.
projects / thirdparty / man-pages.git / blob