1ATTRIBUTES(7)              Linux Programmer's Manual             ATTRIBUTES(7)
2
3
4

NAME

6       attributes - POSIX safety concepts
7

DESCRIPTION

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
13       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
17       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
21              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
30              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
37       MT-Unsafe
38              MT-Unsafe functions are not safe to call in a multithreaded pro‐
39              grams.
40
41       Other  keywords  that  appear in safety notes are defined in subsequent
42       sections.
43
44   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
55       init   Functions marked with init as an MT-Unsafe feature  perform  MT-
56              Unsafe initialization when they are first called.
57
58              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
63       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
70       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
82              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
90       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
94              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
100       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
106              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
116   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
121       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
128              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
136       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
140              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
148       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
159       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
165              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
173       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
179              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
185       :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
193              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
200              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
205       /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
213              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

SEE ALSO

218       pthreads(7)
219

COLOPHON

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/.
225
226
227
228Linux                             2015-03-02                     ATTRIBUTES(7)
Impressum