1 .\" Copyright (c) 2014, Red Hat, Inc
2 .\" Written by Alexandre Oliva <aoliva@redhat.com>
4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
5 .\" This is free documentation; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License as
7 .\" published by the Free Software Foundation; either version 2 of
8 .\" the License, or (at your option) any later version.
10 .\" The GNU General Public License's references to "object code"
11 .\" and "executables" are to be interpreted as the output of any
12 .\" document formatting or typesetting system, including
13 .\" intermediate and printed output.
15 .\" This manual is distributed in the hope that it will be useful,
16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 .\" GNU General Public License for more details.
20 .\" You should have received a copy of the GNU General Public
21 .\" License along with this manual; if not, see
22 .\" <http://www.gnu.org/licenses/>.
24 .TH ATTRIBUTES 7 2015-03-02 "Linux" "Linux Programmer's Manual"
26 attributes \- POSIX safety concepts
31 the text of this man page is based on the material taken from
32 the "POSIX Safety Concepts" section of the GNU C Library manual.
33 Further details on the topics described here can be found in that
36 Various function manual pages include a section ATTRIBUTES
37 that describes the safety of calling the function in various contexts.
38 This section annotates functions with the following safety markings:
43 Thread-Safe functions are safe to call in the presence
45 MT, in MT-Safe, stands for Multi Thread.
47 Being MT-Safe does not imply a function is atomic, nor that it uses any
48 of the memory synchronization mechanisms POSIX exposes to users.
49 It is even possible that calling MT-Safe functions in sequence
50 does not yield an MT-Safe combination.
51 For example, having a thread call two MT-Safe
52 functions one right after the other does not guarantee behavior
53 equivalent to atomic execution of a combination of both functions,
54 since concurrent calls in other threads may interfere in a destructive way.
56 Whole-program optimizations that could inline functions across library
57 interfaces may expose unsafe reordering, and so performing inlining
58 across the GNU C Library interface is not recommended.
60 MT-Safety status is not guaranteed under whole-program optimization.
61 However, functions defined in user-visible headers are designed to be
66 .\" or Async-Signal-Safe functions are safe to call from
67 .\" asynchronous signal handlers.
68 .\" AS, in AS-Safe, stands for Asynchronous Signal.
70 .\" Many functions that are AS-Safe may set
72 .\" or modify the floating-point environment,
73 .\" because their doing so does not make them
74 .\" unsuitable for use in signal handlers.
75 .\" However, programs could misbehave should asynchronous signal handlers
76 .\" modify this thread-local state,
77 .\" and the signal handling machinery cannot be counted on to
79 .\" Therefore, signal handlers that call functions that may set
81 .\" or modify the floating-point environment
83 .\" save their original values, and restore them before returning.
87 .\" or Async-Cancel-Safe functions are safe to call when
88 .\" asynchronous cancellation is enabled.
89 .\" AC in AC-Safe stands for Asynchronous Cancellation.
91 .\" The POSIX standard defines only three functions to be AC-Safe, namely
92 .\" .BR pthread_cancel (3),
93 .\" .BR pthread_setcancelstate (3),
95 .\" .BR pthread_setcanceltype (3).
96 .\" At present the GNU C Library provides no
97 .\" guarantees beyond these three functions,
98 .\" but does document which functions are presently AC-Safe.
99 .\" This documentation is provided for use
100 .\" by the GNU C Library developers.
102 .\" Just like signal handlers, cancellation cleanup routines must configure
103 .\" the floating point environment they require.
104 .\" The routines cannot assume a floating point environment,
105 .\" particularly when asynchronous cancellation is enabled.
106 .\" If the configuration of the floating point
107 .\" environment cannot be performed atomically then it is also possible that
108 .\" the environment encountered is internally inconsistent.
110 .IR MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe
111 .IR MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe
112 functions are not safe to call in a multithreaded programs.
113 .\" functions are not
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
127 .\" the GNU C Library.
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
140 .\" .IR Preliminary ,
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 indicates
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
413 .\" types as arguments.
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))
446 .\" will be annotated,
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,
496 .\" also documented with
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 which 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
513 MT-Unsafe \" and AS-Unsafe
515 but the then-mandatory constness of objects they
516 modify enables readers to be regarded as MT-Safe \" and AS-Safe
517 (as long as no other reasons for them to be unsafe remain),
518 since the lack of synchronization is not a problem when the
519 objects are effectively constant.
521 The identifier that follows the
523 mark will appear by itself as a safety note in readers.
524 Programs that wish to work around this safety issue,
525 so as to call writers, may use a non-recursive
527 associated with the identifier, and guard
529 calls to functions marked with
531 followed by the identifier with a write lock, and
533 calls to functions marked with the identifier
534 by itself with a read lock.
535 .\" The non-recursive locking removes the MT-Safety problem,
536 .\" but it trades one AS-Safety problem for another,
537 .\" so use in asynchronous signals remains undefined.
539 .\" .\" But what if, instead of marking modifiers with const:id and readers
540 .\" .\" with just id, we marked writers with race:id and readers with ro:id?
541 .\" .\" Instead of having to define each instance of 'id', we'd have a
542 .\" .\" general pattern governing all such 'id's, wherein race:id would
543 .\" .\" suggest the need for an exclusive/write lock to make the function
544 .\" .\" safe, whereas ro:id would indicate 'id' is expected to be read-only,
545 .\" .\" but if any modifiers are called (while holding an exclusive lock),
546 .\" .\" then ro:id-marked functions ought to be guarded with a read lock for
547 .\" .\" safe operation. ro:env or ro:locale, for example, seems to convey
548 .\" .\" more clearly the expectations and the meaning, than just env or
552 Functions marked with
555 .\" (that implies an identical AS-Safety issue, omitted for brevity)
556 may temporarily install a signal handler for internal purposes,
557 which may interfere with other uses of the signal,
558 identified after a colon.
560 This safety problem can be worked around by ensuring that no other uses
561 of the signal will take place for the duration of the call.
562 Holding a non-recursive mutex while calling all functions that use the same
564 blocking that signal before the call and resetting its
565 handler afterwards is recommended.
567 .\" There is no safe way to guarantee the original signal handler is
568 .\" restored in case of asynchronous cancellation,
569 .\" therefore so-marked functions are also AC-Unsafe.
571 .\" .\" fixme: at least deferred cancellation should get it right, and would
572 .\" .\" obviate the restoring bit below, and the qualifier above.
574 .\" Besides the measures recommended to work around the
575 .\" MT-Safety and AS-Safety problem,
576 .\" in order to avert the cancellation problem,
577 .\" disabling asynchronous cancellation
579 .\" installing a cleanup handler to restore the signal to the desired state
580 .\" and to release the mutex are recommended.
583 Functions marked with
585 as an MT-Safety issue may change the
586 terminal settings in the recommended way, namely: call
588 modify some flags, and then call
590 this creates a window in which changes made by other threads are lost.
591 Thus, functions marked with
594 .\" The same window enables changes made by asynchronous signals to be lost.
595 .\" These functions are also AS-Unsafe,
596 .\" but the corresponding mark is omitted as redundant.
598 It is thus advisable for applications using the terminal to avoid
599 concurrent and reentrant interactions with it,
600 by not using it in signal handlers or blocking signals that might use it,
601 and holding a lock while calling these functions and interacting
603 This lock should also be used for mutual exclusion with
604 functions marked with
605 .IR race:tcattr(fd) ,
608 is a file descriptor for the controlling terminal.
609 The caller may use a single mutex for simplicity,
610 or use one mutex per terminal,
611 even if referenced by different file descriptors.
613 .\" Functions marked with
615 .\" as an AC-Safety issue are supposed to
616 .\" restore terminal settings to their original state,
617 .\" after temporarily changing them, but they may fail to do so if canceled.
619 .\" .\" fixme: at least deferred cancellation should get it right, and would
620 .\" .\" obviate the restoring bit below, and the qualifier above.
622 .\" Besides the measures recommended to work around the
623 .\" MT-Safety and AS-Safety problem,
624 .\" in order to avert the cancellation problem,
625 .\" disabling asynchronous cancellation
627 .\" installing a cleanup handler to
628 .\" restore the terminal settings to the original state and to release the
629 .\" mutex are recommended.
632 .SS Other safety remarks
633 Additional keywords may be attached to functions,
634 indicating features that do not make a function unsafe to call,
635 but that may need to be taken into account in certain classes of programs:
638 Functions annotated with
640 as an MT-Safety issue read from
641 the locale object without any form of synchronization.
645 called concurrently with locale changes may
646 behave in ways that do not correspond to any of the locales active
647 during their execution, but an unpredictable mix thereof.
649 We do not mark these functions as MT-Unsafe, \" or AS-Unsafe,
651 because functions that modify the locale object are marked with
653 and regarded as unsafe.
654 Being unsafe, the latter are not to be called when multiple threads
655 are running or asynchronous signals are enabled,
656 and so the locale can be considered effectively constant
658 which makes the former safe.
659 .\" Should the locking strategy suggested under @code{const} be used,
660 .\" failure to guard locale uses is not as fatal as data races in
661 .\" general: unguarded uses will @emph{not} follow dangling pointers or
662 .\" access uninitialized, unmapped or recycled memory. Each access will
663 .\" read from a consistent locale object that is or was active at some
664 .\" point during its execution. Without synchronization, however, it
665 .\" cannot even be assumed that, after a change in locale, earlier
666 .\" locales will no longer be used, even after the newly-chosen one is
667 .\" used in the thread. Nevertheless, even though unguarded reads from
668 .\" the locale will not violate type safety, functions that access the
669 .\" locale multiple times may invoke all sorts of undefined behavior
670 .\" because of the unexpected locale changes.
673 Functions marked with
675 as an MT-Safety issue access the
678 or similar, without any guards to ensure
679 safety in the presence of concurrent modifications.
681 We do not mark these functions as MT-Unsafe, \" or AS-Unsafe,
683 because functions that modify the environment are all marked with
685 and regarded as unsafe.
686 Being unsafe, the latter are not to be called when multiple threads
687 are running or asynchronous signals are enabled,
688 and so the environment can be considered
689 effectively constant in these contexts,
690 which makes the former safe.
693 The function marked with
695 as an MT-Safety issue reads from the system-wide data structures that
696 hold the "host ID" of the machine.
697 These data structures cannot generally be modified atomically.
698 Since it is expected that the "host ID" will not normally change,
699 the function that reads from it
702 whereas the function that modifies it
706 indicating it may require special care if it is to be called.
707 In this specific case,
708 the special care amounts to system-wide
709 (not merely intra-process) coordination.
712 Functions marked with
714 as an MT-Safety issue access the
717 internal data structure without any guards to ensure
718 safety in the presence of concurrent modifications.
720 We do not mark these functions as MT-Unsafe, \" or AS-Unsafe,
722 because functions that modify this data structure are all marked with
724 and regarded as unsafe.
726 the latter are not to be called when multiple threads are
727 running or asynchronous signals are enabled,
728 and so the data structure can be considered
729 effectively constant in these contexts,
730 which makes the former safe.
733 .\" Functions annotated with
735 .\" as an AC-Safety issue may leak file
736 .\" descriptors if asynchronous thread cancellation interrupts their
739 .\" Functions that allocate or deallocate file descriptors will generally be
741 .\" Even if they attempted to protect the file descriptor
742 .\" allocation and deallocation with cleanup regions,
743 .\" allocating a new descriptor and storing its number where the cleanup region
744 .\" could release it cannot be performed as a single atomic operation.
746 .\" releasing the descriptor and taking it out of the data structure
747 .\" normally responsible for releasing it cannot be performed atomically.
748 .\" There will always be a window in which the descriptor cannot be released
749 .\" because it was not stored in the cleanup handler argument yet,
750 .\" or it was already taken out before releasing it.
751 .\" .\" It cannot be taken out after release:
752 .\" an open descriptor could mean either that the descriptor still
753 .\" has to be closed,
754 .\" or that it already did so but the descriptor was
755 .\" reallocated by another thread or signal handler.
757 .\" Such leaks could be internally avoided, with some performance penalty,
758 .\" by temporarily disabling asynchronous thread cancellation.
760 .\" since callers of allocation or deallocation functions would have to do
761 .\" this themselves, to avoid the same sort of leak in their own layer,
762 .\" it makes more sense for the library to assume they are taking care of it
763 .\" than to impose a performance penalty that is redundant when the problem
764 .\" is solved in upper layers, and insufficient when it is not.
766 .\" This remark by itself does not cause a function to be regarded as
768 .\" However, cumulative effects of such leaks may pose a
769 .\" problem for some programs.
770 .\" If this is the case,
771 .\" suspending asynchronous cancellation for the duration of calls
772 .\" to such functions is recommended.
775 .\" Functions annotated with
777 .\" as an AC-Safety issue may leak
778 .\" memory if asynchronous thread cancellation interrupts their execution.
780 .\" The problem is similar to that of file descriptors: there is no atomic
781 .\" interface to allocate memory and store its address in the argument to a
783 .\" or to release it and remove its address from that argument,
784 .\" without at least temporarily disabling asynchronous cancellation,
785 .\" which these functions do not do.
787 .\" This remark does not by itself cause a function to be regarded as
788 .\" generally AC-Unsafe.
789 .\" However, cumulative effects of such leaks may be
790 .\" severe enough for some programs that disabling asynchronous cancellation
791 .\" for the duration of calls to such functions may be required.
794 Functions marked with
796 as an MT-Safety issue may temporarily
797 change the current working directory during their execution,
798 which may cause relative pathnames to be resolved in unexpected ways in
799 other threads or within asynchronous signal or cancellation handlers.
801 This is not enough of a reason to mark so-marked functions as MT-Unsafe,
803 but when this behavior is optional (e.g.,
807 avoiding the option may be a good alternative to
808 using full pathnames or file descriptor-relative (e.g.,
813 .\" This remark, as an MT-Safety, AS-Safety or AC-Safety
814 .\" note to a function,
815 .\" indicates the safety status of the function is known to differ
816 .\" from the specified status in the POSIX standard.
817 .\" For example, POSIX does not require a function to be Safe,
818 .\" but our implementation is, or vice-versa.
820 .\" For the time being, the absence of this remark does not imply the safety
821 .\" properties we documented are identical to those mandated by POSIX for
822 .\" the corresponding functions.
825 Annotations may sometimes be followed by identifiers,
826 intended to group several functions that, for example,
827 access the data structures in an unsafe way, as in
831 or to provide more specific information,
832 such as naming a signal in a function marked with
834 It is envisioned that it may be applied to
838 as well in the future.
840 In most cases, the identifier will name a set of functions,
841 but it may name global objects or function arguments,
842 or identifiable properties or logical components associated with them,
843 with a notation such as, for example,
845 to denote a buffer associated with the argument
849 to denote the terminal attributes of a file descriptor
852 The most common use for identifiers is to provide logical groups of
853 functions and arguments that need to be protected by the same
854 synchronization primitive in order to ensure safe operation in a given
858 Some safety annotations may be conditional,
859 in that they only apply if a boolean expression involving arguments,
860 global variables or even the underlying kernel evaluates to true.
861 .\" Such conditions as
865 .\" indicate the preceding marker only
866 .\" applies when the underlying kernel is the HURD,
867 .\" or when it is neither Linux nor a BSD kernel, respectively.
872 indicate the preceding marker only applies when argument
874 is NULL, or global variable
878 When all marks that render a function unsafe are
879 adorned with such conditions,
880 and none of the named conditions hold,
881 then the function can be regarded as safe.
projects / thirdparty / man-pages.git / blob