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