{ "content": [ { "type": "text", "text": "# attributes (info)\n\n## NAME\n\nattributes - get/set subroutine or variable attributes\n\n## SYNOPSIS\n\nsub foo : method ;\nmy ($x,@y,%z) : Bent = 1;\nmy $s = sub : method { ... };\nuse attributes (); # optional, to get subroutine declarations\nmy @attrlist = attributes::get(\\&foo);\nuse attributes 'get'; # import the attributes::get subroutine\nmy @attrlist = get \\&foo;\n\n## DESCRIPTION\n\nNote: the text of this man page is based on the material taken from the\n\"POSIX Safety Concepts\" section of the GNU C Library manual. Further\ndetails on the topics described here can be found in that manual.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **EXPORTS**\n- **EXAMPLES**\n- **MORE EXAMPLES**\n- **SEE ALSO**\n- **COLOPHON**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "attributes", "section": "", "mode": "info", "summary": "attributes - get/set subroutine or variable attributes", "synopsis": "sub foo : method ;\nmy ($x,@y,%z) : Bent = 1;\nmy $s = sub : method { ... };\nuse attributes (); # optional, to get subroutine declarations\nmy @attrlist = attributes::get(\\&foo);\nuse attributes 'get'; # import the attributes::get subroutine\nmy @attrlist = get \\&foo;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "Here are some samples of syntactically valid declarations, with", "annotation as to how they resolve internally into \"use attributes\"", "invocations by perl. These examples are primarily useful to see how", "the \"appropriate package\" is found for the possible method lookups for", "package-defined attributes.", "1. Code:", "package Canine;", "package Dog;", "my Canine $spot : Watchful ;", "Effect:", "use attributes ();", "attributes::->import(Canine => \\$spot, \"Watchful\");", "2. Code:", "package Felis;", "my $cat : Nervous;", "Effect:", "use attributes ();", "attributes::->import(Felis => \\$cat, \"Nervous\");", "3. Code:", "package X;", "sub foo : lvalue ;", "Effect:", "use attributes X => \\&foo, \"lvalue\";", "4. Code:", "package X;", "sub Y::x : lvalue { 1 }", "Effect:", "use attributes Y => \\&Y::x, \"lvalue\";", "5. Code:", "package X;", "sub foo { 1 }", "package Y;", "BEGIN { *bar = \\&X::foo; }", "package Z;", "sub Y::bar : lvalue ;", "Effect:", "use attributes X => \\&X::foo, \"lvalue\";", "This last example is purely for purposes of completeness. You should", "not be trying to mess with the attributes of something in a package", "that's not your own." ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 10, "subsections": [] }, { "name": "DESCRIPTION", "lines": 207, "subsections": [] }, { "name": "EXPORTS", "lines": 9, "subsections": [] }, { "name": "EXAMPLES", "lines": 64, "subsections": [] }, { "name": "MORE EXAMPLES", "lines": 38, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "COLOPHON", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "attributes - POSIX safety concepts\n", "subsections": [] }, "SYNOPSIS": { "content": "sub foo : method ;\nmy ($x,@y,%z) : Bent = 1;\nmy $s = sub : method { ... };\n\nuse attributes (); # optional, to get subroutine declarations\nmy @attrlist = attributes::get(\\&foo);\n\nuse attributes 'get'; # import the attributes::get subroutine\nmy @attrlist = get \\&foo;\n", "subsections": [] }, "DESCRIPTION": { "content": "Note: the text of this man page is based on the material taken from the\n\"POSIX Safety Concepts\" section of the GNU C Library manual. Further\ndetails on the topics described here can be found in that manual.\n\nVarious function manual pages include a section ATTRIBUTES that de-\nscribes the safety of calling the function in various contexts. This\nsection annotates functions with the following safety markings:\n\nMT-Safe\nMT-Safe or Thread-Safe functions are safe to call in the pres-\nence of other threads. MT, in MT-Safe, stands for Multi Thread.\n\nBeing MT-Safe does not imply a function is atomic, nor that it\nuses any of the memory synchronization mechanisms POSIX exposes\nto users. It is even possible that calling MT-Safe functions in\nsequence does not yield an MT-Safe combination. For example,\nhaving a thread call two MT-Safe functions one right after the\nother does not guarantee behavior equivalent to atomic execution\nof a combination of both functions, since concurrent calls in\nother threads may interfere in a destructive way.\n\nWhole-program optimizations that could inline functions across\nlibrary interfaces may expose unsafe reordering, and so perform-\ning inlining across the GNU C Library interface is not recom-\nmended. The documented MT-Safety status is not guaranteed under\nwhole-program optimization. However, functions defined in user-\nvisible headers are designed to be safe for inlining.\n\nMT-Unsafe\nMT-Unsafe functions are not safe to call in a multithreaded pro-\ngrams.\n\nOther keywords that appear in safety notes are defined in subsequent\nsections.\n\nConditionally safe features\nFor some features that make functions unsafe to call in certain con-\ntexts, there are known ways to avoid the safety problem other than re-\nfraining from calling the function altogether. The keywords that fol-\nlow refer to such features, and each of their definitions indicates how\nthe whole program needs to be constrained in order to remove the safety\nproblem indicated by the keyword. Only when all the reasons that make\na function unsafe are observed and addressed, by applying the docu-\nmented constraints, does the function become safe to call in a context.\n\ninit Functions marked with init as an MT-Unsafe feature perform MT-\nUnsafe initialization when they are first called.\n\nCalling such a function at least once in single-threaded mode\nremoves this specific cause for the function to be regarded as\nMT-Unsafe. If no other cause for that remains, the function can\nthen be safely called after other threads are started.\n\nrace Functions annotated with race as an MT-Safety issue operate on\nobjects in ways that may cause data races or similar forms of\ndestructive interference out of concurrent execution. In some\ncases, the objects are passed to the functions by users; in oth-\ners, they are used by the functions to return values to users;\nin others, they are not even exposed to users.\n\nconst Functions marked with const as an MT-Safety issue non-atomically\nmodify internal objects that are better regarded as constant,\nbecause a substantial portion of the GNU C Library accesses them\nwithout synchronization. Unlike race, which causes both readers\nand writers of internal objects to be regarded as MT-Unsafe,\nthis mark is applied to writers only. Writers remain MT-Unsafe\nto call, but the then-mandatory constness of objects they modify\nenables readers to be regarded as MT-Safe (as long as no other\nreasons for them to be unsafe remain), since the lack of syn-\nchronization is not a problem when the objects are effectively\nconstant.\n\nThe identifier that follows the const mark will appear by itself\nas a safety note in readers. Programs that wish to work around\nthis safety issue, so as to call writers, may use a non-recur-\nsive read-write lock associated with the identifier, and guard\nall calls to functions marked with const followed by the identi-\nfier with a write lock, and all calls to functions marked with\nthe identifier by itself with a read lock.\n\nsig Functions marked with sig as a MT-Safety issue may temporarily\ninstall a signal handler for internal purposes, which may inter-\nfere with other uses of the signal, identified after a colon.\n\nThis safety problem can be worked around by ensuring that no\nother uses of the signal will take place for the duration of the\ncall. Holding a non-recursive mutex while calling all functions\nthat 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\nterminal settings in the recommended way, namely: call tcge-\ntattr(3), modify some flags, and then call tcsetattr(3), this\ncreates a window in which changes made by other threads are\nlost. Thus, functions marked with term are MT-Unsafe.\n\nIt is thus advisable for applications using the terminal to\navoid concurrent and reentrant interactions with it, by not us-\ning it in signal handlers or blocking signals that might use it,\nand holding a lock while calling these functions and interacting\nwith the terminal. This lock should also be used for mutual ex-\nclusion with functions marked with race:tcattr(fd), where fd is\na file descriptor for the controlling terminal. The caller may\nuse a single mutex for simplicity, or use one mutex per termi-\nnal, even if referenced by different file descriptors.\n\nOther safety remarks\nAdditional keywords may be attached to functions, indicating features\nthat do not make a function unsafe to call, but that may need to be\ntaken into account in certain classes of programs:\n\nlocale Functions annotated with locale as an MT-Safety issue read from\nthe locale object without any form of synchronization. Func-\ntions annotated with locale called concurrently with locale\nchanges may behave in ways that do not correspond to any of the\nlocales active during their execution, but an unpredictable mix\nthereof.\n\nWe do not mark these functions as MT-Unsafe, however, because\nfunctions that modify the locale object are marked with\nconst:locale and regarded as unsafe. Being unsafe, the latter\nare not to be called when multiple threads are running or asyn-\nchronous signals are enabled, and so the locale can be consid-\nered effectively constant in these contexts, which makes the\nformer safe.\n\nenv Functions marked with env as an MT-Safety issue access the envi-\nronment with getenv(3) or similar, without any guards to ensure\nsafety in the presence of concurrent modifications.\n\nWe do not mark these functions as MT-Unsafe, however, because\nfunctions that modify the environment are all marked with\nconst:env and regarded as unsafe. Being unsafe, the latter are\nnot to be called when multiple threads are running or asynchro-\nnous signals are enabled, and so the environment can be consid-\nered effectively constant in these contexts, which makes the\nformer safe.\n\nhostid The function marked with hostid as an MT-Safety issue reads from\nthe system-wide data structures that hold the \"host ID\" of the\nmachine. These data structures cannot generally be modified\natomically. Since it is expected that the \"host ID\" will not\nnormally change, the function that reads from it (gethostid(3))\nis regarded as safe, whereas the function that modifies it\n(sethostid(3)) is marked with const:hostid, indicating it may\nrequire special care if it is to be called. In this specific\ncase, the special care amounts to system-wide (not merely intra-\nprocess) coordination.\n\nsigintr\nFunctions marked with sigintr as an MT-Safety issue access the\nGNU C Library sigintr internal data structure without any\nguards to ensure safety in the presence of concurrent modifica-\ntions.\n\nWe do not mark these functions as MT-Unsafe, however, because\nfunctions that modify this data structure are all marked with\nconst:sigintr and regarded as unsafe. Being unsafe, the latter\nare not to be called when multiple threads are running or asyn-\nchronous signals are enabled, and so the data structure can be\nconsidered effectively constant in these contexts, which makes\nthe former safe.\n\ncwd Functions marked with cwd as an MT-Safety issue may temporarily\nchange the current working directory during their execution,\nwhich may cause relative pathnames to be resolved in unexpected\nways 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\nMT-Unsafe, but when this behavior is optional (e.g., nftw(3)\nwith FTWCHDIR), avoiding the option may be a good alternative\nto using full pathnames or file descriptor-relative (e.g., ope-\nnat(2)) system calls.\n\n:identifier\nAnnotations may sometimes be followed by identifiers, intended\nto group several functions that, for example, access the data\nstructures in an unsafe way, as in race and const, or to provide\nmore specific information, such as naming a signal in a function\nmarked with sig. It is envisioned that it may be applied to\nlock and corrupt as well in the future.\n\nIn most cases, the identifier will name a set of functions, but\nit may name global objects or function arguments, or identifi-\nable properties or logical components associated with them, with\na notation such as, for example, :buf(arg) to denote a buffer\nassociated with the argument arg, or :tcattr(fd) to denote the\nterminal attributes of a file descriptor fd.\n\nThe most common use for identifiers is to provide logical groups\nof functions and arguments that need to be protected by the same\nsynchronization primitive in order to ensure safe operation in a\ngiven context.\n\n/condition\nSome safety annotations may be conditional, in that they only\napply if a boolean expression involving arguments, global vari-\nables or even the underlying kernel evaluates to true. For ex-\nample, /!ps and /oneperline indicate the preceding marker only\napplies when argument ps is NULL, or global variable\noneperline is nonzero.\n\nWhen all marks that render a function unsafe are adorned with\nsuch conditions, and none of the named conditions hold, then the\nfunction can be regarded as safe.\n", "subsections": [] }, "EXPORTS": { "content": "Default exports\nNone.\n\nAvailable exports\nThe routines \"get\" and \"reftype\" are exportable.\n\nExport tags defined\nThe \":ALL\" tag will get all of the above exports.\n", "subsections": [] }, "EXAMPLES": { "content": "Here are some samples of syntactically valid declarations, with\nannotation as to how they resolve internally into \"use attributes\"\ninvocations by perl. These examples are primarily useful to see how\nthe \"appropriate package\" is found for the possible method lookups for\npackage-defined attributes.\n\n1. Code:\n\npackage Canine;\npackage Dog;\nmy Canine $spot : Watchful ;\n\nEffect:\n\nuse attributes ();\nattributes::->import(Canine => \\$spot, \"Watchful\");\n\n2. Code:\n\npackage Felis;\nmy $cat : Nervous;\n\nEffect:\n\nuse attributes ();\nattributes::->import(Felis => \\$cat, \"Nervous\");\n\n3. Code:\n\npackage X;\nsub foo : lvalue ;\n\nEffect:\n\nuse attributes X => \\&foo, \"lvalue\";\n\n4. Code:\n\npackage X;\nsub Y::x : lvalue { 1 }\n\nEffect:\n\nuse attributes Y => \\&Y::x, \"lvalue\";\n\n5. Code:\n\npackage X;\nsub foo { 1 }\n\npackage Y;\nBEGIN { *bar = \\&X::foo; }\n\npackage Z;\nsub Y::bar : lvalue ;\n\nEffect:\n\nuse attributes X => \\&X::foo, \"lvalue\";\n\nThis last example is purely for purposes of completeness. You should\nnot be trying to mess with the attributes of something in a package\nthat's not your own.\n", "subsections": [] }, "MORE EXAMPLES": { "content": "1.\nsub MODIFYCODEATTRIBUTES {\nmy ($class,$code,@attrs) = @;\n\nmy $allowed = 'MyAttribute';\nmy @bad = grep { $ ne $allowed } @attrs;\n\nreturn @bad;\n}\n\nsub foo : MyAttribute {\nprint \"foo\\n\";\n}\n\nThis example runs. At compile time \"MODIFYCODEATTRIBUTES\" is\ncalled. In that subroutine, we check if any attribute is\ndisallowed and we return a list of these \"bad attributes\".\n\nAs we return an empty list, everything is fine.\n\n2.\nsub MODIFYCODEATTRIBUTES {\nmy ($class,$code,@attrs) = @;\n\nmy $allowed = 'MyAttribute';\nmy @bad = grep{ $ ne $allowed }@attrs;\n\nreturn @bad;\n}\n\nsub foo : MyAttribute Test {\nprint \"foo\\n\";\n}\n\nThis example is aborted at compile time as we use the attribute\n\"Test\" which isn't allowed. \"MODIFYCODEATTRIBUTES\" returns a\nlist that contains a single element ('Test').\n", "subsections": [] }, "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\ndescription of the project, information about reporting bugs, and the\nlatest version of this page, can be found at\nhttps://www.kernel.org/doc/man-pages/.\n\nLinux 2020-12-21 ATTRIBUTES(7)", "subsections": [] } } } }