{
    "mode": "man",
    "parameter": "attributes",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/attributes/7/json",
    "generated": "2026-10-09T23:33:19Z",
    "sections": {
        "NAME": {
            "content": "attributes - POSIX safety concepts\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Note:  the  text  of this man page is based on the material taken from the \"POSIX Safety Con‐\ncepts\" section of the GNU C Library manual.  Further details on the topics described here can\nbe found in that manual.\n\nVarious function manual pages include a section ATTRIBUTES that describes the safety of call‐\ning the function in various contexts.  This section annotates functions  with  the  following\nsafety markings:\n\nMT-Safe\nMT-Safe  or  Thread-Safe  functions are safe to call in the presence of other threads.\nMT, in MT-Safe, stands for Multi Thread.\n\nBeing MT-Safe does not imply a function is atomic, nor that it uses any of the  memory\nsynchronization  mechanisms  POSIX exposes to users.  It is even possible that calling\nMT-Safe functions in sequence does not yield an  MT-Safe  combination.   For  example,\nhaving  a thread call two MT-Safe functions one right after the other does not guaran‐\ntee behavior equivalent to atomic execution of a combination of both functions,  since\nconcurrent calls in other threads may interfere in a destructive way.\n\nWhole-program  optimizations that could inline functions across library interfaces may\nexpose unsafe reordering, and so performing inlining across the GNU C  Library  inter‐\nface  is  not  recommended.   The  documented MT-Safety status is not guaranteed under\nwhole-program optimization.  However, functions defined in  user-visible  headers  are\ndesigned to be safe for inlining.\n\nMT-Unsafe\nMT-Unsafe functions are not safe to call in a multithreaded programs.\n\nOther keywords that appear in safety notes are defined in subsequent sections.\n",
            "subsections": [
                {
                    "name": "Conditionally safe features",
                    "content": "For  some  features  that  make functions unsafe to call in certain contexts, there are known\nways to avoid the safety problem other than refraining from calling the function  altogether.\nThe  keywords that follow refer to such features, and each of their definitions indicates how\nthe whole program needs to be constrained in order to remove the safety problem indicated  by\nthe  keyword.   Only  when  all  the reasons that make a function unsafe are observed and ad‐\ndressed, by applying the documented constraints, does the function become safe to call  in  a\ncontext.\n\ninit   Functions  marked  with  init as an MT-Unsafe feature perform MT-Unsafe initialization\nwhen they are first called.\n\nCalling such a function at least once in single-threaded mode  removes  this  specific\ncause  for  the  function to be regarded as MT-Unsafe.  If no other cause for that re‐\nmains, the function can then be safely called after other threads are started.\n\nrace   Functions annotated with race as an MT-Safety issue operate on objects  in  ways  that\nmay  cause  data  races or similar forms of destructive interference out of concurrent\nexecution.  In some cases, the objects are passed to the functions by users;  in  oth‐\ners, they are used by the functions to return values to users; in others, they are not\neven exposed to users.\n\nconst  Functions  marked  with const as an MT-Safety issue non-atomically modify internal ob‐\njects that are better regarded as constant, because a substantial portion of the GNU C\nLibrary accesses them without synchronization.  Unlike race, which causes both readers\nand writers of internal objects to be regarded as MT-Unsafe, this mark is  applied  to\nwriters  only.   Writers remain MT-Unsafe to call, but the then-mandatory constness of\nobjects they modify enables readers to be regarded as MT-Safe (as  long  as  no  other\nreasons  for  them  to  be  unsafe remain), since the lack of synchronization is not a\nproblem when the objects are effectively constant.\n\nThe identifier that follows the const mark will appear by itself as a safety  note  in\nreaders.   Programs that wish to work around this safety issue, so as to call writers,\nmay use a non-recursive read-write lock associated with the identifier, and guard  all\ncalls to functions marked with const followed by the identifier with a write lock, and\nall calls to functions marked with the identifier by itself with a read lock.\n\nsig    Functions  marked  with sig as a MT-Safety issue may temporarily install a signal han‐\ndler for internal purposes, which may interfere with other uses of the signal, identi‐\nfied after a colon.\n\nThis safety problem can be worked around by ensuring that no other uses of the  signal\nwill  take  place  for  the duration of the call.  Holding a non-recursive mutex while\ncalling all functions that use the same temporary signal; blocking that signal  before\nthe call and resetting its handler afterwards is recommended.\n\nterm   Functions  marked  with term as an MT-Safety issue may change the terminal settings in\nthe recommended way, namely: call tcgetattr(3), modify some flags, and then call tcse‐\ntattr(3), this creates a window in which changes  made  by  other  threads  are  lost.\nThus, functions marked with term are MT-Unsafe.\n\nIt is thus advisable for applications using the terminal to avoid concurrent and reen‐\ntrant  interactions  with  it,  by not using it in signal handlers or blocking signals\nthat might use it, and holding a lock while calling these  functions  and  interacting\nwith  the terminal.  This lock should also be used for mutual exclusion with functions\nmarked with race:tcattr(fd), where fd is a file descriptor for the controlling  termi‐\nnal.  The caller may use a single mutex for simplicity, or use one mutex per terminal,\neven if referenced by different file descriptors.\n"
                },
                {
                    "name": "Other safety remarks",
                    "content": "Additional  keywords  may  be  attached  to functions, indicating features that do not make a\nfunction unsafe to call, but that may need to be taken into account  in  certain  classes  of\nprograms:\n\nlocale Functions  annotated  with  locale  as  an MT-Safety issue read from the locale object\nwithout any form of synchronization.  Functions annotated with locale  called  concur‐\nrently with locale changes may behave in ways that do not correspond to any of the lo‐\ncales active during their execution, but an unpredictable mix thereof.\n\nWe  do  not  mark these functions as MT-Unsafe, however, because functions that modify\nthe locale object are marked with const:locale and regarded as unsafe.  Being  unsafe,\nthe latter are not to be called when multiple threads are running or asynchronous sig‐\nnals  are  enabled,  and so the locale can be considered effectively constant in these\ncontexts, which makes the former safe.\n\nenv    Functions marked with env as an MT-Safety issue access the environment with  getenv(3)\nor  similar, without any guards to ensure safety in the presence of concurrent modifi‐\ncations.\n\nWe do not mark these functions as MT-Unsafe, however, because  functions  that  modify\nthe  environment  are all marked with const:env and regarded as unsafe.  Being unsafe,\nthe latter are not to be called when multiple threads are running or asynchronous sig‐\nnals are enabled, and so the environment can be  considered  effectively  constant  in\nthese contexts, which makes the former safe.\n\nhostid The  function marked with hostid as an MT-Safety issue reads from the system-wide data\nstructures that hold the \"host ID\" of the machine.  These data structures cannot  gen‐\nerally  be modified atomically.  Since it is expected that the \"host ID\" will not nor‐\nmally change, the function that reads from it  (gethostid(3))  is  regarded  as  safe,\nwhereas  the function that modifies it (sethostid(3)) is marked with const:hostid, in‐\ndicating it may require special care if it is to be called.  In  this  specific  case,\nthe special care amounts to system-wide (not merely intra-process) coordination.\n\nsigintr\nFunctions  marked with sigintr as an MT-Safety issue access the GNU C Library sigintr\ninternal data structure without any guards to ensure safety in the presence of concur‐\nrent modifications.\n\nWe do not mark these functions as MT-Unsafe, however, because  functions  that  modify\nthis  data  structure are all marked with const:sigintr and regarded as unsafe.  Being\nunsafe, the latter are not to be called when multiple threads are running or asynchro‐\nnous signals are enabled, and so the data structure can be considered effectively con‐\nstant in these contexts, which makes the former safe.\n\ncwd    Functions marked with cwd as an MT-Safety issue may  temporarily  change  the  current\nworking directory during their execution, which may cause relative pathnames to be re‐\nsolved  in  unexpected ways in other threads or within asynchronous signal or cancela‐\ntion handlers.\n\nThis is not enough of a reason to mark so-marked functions as MT-Unsafe, but when this\nbehavior is optional (e.g., nftw(3) with FTWCHDIR), avoiding the option may be a good\nalternative to using full pathnames or file descriptor-relative (e.g., openat(2)) sys‐\ntem calls.\n\n:identifier\nAnnotations may sometimes be followed by identifiers, intended to group several  func‐\ntions  that,  for example, access the data structures in an unsafe way, as in race and\nconst, or to provide more specific information, such as naming a signal in a  function\nmarked  with sig.  It is envisioned that it may be applied to lock and corrupt as well\nin the future.\n\nIn most cases, the identifier will name a set of functions, but it may name global ob‐\njects or function arguments, or identifiable properties or logical components  associ‐\nated with them, with a notation such as, for example, :buf(arg) to denote a buffer as‐\nsociated  with the argument arg, or :tcattr(fd) to denote the terminal attributes of a\nfile descriptor fd.\n\nThe most common use for identifiers is to provide logical groups of functions and  ar‐\nguments  that  need  to be protected by the same synchronization primitive in order to\nensure safe operation in a given context.\n\n/condition\nSome safety annotations may be conditional, in that they only apply if a  boolean  ex‐\npression involving arguments, global variables or even the underlying kernel evaluates\nto  true.   For example, /!ps and /oneperline indicate the preceding marker only ap‐\nplies when argument ps is NULL, or global variable oneperline is nonzero.\n\nWhen all marks that render a function unsafe are adorned  with  such  conditions,  and\nnone of the named conditions hold, then the function can be regarded as safe.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "pthreads(7), signal-safety(7)\n\nLinux man-pages 6.7                          2023-11-01                                attributes(7)",
            "subsections": []
        }
    },
    "summary": "attributes - POSIX safety concepts",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "pthreads",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/pthreads/7/json"
        },
        {
            "name": "signal-safety",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/signal-safety/7/json"
        }
    ]
}