attributes(7)



ATTRIBUTES(7)              Linux Programmer's Manual             ATTRIBUTES(7)

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 pres-
              ence 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 perform-
              ing  inlining  across  the GNU C Library interface is not recom-
              mended.  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 pro-
              grams.

       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  con-
       texts,  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 con-
       text.

       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 oth-
              ers, 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 syn-
              chronization 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-recur-
              sive read-write lock associated with the identifier,  and  guard
              all calls to functions marked with const followed by the identi-
              fier 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 inter-
              fere 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  tcge-
              tattr(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  inter-
              acting  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.   Func-
              tions  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 asyn-
              chronous signals are enabled, and so the locale can  be  consid-
              ered  effectively  constant  in  these contexts, which makes the
              former safe.

       env    Functions marked with env as an MT-Safety issue access the envi-
              ronment  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 asynchro-
              nous signals are enabled, and so the environment can be  consid-
              ered  effectively  constant  in  these contexts, which makes the
              former safe.

       hostid The function marked with hostid as an MT-Safety issue reads 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 modifica-
              tions.

              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 asyn-
              chronous 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 cancella-
              tion 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., ope-
              nat(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  identifi-
              able 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  vari-
              ables  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.

SEE ALSO
       pthreads(7)

COLOPHON
       This page is part of release 4.13 of the Linux  man-pages  project.   A
       description  of  the project, information about reporting bugs, and the
       latest    version    of    this    page,    can     be     found     at
       https://www.kernel.org/doc/man-pages/.

Linux                             2015-03-02                     ATTRIBUTES(7)

Man(1) output converted with man2html
list of all man pages