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