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