1ATTRIBUTES(7) Linux Programmer's Manual ATTRIBUTES(7)
2
6 attributes - POSIX safety concepts
7
9 Note: the text of this man page is based on the material taken from the
10 "POSIX Safety Concepts" section of the GNU C Library manual. Further
11 details on the topics described here can be found in that manual.
12 Various function manual pages include a section ATTRIBUTES that
14 describes the safety of calling the function in various contexts. This
15 section annotates functions with the following safety markings:
16 MT-Safe
18 MT-Safe or Thread-Safe functions are safe to call in the pres‐
19 ence of other threads. MT, in MT-Safe, stands for Multi Thread.
20 Being MT-Safe does not imply a function is atomic, nor that it
22 uses any of the memory synchronization mechanisms POSIX exposes
23 to users. It is even possible that calling MT-Safe functions in
24 sequence does not yield an MT-Safe combination. For example,
25 having a thread call two MT-Safe functions one right after the
26 other does not guarantee behavior equivalent to atomic execution
27 of a combination of both functions, since concurrent calls in
28 other threads may interfere in a destructive way.
29 Whole-program optimizations that could inline functions across
31 library interfaces may expose unsafe reordering, and so perform‐
32 ing inlining across the GNU C Library interface is not recom‐
33 mended. The documented MT-Safety status is not guaranteed under
34 whole-program optimization. However, functions defined in user-
35 visible headers are designed to be safe for inlining.
36 MT-Unsafe
38 MT-Unsafe functions are not safe to call in a multithreaded pro‐
39 grams.
40 Other keywords that appear in safety notes are defined in subsequent
42 sections.
43 Conditionally safe features
45 For some features that make functions unsafe to call in certain con‐
46 texts, there are known ways to avoid the safety problem other than
47 refraining from calling the function altogether. The keywords that
48 follow refer to such features, and each of their definitions indicates
49 how the whole program needs to be constrained in order to remove the
50 safety problem indicated by the keyword. Only when all the reasons
51 that make a function unsafe are observed and addressed, by applying the
52 documented constraints, does the function become safe to call in a con‐
53 text.
54 init Functions marked with init as an MT-Unsafe feature perform MT-
56 Unsafe initialization when they are first called.
57 Calling such a function at least once in single-threaded mode
59 removes this specific cause for the function to be regarded as
60 MT-Unsafe. If no other cause for that remains, the function can
61 then be safely called after other threads are started.
62 race Functions annotated with race as an MT-Safety issue operate on
64 objects in ways that may cause data races or similar forms of
65 destructive interference out of concurrent execution. In some
66 cases, the objects are passed to the functions by users; in oth‐
67 ers, they are used by the functions to return values to users;
68 in others, they are not even exposed to users.
69 const Functions marked with const as an MT-Safety issue non-atomically
71 modify internal objects that are better regarded as constant,
72 because a substantial portion of the GNU C Library accesses them
73 without synchronization. Unlike race, which causes both readers
74 and writers of internal objects to be regarded as MT-Unsafe,
75 this mark is applied to writers only. Writers remain MT-Unsafe
76 to call, but the then-mandatory constness of objects they modify
77 enables readers to be regarded as MT-Safe (as long as no other
78 reasons for them to be unsafe remain), since the lack of syn‐
79 chronization is not a problem when the objects are effectively
80 constant.
81 The identifier that follows the const mark will appear by itself
83 as a safety note in readers. Programs that wish to work around
84 this safety issue, so as to call writers, may use a non-recur‐
85 sive read-write lock associated with the identifier, and guard
86 all calls to functions marked with const followed by the identi‐
87 fier with a write lock, and all calls to functions marked with
88 the identifier by itself with a read lock.
89 sig Functions marked with sig as a MT-Safety issue may temporarily
91 install a signal handler for internal purposes, which may inter‐
92 fere with other uses of the signal, identified after a colon.
93 This safety problem can be worked around by ensuring that no
95 other uses of the signal will take place for the duration of the
96 call. Holding a non-recursive mutex while calling all functions
97 that use the same temporary signal; blocking that signal before
98 the call and resetting its handler afterwards is recommended.
99 term Functions marked with term as an MT-Safety issue may change the
101 terminal settings in the recommended way, namely: call tcge‐
102 tattr(3), modify some flags, and then call tcsetattr(3), this
103 creates a window in which changes made by other threads are
104 lost. Thus, functions marked with term are MT-Unsafe.
105 It is thus advisable for applications using the terminal to
107 avoid concurrent and reentrant interactions with it, by not
108 using it in signal handlers or blocking signals that might use
109 it, and holding a lock while calling these functions and inter‐
110 acting with the terminal. This lock should also be used for
111 mutual exclusion with functions marked with race:tcattr(fd),
112 where fd is a file descriptor for the controlling terminal. The
113 caller may use a single mutex for simplicity, or use one mutex
114 per terminal, even if referenced by different file descriptors.
115 Other safety remarks
117 Additional keywords may be attached to functions, indicating features
118 that do not make a function unsafe to call, but that may need to be
119 taken into account in certain classes of programs:
120 locale Functions annotated with locale as an MT-Safety issue read from
122 the locale object without any form of synchronization. Func‐
123 tions annotated with locale called concurrently with locale
124 changes may behave in ways that do not correspond to any of the
125 locales active during their execution, but an unpredictable mix
126 thereof.
127 We do not mark these functions as MT-Unsafe, however, because
129 functions that modify the locale object are marked with
130 const:locale and regarded as unsafe. Being unsafe, the latter
131 are not to be called when multiple threads are running or asyn‐
132 chronous signals are enabled, and so the locale can be consid‐
133 ered effectively constant in these contexts, which makes the
134 former safe.
135 env Functions marked with env as an MT-Safety issue access the envi‐
137 ronment with getenv(3) or similar, without any guards to ensure
138 safety in the presence of concurrent modifications.
139 We do not mark these functions as MT-Unsafe, however, because
141 functions that modify the environment are all marked with
142 const:env and regarded as unsafe. Being unsafe, the latter are
143 not to be called when multiple threads are running or asynchro‐
144 nous signals are enabled, and so the environment can be consid‐
145 ered effectively constant in these contexts, which makes the
146 former safe.
147 hostid The function marked with hostid as an MT-Safety issue reads from
149 the system-wide data structures that hold the "host ID" of the
150 machine. These data structures cannot generally be modified
151 atomically. Since it is expected that the "host ID" will not
152 normally change, the function that reads from it (gethostid(3))
153 is regarded as safe, whereas the function that modifies it
154 (sethostid(3)) is marked with const:hostid, indicating it may
155 require special care if it is to be called. In this specific
156 case, the special care amounts to system-wide (not merely intra-
157 process) coordination.
158 sigintr
160 Functions marked with sigintr as an MT-Safety issue access the
161 GNU C Library _sigintr internal data structure without any
162 guards to ensure safety in the presence of concurrent modifica‐
163 tions.
164 We do not mark these functions as MT-Unsafe, however, because
166 functions that modify this data structure are all marked with
167 const:sigintr and regarded as unsafe. Being unsafe, the latter
168 are not to be called when multiple threads are running or asyn‐
169 chronous signals are enabled, and so the data structure can be
170 considered effectively constant in these contexts, which makes
171 the former safe.
172 cwd Functions marked with cwd as an MT-Safety issue may temporarily
174 change the current working directory during their execution,
175 which may cause relative pathnames to be resolved in unexpected
176 ways in other threads or within asynchronous signal or cancella‐
177 tion handlers.
178 This is not enough of a reason to mark so-marked functions as
180 MT-Unsafe, but when this behavior is optional (e.g., nftw(3)
181 with FTW_CHDIR), avoiding the option may be a good alternative
182 to using full pathnames or file descriptor-relative (e.g., ope‐
183 nat(2)) system calls.
184 :identifier
186 Annotations may sometimes be followed by identifiers, intended
187 to group several functions that, for example, access the data
188 structures in an unsafe way, as in race and const, or to provide
189 more specific information, such as naming a signal in a function
190 marked with sig. It is envisioned that it may be applied to
191 lock and corrupt as well in the future.
192 In most cases, the identifier will name a set of functions, but
194 it may name global objects or function arguments, or identifi‐
195 able properties or logical components associated with them, with
196 a notation such as, for example, :buf(arg) to denote a buffer
197 associated with the argument arg, or :tcattr(fd) to denote the
198 terminal attributes of a file descriptor fd.
199 The most common use for identifiers is to provide logical groups
201 of functions and arguments that need to be protected by the same
202 synchronization primitive in order to ensure safe operation in a
203 given context.
204 /condition
206 Some safety annotations may be conditional, in that they only
207 apply if a boolean expression involving arguments, global vari‐
208 ables or even the underlying kernel evaluates to true. For
209 example, /!ps and /one_per_line indicate the preceding marker
210 only applies when argument ps is NULL, or global variable
211 one_per_line is nonzero.
212 When all marks that render a function unsafe are adorned with
214 such conditions, and none of the named conditions hold, then the
215 function can be regarded as safe.
216
218 pthreads(7)
219
221 This page is part of release 5.02 of the Linux man-pages project. A
222 description of the project, information about reporting bugs, and the
223 latest version of this page, can be found at
224 https://www.kernel.org/doc/man-pages/.
225Linux 2015-03-02 ATTRIBUTES(7)