975 lines
13 KiB
HTML
975 lines
13 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of ATTRIBUTES</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>ATTRIBUTES</H1>
|
|
Section: Linux Programmer's Manual (7)<BR>Updated: 2015-03-02<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
attributes - POSIX safety concepts
|
|
<A NAME="lbAC"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
<I>Note</I>:
|
|
|
|
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.
|
|
<P>
|
|
|
|
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:
|
|
<DL COMPACT>
|
|
<DT id="1"><I>MT-Safe</I>
|
|
|
|
<DD>
|
|
<I>MT-Safe</I>
|
|
|
|
or
|
|
Thread-Safe functions are safe to call in the presence
|
|
of other threads.
|
|
MT, in MT-Safe, stands for Multi Thread.
|
|
<DT id="2"><DD>
|
|
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.
|
|
<DT id="3"><DD>
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="4"><I>MT-Unsafe</I>
|
|
|
|
<DD>
|
|
<I>MT-Unsafe</I>
|
|
|
|
functions are not safe to call in a multithreaded programs.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
Other keywords that appear in safety notes are defined in subsequent sections.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H3>Conditionally safe features</H3>
|
|
|
|
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 context.
|
|
<DL COMPACT>
|
|
<DT id="5"><I>init</I>
|
|
|
|
<DD>
|
|
Functions marked with
|
|
<I>init</I>
|
|
|
|
as an MT-Unsafe feature perform
|
|
MT-Unsafe initialization when they are first called.
|
|
<DT id="6"><DD>
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="7"><I>race</I>
|
|
|
|
<DD>
|
|
Functions annotated with
|
|
<I>race</I>
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="8"><I>const</I>
|
|
|
|
<DD>
|
|
Functions marked with
|
|
<I>const</I>
|
|
|
|
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
|
|
<I>race</I>,
|
|
|
|
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.
|
|
<DT id="9"><DD>
|
|
The identifier that follows the
|
|
<I>const</I>
|
|
|
|
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
|
|
<I>all</I>
|
|
|
|
calls to functions marked with
|
|
<I>const</I>
|
|
|
|
followed by the identifier with a write lock, and
|
|
<I>all</I>
|
|
|
|
calls to functions marked with the identifier
|
|
by itself with a read lock.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="10"><I>sig</I>
|
|
|
|
<DD>
|
|
Functions marked with
|
|
<I>sig</I>
|
|
|
|
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 colon.
|
|
<DT id="11"><DD>
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="12"><I>term</I>
|
|
|
|
<DD>
|
|
Functions marked with
|
|
<I>term</I>
|
|
|
|
as an MT-Safety issue may change the
|
|
terminal settings in the recommended way, namely: call
|
|
<B><A HREF="/cgi-bin/man/man2html?3+tcgetattr">tcgetattr</A></B>(3),
|
|
|
|
modify some flags, and then call
|
|
<B><A HREF="/cgi-bin/man/man2html?3+tcsetattr">tcsetattr</A></B>(3),
|
|
|
|
this creates a window in which changes made by other threads are lost.
|
|
Thus, functions marked with
|
|
<I>term</I>
|
|
|
|
are MT-Unsafe.
|
|
|
|
|
|
|
|
<DT id="13"><DD>
|
|
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
|
|
<I>race:tcattr(fd)</I>,
|
|
|
|
where
|
|
<I>fd</I>
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Other safety remarks</H3>
|
|
|
|
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:
|
|
<DL COMPACT>
|
|
<DT id="14"><I>locale</I>
|
|
|
|
<DD>
|
|
Functions annotated with
|
|
<I>locale</I>
|
|
|
|
as an MT-Safety issue read from
|
|
the locale object without any form of synchronization.
|
|
Functions
|
|
annotated with
|
|
<I>locale</I>
|
|
|
|
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.
|
|
<DT id="15"><DD>
|
|
We do not mark these functions as MT-Unsafe, however,
|
|
because functions that modify the locale object are marked with
|
|
<I>const:locale</I>
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="16"><I>env</I>
|
|
|
|
<DD>
|
|
Functions marked with
|
|
<I>env</I>
|
|
|
|
as an MT-Safety issue access the
|
|
environment with
|
|
<B><A HREF="/cgi-bin/man/man2html?3+getenv">getenv</A></B>(3)
|
|
|
|
or similar, without any guards to ensure
|
|
safety in the presence of concurrent modifications.
|
|
<DT id="17"><DD>
|
|
We do not mark these functions as MT-Unsafe, however,
|
|
because functions that modify the environment are all marked with
|
|
<I>const:env</I>
|
|
|
|
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.
|
|
<DT id="18"><I>hostid</I>
|
|
|
|
<DD>
|
|
The function marked with
|
|
<I>hostid</I>
|
|
|
|
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
|
|
(<B><A HREF="/cgi-bin/man/man2html?3+gethostid">gethostid</A></B>(3))
|
|
|
|
is regarded as safe,
|
|
whereas the function that modifies it
|
|
(<B><A HREF="/cgi-bin/man/man2html?3+sethostid">sethostid</A></B>(3))
|
|
|
|
is marked with
|
|
<I>const:hostid</I>,
|
|
|
|
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.
|
|
<DT id="19"><I>sigintr</I>
|
|
|
|
<DD>
|
|
Functions marked with
|
|
<I>sigintr</I>
|
|
|
|
as an MT-Safety issue access the
|
|
GNU C Library
|
|
<I>_sigintr</I>
|
|
|
|
internal data structure without any guards to ensure
|
|
safety in the presence of concurrent modifications.
|
|
<DT id="20"><DD>
|
|
We do not mark these functions as MT-Unsafe, however,
|
|
because functions that modify this data structure are all marked with
|
|
<I>const:sigintr</I>
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="21"><I>cwd</I>
|
|
|
|
<DD>
|
|
Functions marked with
|
|
<I>cwd</I>
|
|
|
|
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.
|
|
<DT id="22"><DD>
|
|
This is not enough of a reason to mark so-marked functions as MT-Unsafe,
|
|
|
|
but when this behavior is optional (e.g.,
|
|
<B><A HREF="/cgi-bin/man/man2html?3+nftw">nftw</A></B>(3)
|
|
|
|
with
|
|
<B>FTW_CHDIR</B>),
|
|
|
|
avoiding the option may be a good alternative to
|
|
using full pathnames or file descriptor-relative (e.g.,
|
|
<B><A HREF="/cgi-bin/man/man2html?2+openat">openat</A></B>(2))
|
|
|
|
system calls.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="23"><I>:identifier</I>
|
|
|
|
<DD>
|
|
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
|
|
<I>race</I>
|
|
|
|
and
|
|
<I>const</I>,
|
|
|
|
or to provide more specific information,
|
|
such as naming a signal in a function marked with
|
|
<I>sig</I>.
|
|
|
|
It is envisioned that it may be applied to
|
|
<I>lock</I>
|
|
|
|
and
|
|
<I>corrupt</I>
|
|
|
|
as well in the future.
|
|
<DT id="24"><DD>
|
|
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,
|
|
<I>:buf(arg)</I>
|
|
|
|
to denote a buffer associated with the argument
|
|
<I>arg</I>,
|
|
|
|
or
|
|
<I>:tcattr(fd)</I>
|
|
|
|
to denote the terminal attributes of a file descriptor
|
|
<I>fd</I>.
|
|
|
|
<DT id="25"><DD>
|
|
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.
|
|
<DT id="26"><I>/condition</I>
|
|
|
|
<DD>
|
|
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,
|
|
<I>/!ps</I>
|
|
|
|
and
|
|
<I>/one_per_line</I>
|
|
|
|
indicate the preceding marker only applies when argument
|
|
<I>ps</I>
|
|
|
|
is NULL, or global variable
|
|
<I>one_per_line</I>
|
|
|
|
is nonzero.
|
|
<DT id="27"><DD>
|
|
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.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+pthreads">pthreads</A></B>(7)
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="28"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="29"><A HREF="#lbAC">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="30"><A HREF="#lbAD">Conditionally safe features</A><DD>
|
|
<DT id="31"><A HREF="#lbAE">Other safety remarks</A><DD>
|
|
</DL>
|
|
<DT id="32"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
<DT id="33"><A HREF="#lbAG">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:07 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|