# attributes

## NAME



           attributes - POSIX safety concepts
    


## DESCRIPTION



           _Note_ : the text of this man page is based on the material taken
           from the "POSIX Safety Concepts" section of the GNU C Library
           manual.  Further details on the topics described here can be found
           in that manual.
    
           Various function manual pages include a section ATTRIBUTES that
           describes the safety of calling the function in various contexts.
           This section annotates functions with the following safety
           markings:
    
           _MT-Safe_
                  _MT-Safe_ or Thread-Safe functions are safe to call in the
                  presence of other threads.  MT, in MT-Safe, stands for
                  Multi Thread.
    
                  Being MT-Safe does not imply a function is atomic, nor that
                  it uses any of the memory synchronization mechanisms POSIX
                  exposes to users.  It is even possible that calling MT-Safe
                  functions in sequence does not yield an MT-Safe
                  combination.  For example, having a thread call two MT-Safe
                  functions one right after the other does not guarantee
                  behavior equivalent to atomic execution of a combination of
                  both functions, since concurrent calls in other threads may
                  interfere in a destructive way.
    
                  Whole-program optimizations that could inline functions
                  across library interfaces may expose unsafe reordering, and
                  so performing inlining across the GNU C Library interface
                  is not recommended.  The documented MT-Safety status is not
                  guaranteed under whole-program optimization.  However,
                  functions defined in user-visible headers are designed to
                  be safe for inlining.
    
           _MT-Unsafe_
                  _MT-Unsafe_ functions are not safe to call in a multithreaded
                  programs.
    
           Other keywords that appear in safety notes are defined in
           subsequent sections.
    
       **Conditionally safe features**
           For some features that make functions unsafe to call in certain
           contexts, there are known ways to avoid the safety problem other
           than refraining from calling the function altogether.  The
           keywords that follow refer to such features, and each of their
           definitions indicates how the whole program needs to be
           constrained in order to remove the safety problem indicated by the
           keyword.  Only when all the reasons that make a function unsafe
           are observed and addressed, by applying the documented
           constraints, does the function become safe to call in a context.
    
           _init_   Functions marked with _init_ as an MT-Unsafe feature perform
                  MT-Unsafe initialization when they are first called.
    
                  Calling such a function at least once in single-threaded
                  mode removes this specific cause for the function to be
                  regarded as MT-Unsafe.  If no other cause for that remains,
                  the function can then be safely called after other threads
                  are started.
    
           _race_   Functions annotated with _race_ as an MT-Safety issue operate
                  on objects in ways that may cause data races or similar
                  forms of destructive interference out of concurrent
                  execution.  In some cases, the objects are passed to the
                  functions by users; in others, they are used by the
                  functions to return values to users; in others, they are
                  not even exposed to users.
    
           _const_  Functions marked with _const_ as an MT-Safety issue non-
                  atomically modify internal objects that are better regarded
                  as constant, because a substantial portion of the GNU C
                  Library accesses them without synchronization.  Unlike
                  _race_ , which causes both readers and writers of internal
                  objects to be regarded as MT-Unsafe, this mark is applied
                  to writers only.  Writers remain MT-Unsafe to call, but the
                  then-mandatory constness of objects they modify enables
                  readers to be regarded as MT-Safe (as long as no other
                  reasons for them to be unsafe remain), since the lack of
                  synchronization is not a problem when the objects are
                  effectively constant.
    
                  The identifier that follows the _const_ mark will appear by
                  itself as a safety note in readers.  Programs that wish to
                  work around this safety issue, so as to call writers, may
                  use a non-recursive read-write lock associated with the
                  identifier, and guard _all_ calls to functions marked with
                  _const_ followed by the identifier with a write lock, and _all_
                  calls to functions marked with the identifier by itself
                  with a read lock.
    
           _sig_    Functions marked with _sig_ as a MT-Safety issue may
                  temporarily install a signal handler for internal purposes,
                  which may interfere with other uses of the signal,
                  identified after a colon.
    
                  This safety problem can be worked around by ensuring that
                  no other uses of the signal will take place for the
                  duration of the call.  Holding a non-recursive mutex while
                  calling all functions that use the same temporary signal;
                  blocking that signal before the call and resetting its
                  handler afterwards is recommended.
    
           _term_   Functions marked with _term_ as an MT-Safety issue may change
                  the terminal settings in the recommended way, namely: call
                  tcgetattr(3), modify some flags, and then call
                  tcsetattr(3), this creates a window in which changes made
                  by other threads are lost.  Thus, functions marked with
                  _term_ are MT-Unsafe.
    
                  It is thus advisable for applications using the terminal to
                  avoid concurrent and reentrant interactions with it, by not
                  using it in signal handlers or blocking signals that might
                  use it, and holding a lock while calling these functions
                  and interacting with the terminal.  This lock should also
                  be used for mutual exclusion with functions marked with
                  _race:tcattr(fd)_ , where _fd_ is a file descriptor for the
                  controlling terminal.  The caller may use a single mutex
                  for simplicity, or use one mutex per terminal, even if
                  referenced by different file descriptors.
    
       **Other safety remarks**
           Additional keywords may be attached to functions, indicating
           features that do not make a function unsafe to call, but that may
           need to be taken into account in certain classes of programs:
    
           _locale_ Functions annotated with _locale_ as an MT-Safety issue read
                  from the locale object without any form of synchronization.
                  Functions annotated with _locale_ called concurrently with
                  locale changes may behave in ways that do not correspond to
                  any of the locales active during their execution, but an
                  unpredictable mix thereof.
    
                  We do not mark these functions as MT-Unsafe, however,
                  because functions that modify the locale object are marked
                  with _const:locale_ and regarded as unsafe.  Being unsafe,
                  the latter are not to be called when multiple threads are
                  running or asynchronous signals are enabled, and so the
                  locale can be considered effectively constant in these
                  contexts, which makes the former safe.
    
           _env_    Functions marked with _env_ as an MT-Safety issue access the
                  environment with getenv(3) or similar, without any guards
                  to ensure safety in the presence of concurrent
                  modifications.
    
                  We do not mark these functions as MT-Unsafe, however,
                  because functions that modify the environment are all
                  marked with _const:env_ and regarded as unsafe.  Being
                  unsafe, the latter are not to be called when multiple
                  threads are running or asynchronous signals are enabled,
                  and so the environment can be considered effectively
                  constant in these contexts, which makes the former safe.
    
           _hostid_ Functions marked with _hostid_ as an MT-Safety issue read
                  from the system-wide data structures that hold the "host
                  ID" of the machine.  These data structures cannot generally
                  be modified atomically.  Since it is expected that the
                  "host ID" will not normally change, the function that reads
                  from it (gethostid(3)) is regarded as safe, whereas the
                  function that modifies it (sethostid(3)) is marked with
                  _const:hostid_ , indicating it may require special care if it
                  is to be called.  In this specific case, the special care
                  amounts to system-wide (not merely intra-process)
                  coordination.
    
           _sigintr_
                  Functions marked with _sigintr_ as an MT-Safety issue access
                  the GNU C Library __sigintr_ internal data structure without
                  any guards to ensure safety in the presence of concurrent
                  modifications.
    
                  We do not mark these functions as MT-Unsafe, however,
                  because functions that modify this data structure are all
                  marked with _const:sigintr_ and regarded as unsafe.  Being
                  unsafe, the latter are not to be called when multiple
                  threads are running or asynchronous signals are enabled,
                  and so the data structure can be considered effectively
                  constant in these contexts, which makes the former safe.
    
           _cwd_    Functions marked with _cwd_ as an MT-Safety issue may
                  temporarily change the current working directory during
                  their execution, which may cause relative pathnames to be
                  resolved in unexpected ways in other threads or within
                  asynchronous signal or cancelation handlers.
    
                  This is not enough of a reason to mark so-marked functions
                  as MT-Unsafe, but when this behavior is optional (e.g.,
                  nftw(3) with **FTW_CHDIR**), avoiding the option may be a good
                  alternative to using full pathnames or file descriptor-
                  relative (e.g., openat(2)) system calls.
    
           _:identifier_
                  Annotations may sometimes be followed by identifiers,
                  intended to group several functions that, for example,
                  access the data structures in an unsafe way, as in _race_ and
                  _const_ , or to provide more specific information, such as
                  naming a signal in a function marked with _sig_.  It is
                  envisioned that it may be applied to _lock_ and _corrupt_ as
                  well in the future.
    
                  In most cases, the identifier will name a set of functions,
                  but it may name global objects or function arguments, or
                  identifiable properties or logical components associated
                  with them, with a notation such as, for example, _:buf(arg)_
                  to denote a buffer associated with the argument _arg_ , or
                  _:tcattr(fd)_ to denote the terminal attributes of a file
                  descriptor _fd_.
    
                  The most common use for identifiers is to provide logical
                  groups of functions and arguments that need to be protected
                  by the same synchronization primitive in order to ensure
                  safe operation in a given context.
    
           _/condition_
                  Some safety annotations may be conditional, in that they
                  only apply if a boolean expression involving arguments,
                  global variables or even the underlying kernel evaluates to
                  true.  For example, _/!ps_ and _/one_per_line_ indicate the
                  preceding marker only applies when argument _ps_ is NULL, or
                  global variable _one_per_line_ is nonzero.
    
                  When all marks that render a function unsafe are adorned
                  with such conditions, and none of the named conditions
                  hold, then the function can be regarded as safe.
    


* * *