attributes - POSIX safety concepts


   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  or  Thread-Safe  functions  are  safe  to  call  in the
          presence of other threads.  MT, in  MT-Safe,  stands  for  Multi

          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  functions  are  not  safe  to call in a multithreaded

   Other keywords that appear in safety notes are  defined  in  subsequent

   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

   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

          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

          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 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.

          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

          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
          cancellation 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.

          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.

          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.




   This page is part of release 4.09 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

More Linux Commands

smoltGui(1) - GUI for Smolt hardware profile submission.....
smoltGui is a graphical user interface that can be used to submit Smolt hardware profiles to a Smoon server. Smolt is a cross-desktop hardware reporting tool fo

XTranslateCoordinates(3) - translate window coordinates.....
If XTranslateCoordinates returns True, it takes the src_x and src_y coordinates relative to the source windows origin and returns these coordinates to dest_x_re

glRasterPos4s(3gl) - specify the raster position for pixel o
The GL maintains a 3D position in window coordinates. This position, called the raster position, is used to position pixel and bitmap write operations. It is ma

Tk_SetWindowVisual(3) - change visual characteristics of win
When Tk creates a new window it assigns it the default visual characteristics (visual, depth, and colormap) for its screen. Tk_SetWindowVisual may be called to

Tcl_JoinPath(3) - manipulate platform-dependent file paths
These procedures have been superceded by the objectified procedures in the FileSystem man page, which are more efficient. These procedures may be used to disass

cdrecord(1) - write data to optical disk media (Man Page)...
wodim is used to record data or audio Compact Discs on an Orange Book CD-Recorder or to write DVD media on a DVD-Recorder. The device is the device file or labe

XmbTextExtents(3) - compute text extents - Linux man page...
The XmbTextExtents, XwcTextExtents and Xutf8TextExtents functions set the components of the specified overall_ink_return and overall_logical_return arguments to

plipconfig(8) - fine tune PLIP device parameters (Man Page)
Plipconfig is used to (hopefully) improve PLIP performance by changing the default timing parameters used by the PLIP protocol. Results are dependent on the par

glutKeyboardUpFunc(3) - sets the keyboard up (key release) c
glutKeyboardFunc sets the keyboard up (key release) callback for the current window. When a user types into the window, each key release matching an ASCII chara

systemd-machined.service(8) Virtual machine and container re
systemd-machined is a system service that keeps track of virtual machines and containers, and processes belonging to them. See systemd-nspawn(1) for some exampl

ntfscp(8) - copy file to an NTFS volume. - Linux man page...
ntfscp will copy file to an NTFS volume. destination can be either file or directory. In case if destination is directory specified by name then source_file is

git-whatchanged(1) - Show logs with difference each commit i
Shows commit logs and diff output each commit introduces. New users are encouraged to use git-log(1) instead. The whatchanged command is essentially the same as

We can't live, work or learn in freedom unless the software we use is free.