{
    "mode": "man",
    "parameter": "attributes",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/attributes/7/json",
    "generated": "2026-07-07T04:35:30Z",
    "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  cancella‐\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",
            "subsections": []
        },
        "COLOPHON": {
            "content": "This page is part of release 5.10 of the Linux  man-pages  project.   A  description  of  the\nproject,  information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux                                        2020-12-21                                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"
        }
    ]
}