This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Thread-, Signal- and Cancellation-safety documentation
- From: Alexandre Oliva <aoliva at redhat dot com>
- To: libc-alpha at sourceware dot org
- Date: Tue, 26 Mar 2013 01:49:20 -0300
- Subject: Thread-, Signal- and Cancellation-safety documentation
I've (not so) recently started working on documenting these safety
properties of glibc functions. I believe now have enough of a patchset
to get the discussion on form and content started.
I introduced a few macros to document these properties. I envision that
they might expand differently in info and pdf docs, but currently
they're the same. Some of the *unsafe macros expand to nothing, because
unsafe is the default, but I wanted to document that the property was
actually assessed and what makes the function unsafe (in comments in the
manual sources, but not in the manual formatted output).
One of the stumbling blocks I ran into was that setlocale (unlike
uselocale) may change the global locale object and, even though the
modification of this object is guarded by a rwlock, most uses are not.
As a result, many functions were marked as unsafe, with âglocaleâ as the
reason. More recently, talking to Carlos about the consequences of this
and debating how best to approach the need for some functions to be
MT-Safe in spite of setlocale, we decided to document setlocale itself
as unsafe, so that calling it after starting threads was documented as
problematic. Then, we could document the fast-path functions as MT-Safe
even though they don't bother with locking.
A similar âsolutionâ was used for fsetlocking: since it may disable
internal locking, it would render several functions MT-Unsafe (and also
cause them to release locks they didn't take, or take locks and never
release them). By declaring fsetlocking itself MT-Unsafe, we avoid
these problems (since then calling it after starting threads invokes
undefined behavior), without making every function that optionally takes
care of internal locking MT-Unsafe. It would be possible, however, to
make fsetlocking MT-Safer :-) by changing it hold the stream's recursive
lock regardless of internal-locking status (to make sure all threads
that are using the stream complete the operation underway, be it guarded
by internal locking, be it explicit external locking--use without either
is undefined). This wouldn't make it AS-Safe, which would require all
functions that optionally take the lock to load the status only once
into an automatic variable, and use it to decide whether to take and
release the lock, or neither, rather than re-reading the setting that
may have been modified in a signal handler. This is fixable but
cumbersome and possibly not worth it, so I didn't implement this
change.
Another issue was how to enable threads and signal handlers to safely
call fclose, given that it releases the memory area that contains the
lock object that other threads might need for synchronization.
Comparing it with e.g. freopen, that closes a stream and then opens it
again without releasing the storage, and therefore concurrent and
subsequent uses of the stream are acceptable, whereas for fclose any use
of the stream after the call, even on other threads, invoke undefined
behavior. Since fclose takes the lock, it will likely be nice and yield
to other threads that hold the stream's lock, or asked for it before,
but even concurrent uses that happen to be unordered (in the virtual
clock happens-before sense) except for the locking can be ruled as
invoking undefined behavior, and therefore fclose could be documented as
MT-Safe and AS-Safe (except for other details), with the understanding
that only fclosing streams that are certainly not going to be used ever
again (e.g., streams opened within the signal handler itself, or no
longer usable by other threads) avoids undefined behavior and is
therefore well-defined and safe. In the end, fclose turned out to be
AS-Unsafe for other reasons (a non-recursive gconv mutex that could
self-deadlock), but the rationale, if agreed by the community as sound,
may be reused in other settings.
As for AC safety, a number of functions take locks in ways that suffice
to get the locks released upon synchronous cancellation. Unfortunately,
that's not enough to ensure AC-safety of the locking: it is possible for
the cancellation to take place before the lock is taken, and then the
cleanup would attempt to released the lock anyway. I referred to this
problem in the safety notes as lockleak. Other leaks, such as memory
and file descriptor leaks, were not regarded as safety issues, but they
were noted as well.
Many functions could also leave streams in inconsistent or
partially-updated states upon cancellation, which made me document them
as AC-unsafe, and likewise they might encounter streams in such states
if called from signal handlers that happened to interrupt functions that
manipulated the same stream, which got marked as AS-unsafe. These were
justified with âbadstreamâ.
Another issue that came up was using/changing the floating point
control/status word. It seems that all ports that support floating
point exceptions, rounding modes, etc, use hardware floating point, with
thread-specific FP registers holding the control&status info, and having
these registers preserved by the signal machinery just like all other
registers. Unfortunately, this is not the case of powerpc fpu
emulation: it uses a global variable (which makes a number of functions
mt-unsafe) that's not restored when signal handlers return control to
the interrupted function (which makes them as-unsafe), but I documented
them as safe anyway, because I regard the current behavior as a bug that
ought to be fixed.
Yet another issue of concern is the ability to extend printf with
register_printf_function. Besides any thread-safety issues that might
be exposed by the registered functions themselves, the use of the arrays
in which the extensions are stored is not thread safe. We have thus
documented register_printf_function as unsafe, even though it is
properly guarded itself: it is not safe to call when other threads might
be running printf.
So far, I've documented all functions in arith.texi and stdio.texi
(although some that I'd marked as âglocaleâ unsafe need revisiting to
tell whether they're otherwise thread-safe), and a couple of
dependencies elsewhere.
I've uploaded my patchset to branch lxoliva/thread-safety-docs, and I
intend to update the branch weekly or so, posting updated stgit patches
here.
Here's the initial patchset, with all the changes to the manual so far,
plus comments that document the need for thread-specific and signal-safe
emulated FP status/control words for ppc-nofpu.
I'd appreciate feedback on the decisions described above, on the
formatting of the notes in the manual, and on the patches themselves. I
hope to keep the ChangeLog entries short, going over one texi file at a
time or so, rather than listing all the functions that get documentation
notes in a patch. Let the discussion begin! :-)
Thanks,
Thread safety documentation.
From: Alexandre Oliva <aoliva@redhat.com>
for ChangeLog
* manual/macros.texi: Introduce macros to document thread
safety properties.
* manual/intro.texi: Introduce the properties themselves.
---
manual/intro.texi | 33 +++++++++++++++++++++++++++++++++
manual/macros.texi | 33 +++++++++++++++++++++++++++++++++
2 files changed, 66 insertions(+)
diff --git a/manual/intro.texi b/manual/intro.texi
index deaf089..02d2b33 100644
--- a/manual/intro.texi
+++ b/manual/intro.texi
@@ -159,6 +159,39 @@ Utilities standard} (POSIX.2) are also implemented in @theglibc{}.
These include utilities for dealing with regular expressions and other
pattern matching facilities (@pxref{Pattern Matching}).
+The safety properties of @glibcadj{} functions, documented as MT-, AS-
+and AC- -Safe and -Unsafe are assessed according to the criteria set
+forth in the POSIX standard for Multi-Thread, Async-Signal and
+Async-Cancel safety.
+
+An intuitive definition of these properties, that attempts to capture
+the formal definition in the standard, follows:
+
+@itemize @bullet
+
+@item
+MT-Safe functions are safe to call in the presence of other threads. MT
+stands for Multi Thread.
+
+@item
+AS-Safe functions are safe to call from asynchronous signal handlers.
+AS stands for Asynchronous Signal.
+
+@item
+AC-Safe functions are safe to call when asynchronous cancellation is
+enabled. AC stands for Asynchronous Cancellation.
+
+@item
+MT-Unsafe, AS-Unsafe, AC-Unsafe functions are not safe to call within
+the contexts described above: they may cause deviations from the
+specification in the behavior of the calls themselves, or of any other
+concurrent, ongoing or subsequent calls.
+
+Functions not explicitly documented as Safe should be regarded as
+Unsafe.
+
+@end itemize
+
@comment Roland sez:
@comment The GNU C library as it stands conforms to 1003.2 draft 11, which
@comment specifies:
diff --git a/manual/macros.texi b/manual/macros.texi
index daaf1c0..f5919bf 100644
--- a/manual/macros.texi
+++ b/manual/macros.texi
@@ -47,4 +47,37 @@ GNU/Hurd systems
GNU/Linux systems
@end macro
+@c Document a function as thread safe.
+@macro mtsafe {comments}
+| MT-Safe |
+@end macro
+@c Document a function as thread unsafe.
+@macro mtunsafe {comments}
+| MT-Unsafe |
+@end macro
+@c Document a function as safe for use in asynchronous signal handlers.
+@macro assafe {comments}
+| AS-Safe |
+@end macro
+@c Document a function as unsafe for use in asynchronous signal
+@c handlers. This distinguishes unmarked functions, for which this
+@c property has not been assessed, from those that have been analyzed.
+@macro asunsafe {comments}
+@end macro
+@c Document a function as safe for use when asynchronous cancellation is
+@c enabled.
+@macro acsafe {comments}
+| AC-Safe |
+@end macro
+@c Document a function as unsafe for use when asynchronous cancellation
+@c is enabled. This distinguishes unmarked functions, for which this
+@c property has not been assessed, from those that have been analyzed.
+@macro acunsafe {comments}
+@end macro
+@c Format the thread and async safety properties of a function.
+@macro safety {notes}
+\notes\
+
+@end macro
+
@end ifclear
Note that powerpc fpu emulation status is not thread- or signal-safe.
From: Alexandre Oliva <aoliva@redhat.com>
for ports/ChangeLog.powerpc
* sysdeps/powerpc/nofpu/sim-full.c: Add FIXME note about
the need for thread-specific variables preserved across signal
handlers.
* sysdeps/powerpc/soft-fp/sfp-machine.c: Likewise.
---
ports/sysdeps/powerpc/nofpu/sim-full.c | 3 +++
ports/sysdeps/powerpc/nofpu/soft-supp.h | 1 +
ports/sysdeps/powerpc/soft-fp/sfp-machine.h | 2 ++
3 files changed, 6 insertions(+)
diff --git a/ports/sysdeps/powerpc/nofpu/sim-full.c b/ports/sysdeps/powerpc/nofpu/sim-full.c
index fc061d0..c6f9fb9 100644
--- a/ports/sysdeps/powerpc/nofpu/sim-full.c
+++ b/ports/sysdeps/powerpc/nofpu/sim-full.c
@@ -21,6 +21,9 @@
#include "soft-fp.h"
#include "soft-supp.h"
+/* FIXME: these variables should be thread specific and preserved
+ across signal handlers, like hardware FP status words. */
+
/* Global to store sticky exceptions. */
int __sim_exceptions __attribute__ ((nocommon));
libc_hidden_data_def (__sim_exceptions);
diff --git a/ports/sysdeps/powerpc/nofpu/soft-supp.h b/ports/sysdeps/powerpc/nofpu/soft-supp.h
index b9638bb..cd4426c 100644
--- a/ports/sysdeps/powerpc/nofpu/soft-supp.h
+++ b/ports/sysdeps/powerpc/nofpu/soft-supp.h
@@ -26,6 +26,7 @@ typedef union
} fenv_union_t;
+/* FIXME: these variables should be thread-specific. */
extern int __sim_exceptions;
libc_hidden_proto (__sim_exceptions);
extern int __sim_disabled_exceptions;
diff --git a/ports/sysdeps/powerpc/soft-fp/sfp-machine.h b/ports/sysdeps/powerpc/soft-fp/sfp-machine.h
index 8a9afad..d55e5f7 100644
--- a/ports/sysdeps/powerpc/soft-fp/sfp-machine.h
+++ b/ports/sysdeps/powerpc/soft-fp/sfp-machine.h
@@ -53,6 +53,8 @@
#define FP_ROUNDMODE __sim_round_mode
#define FP_TRAPPING_EXCEPTIONS (~__sim_disabled_exceptions & 0x3e000000)
+/* FIXME: these variables should be thread specific and preserved
+ across signal handlers, like hardware FP status words. */
extern int __sim_exceptions;
libc_hidden_proto (__sim_exceptions);
extern int __sim_disabled_exceptions;
Thread safety documentation.
From: Alexandre Oliva <aoliva@redhat.com>
for ChangeLog
* manual/arith.texi: Document thread safety properties.
---
manual/arith.texi | 127 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 127 insertions(+)
diff --git a/manual/arith.texi b/manual/arith.texi
index d060ff9..8b31b79 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -160,6 +160,8 @@ The remainder from the division.
@comment stdlib.h
@comment ISO
@deftypefun div_t div (int @var{numerator}, int @var{denominator})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
+@c Functions in this section are pure, and thus safe.
This function @code{div} computes the quotient and remainder from
the division of @var{numerator} by @var{denominator}, returning the
result in a structure of type @code{div_t}.
@@ -199,6 +201,7 @@ type @code{long int} rather than @code{int}.)
@comment stdlib.h
@comment ISO
@deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{ldiv} function is similar to @code{div}, except that the
arguments are of type @code{long int} and the result is returned as a
structure of type @code{ldiv_t}.
@@ -225,6 +228,7 @@ type @code{long long int} rather than @code{int}.)
@comment stdlib.h
@comment ISO
@deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{lldiv} function is like the @code{div} function, but the
arguments are of type @code{long long int} and the result is returned as
a structure of type @code{lldiv_t}.
@@ -256,6 +260,7 @@ See @ref{Integers} for a description of the @code{intmax_t} type.
@comment inttypes.h
@comment ISO
@deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{imaxdiv} function is like the @code{div} function, but the
arguments are of type @code{intmax_t} and the result is returned as
a structure of type @code{imaxdiv_t}.
@@ -402,6 +407,7 @@ not have to worry about the type of their argument.
@comment math.h
@comment BSD
@deftypefunx int isinfl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This function returns @code{-1} if @var{x} represents negative infinity,
@code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
@end deftypefun
@@ -415,6 +421,7 @@ This function returns @code{-1} if @var{x} represents negative infinity,
@comment math.h
@comment BSD
@deftypefunx int isnanl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This function returns a nonzero value if @var{x} is a ``not a number''
value, and zero otherwise.
@@ -437,6 +444,7 @@ function for some reason, you can write
@comment math.h
@comment BSD
@deftypefunx int finitel (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This function returns a nonzero value if @var{x} is finite or a ``not a
number'' value, and zero otherwise.
@end deftypefun
@@ -705,6 +713,22 @@ and save and restore the set of exceptions flagged.
@comment fenv.h
@comment ISO
@deftypefun int feclearexcept (int @var{excepts})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{unlike-posix}@acsafe{unlike-posix}}
+@c The other functions in this section that modify FP status register
+@c mostly do so with non-atomic load-modify-store sequences, but since
+@c the register is thread-specific, this should be fine, and safe for
+@c cancellation. As long as the FP environment is restored before the
+@c signal handler returns control to the interrupted thread (like any
+@c kernel should do), the functions are also safe for use in signal
+@c handlers.
+@c
+@c FIXME: unsafe ppc-nofpu-sim: Floating point emulation on powerpc is
+@c the exception: __sim_exception, __sim_disabled_exception and
+@c __sim_round_mode variables, that emulate a floating-point status
+@c register, are not thread-specific variables, so many of these
+@c functions are not MT-safe on that platform. This is probably a bug.
+@c These variables aren't restored by the signal machinery either,
+@c making the functions also async-signal-unsafe on this platform.
This function clears all of the supported exception flags indicated by
@var{excepts}.
@@ -715,6 +739,7 @@ non-zero value otherwise.
@comment fenv.h
@comment ISO
@deftypefun int feraiseexcept (int @var{excepts})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
This function raises the supported exceptions indicated by
@var{excepts}. If more than one exception bit in @var{excepts} is set
the order in which the exceptions are raised is undefined except that
@@ -730,6 +755,7 @@ non-zero value otherwise.
@comment fenv.h
@comment ISO
@deftypefun int fetestexcept (int @var{excepts})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
Test whether the exception flags indicated by the parameter @var{except}
are currently set. If any of them are, a nonzero value is returned
which specifies which exceptions are set. Otherwise the result is zero.
@@ -766,6 +792,7 @@ following functions:
@comment fenv.h
@comment ISO
@deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
This function stores in the variable pointed to by @var{flagp} an
implementation-defined value representing the current setting of the
exception flags indicated by @var{excepts}.
@@ -777,6 +804,7 @@ non-zero value otherwise.
@comment fenv.h
@comment ISO
@deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
This function restores the flags for the exceptions indicated by
@var{excepts} to the values stored in the variable pointed to by
@var{flagp}.
@@ -932,6 +960,7 @@ find out which one with this function:
@comment fenv.h
@comment ISO
@deftypefun int fegetround (void)
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
Returns the currently selected rounding mode, represented by one of the
values of the defined rounding mode macros.
@end deftypefun
@@ -942,6 +971,7 @@ To change the rounding mode, use this function:
@comment fenv.h
@comment ISO
@deftypefun int fesetround (int @var{round})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
Changes the currently selected rounding mode to @var{round}. If
@var{round} does not correspond to one of the supported rounding modes
nothing is changed. @code{fesetround} returns zero if it changed the
@@ -986,6 +1016,7 @@ To save the state of the FPU, use one of these functions:
@comment fenv.h
@comment ISO
@deftypefun int fegetenv (fenv_t *@var{envp})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
Store the floating-point environment in the variable pointed to by
@var{envp}.
@@ -996,6 +1027,7 @@ non-zero value otherwise.
@comment fenv.h
@comment ISO
@deftypefun int feholdexcept (fenv_t *@var{envp})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
Store the current floating-point environment in the object pointed to by
@var{envp}. Then clear all exception flags, and set the FPU to trap no
exceptions. Not all FPUs support trapping no exceptions; if
@@ -1034,6 +1066,7 @@ functions:
@comment fenv.h
@comment ISO
@deftypefun int fesetenv (const fenv_t *@var{envp})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
Set the floating-point environment to that described by @var{envp}.
The function returns zero in case the operation was successful, a
@@ -1043,6 +1076,7 @@ non-zero value otherwise.
@comment fenv.h
@comment ISO
@deftypefun int feupdateenv (const fenv_t *@var{envp})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
Like @code{fesetenv}, this function sets the floating-point environment
to that described by @var{envp}. However, if any exceptions were
flagged in the status word before @code{feupdateenv} was called, they
@@ -1063,6 +1097,7 @@ occur, you can use the following two functions.
@comment fenv.h
@comment GNU
@deftypefun int feenableexcept (int @var{excepts})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
This functions enables traps for each of the exceptions as indicated by
the parameter @var{except}. The individual exceptions are described in
@ref{Status bit operations}. Only the specified exceptions are
@@ -1075,6 +1110,7 @@ operation was successful, @code{-1} otherwise.
@comment fenv.h
@comment GNU
@deftypefun int fedisableexcept (int @var{excepts})
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
This functions disables traps for each of the exceptions as indicated by
the parameter @var{except}. The individual exceptions are described in
@ref{Status bit operations}. Only the specified exceptions are
@@ -1087,6 +1123,7 @@ operation was successful, @code{-1} otherwise.
@comment fenv.h
@comment GNU
@deftypefun int fegetexcept (void)
+@safety{@mtsafe{FIXME: unsafe ppc-nofpu-sim}@assafe{}@acsafe{}}
The function returns a bitmask of all currently enabled exceptions. It
returns @code{-1} in case of failure.
@end deftypefun
@@ -1138,6 +1175,7 @@ Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
@comment inttypes.h
@comment ISO
@deftypefunx intmax_t imaxabs (intmax_t @var{number})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the absolute value of @var{number}.
Most computers use a two's complement integer representation, in which
@@ -1159,6 +1197,7 @@ See @ref{Integers} for a description of the @code{intmax_t} type.
@comment math.h
@comment ISO
@deftypefunx {long double} fabsl (long double @var{number})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This function returns the absolute value of the floating-point number
@var{number}.
@end deftypefun
@@ -1172,6 +1211,7 @@ This function returns the absolute value of the floating-point number
@comment complex.h
@comment ISO
@deftypefunx {long double} cabsl (complex long double @var{z})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the absolute value of the complex number @var{z}
(@pxref{Complex Numbers}). The absolute value of a complex number is:
@@ -1209,6 +1249,7 @@ All these functions are declared in @file{math.h}.
@comment math.h
@comment ISO
@deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are used to split the number @var{value}
into a normalized fraction and an exponent.
@@ -1234,6 +1275,7 @@ zero is stored in @code{*@var{exponent}}.
@comment math.h
@comment ISO
@deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the result of multiplying the floating-point
number @var{value} by 2 raised to the power @var{exponent}. (It can
be used to reassemble floating-point numbers that were taken apart
@@ -1255,6 +1297,7 @@ equivalent to those of @code{ldexp} and @code{frexp}. See also the
@comment math.h
@comment BSD
@deftypefunx {long double} scalbl (long double @var{value}, long double @var{exponent})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{scalb} function is the BSD name for @code{ldexp}.
@end deftypefun
@@ -1267,6 +1310,7 @@ The @code{scalb} function is the BSD name for @code{ldexp}.
@comment math.h
@comment BSD
@deftypefunx {long double} scalbnl (long double @var{x}, int @var{n})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
@code{scalbn} is identical to @code{scalb}, except that the exponent
@var{n} is an @code{int} instead of a floating-point number.
@end deftypefun
@@ -1280,6 +1324,7 @@ The @code{scalb} function is the BSD name for @code{ldexp}.
@comment math.h
@comment BSD
@deftypefunx {long double} scalblnl (long double @var{x}, long int @var{n})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
@code{scalbln} is identical to @code{scalb}, except that the exponent
@var{n} is a @code{long int} instead of a floating-point number.
@end deftypefun
@@ -1293,6 +1338,7 @@ The @code{scalb} function is the BSD name for @code{ldexp}.
@comment math.h
@comment BSD
@deftypefunx {long double} significandl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
@code{significand} returns the mantissa of @var{x} scaled to the range
@math{[1, 2)}.
It is equivalent to @w{@code{scalb (@var{x}, (double) -ilogb (@var{x}))}}.
@@ -1327,6 +1373,7 @@ result as a @code{double} instead to get around this problem.
@comment math.h
@comment ISO
@deftypefunx {long double} ceill (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions round @var{x} upwards to the nearest integer,
returning that value as a @code{double}. Thus, @code{ceil (1.5)}
is @code{2.0}.
@@ -1341,6 +1388,7 @@ is @code{2.0}.
@comment math.h
@comment ISO
@deftypefunx {long double} floorl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions round @var{x} downwards to the nearest
integer, returning that value as a @code{double}. Thus, @code{floor
(1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
@@ -1355,6 +1403,7 @@ integer, returning that value as a @code{double}. Thus, @code{floor
@comment math.h
@comment ISO
@deftypefunx {long double} truncl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{trunc} functions round @var{x} towards zero to the nearest
integer (returned in floating-point format). Thus, @code{trunc (1.5)}
is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}.
@@ -1369,6 +1418,7 @@ is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}.
@comment math.h
@comment ISO
@deftypefunx {long double} rintl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions round @var{x} to an integer value according to the
current rounding mode. @xref{Floating Point Parameters}, for
information about the various rounding modes. The default
@@ -1389,6 +1439,7 @@ inexact exception.
@comment math.h
@comment ISO
@deftypefunx {long double} nearbyintl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the same value as the @code{rint} functions, but
do not raise the inexact exception if @var{x} is not an integer.
@end deftypefun
@@ -1402,6 +1453,7 @@ do not raise the inexact exception if @var{x} is not an integer.
@comment math.h
@comment ISO
@deftypefunx {long double} roundl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are similar to @code{rint}, but they round halfway
cases away from zero instead of to the nearest integer (or other
current rounding mode).
@@ -1416,6 +1468,7 @@ current rounding mode).
@comment math.h
@comment ISO
@deftypefunx {long int} lrintl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{rint}, but they return a
@code{long int} instead of a floating-point number.
@end deftypefun
@@ -1429,6 +1482,7 @@ These functions are just like @code{rint}, but they return a
@comment math.h
@comment ISO
@deftypefunx {long long int} llrintl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{rint}, but they return a
@code{long long int} instead of a floating-point number.
@end deftypefun
@@ -1442,6 +1496,7 @@ These functions are just like @code{rint}, but they return a
@comment math.h
@comment ISO
@deftypefunx {long int} lroundl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{round}, but they return a
@code{long int} instead of a floating-point number.
@end deftypefun
@@ -1455,6 +1510,7 @@ These functions are just like @code{round}, but they return a
@comment math.h
@comment ISO
@deftypefunx {long long int} llroundl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{round}, but they return a
@code{long long int} instead of a floating-point number.
@end deftypefun
@@ -1469,6 +1525,7 @@ These functions are just like @code{round}, but they return a
@comment math.h
@comment ISO
@deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions break the argument @var{value} into an integer part and a
fractional part (between @code{-1} and @code{1}, exclusive). Their sum
equals @var{value}. Each of the parts has the same sign as @var{value},
@@ -1495,6 +1552,7 @@ suits your problem.
@comment math.h
@comment ISO
@deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions compute the remainder from the division of
@var{numerator} by @var{denominator}. Specifically, the return value is
@code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
@@ -1517,6 +1575,7 @@ If @var{denominator} is zero, @code{fmod} signals a domain error.
@comment math.h
@comment BSD
@deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are like @code{fmod} except that they round the
internal quotient @var{n} to the nearest integer instead of towards zero
to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
@@ -1540,6 +1599,7 @@ If @var{denominator} is zero, @code{drem} signals a domain error.
@comment math.h
@comment BSD
@deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This function is another name for @code{drem}.
@end deftypefun
@@ -1561,6 +1621,7 @@ bits.
@comment math.h
@comment ISO
@deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return @var{x} but with the sign of @var{y}. They work
even if @var{x} or @var{y} are NaN or zero. Both of these can carry a
sign (although not all implementations support it) and this is one of
@@ -1576,6 +1637,7 @@ recommended functions in @w{IEEE 754}/@w{IEEE 854}).
@comment math.h
@comment ISO
@deftypefun int signbit (@emph{float-type} @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
@code{signbit} is a generic macro which can work on all floating-point
types. It returns a nonzero value if the value of @var{x} has its sign
bit set.
@@ -1594,6 +1656,7 @@ false, but @code{signbit (-0.0)} will return a nonzero value.
@comment math.h
@comment ISO
@deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{nextafter} function returns the next representable neighbor of
@var{x} in the direction towards @var{y}. The size of the step between
@var{x} and the result depends on the type of the result. If
@@ -1617,6 +1680,7 @@ recommended functions in @w{IEEE 754}/@w{IEEE 854}).
@comment math.h
@comment ISO
@deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are identical to the corresponding versions of
@code{nextafter} except that their second argument is a @code{long
double}.
@@ -1632,6 +1696,10 @@ double}.
@comment math.h
@comment ISO
@deftypefunx {long double} nanl (const char *@var{tagp})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
+@c It actually calls strtod, that has MT-Safety problems upon locale
+@c changes. It needs to be rechecked after the decision to document
+@c setlocale as MT-Unsafe to avoid all those issues.
The @code{nan} function returns a representation of NaN, provided that
NaN is supported by the target platform.
@code{nan ("@var{n-char-sequence}")} is equivalent to
@@ -1666,6 +1734,7 @@ arguments only once.
@comment math.h
@comment ISO
@deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is greater than
@var{y}. It is equivalent to @code{(@var{x}) > (@var{y})}, but no
exception is raised if @var{x} or @var{y} are NaN.
@@ -1674,6 +1743,7 @@ exception is raised if @var{x} or @var{y} are NaN.
@comment math.h
@comment ISO
@deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is greater than or
equal to @var{y}. It is equivalent to @code{(@var{x}) >= (@var{y})}, but no
exception is raised if @var{x} or @var{y} are NaN.
@@ -1682,6 +1752,7 @@ exception is raised if @var{x} or @var{y} are NaN.
@comment math.h
@comment ISO
@deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is less than @var{y}.
It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is
raised if @var{x} or @var{y} are NaN.
@@ -1690,6 +1761,7 @@ raised if @var{x} or @var{y} are NaN.
@comment math.h
@comment ISO
@deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is less than or equal
to @var{y}. It is equivalent to @code{(@var{x}) <= (@var{y})}, but no
exception is raised if @var{x} or @var{y} are NaN.
@@ -1698,6 +1770,7 @@ exception is raised if @var{x} or @var{y} are NaN.
@comment math.h
@comment ISO
@deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is less or greater
than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y}) ||
(@var{x}) > (@var{y})} (although it only evaluates @var{x} and @var{y}
@@ -1710,6 +1783,7 @@ expression is true if @var{x} or @var{y} are NaN.
@comment math.h
@comment ISO
@deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether its arguments are unordered. In other
words, it is true if @var{x} or @var{y} are NaN, and false otherwise.
@end deftypefn
@@ -1743,6 +1817,7 @@ perform these operations faster than the equivalent C code.
@comment math.h
@comment ISO
@deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{fmin} function returns the lesser of the two values @var{x}
and @var{y}. It is similar to the expression
@smallexample
@@ -1763,6 +1838,7 @@ are NaN, NaN is returned.
@comment math.h
@comment ISO
@deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{fmax} function returns the greater of the two values @var{x}
and @var{y}.
@@ -1779,6 +1855,7 @@ are NaN, NaN is returned.
@comment math.h
@comment ISO
@deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{fdim} function returns the positive difference between
@var{x} and @var{y}. The positive difference is @math{@var{x} -
@var{y}} if @var{x} is greater than @var{y}, and @math{0} otherwise.
@@ -1796,6 +1873,7 @@ If @var{x}, @var{y}, or both are NaN, NaN is returned.
@comment ISO
@deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
@cindex butterfly
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{fma} function performs floating-point multiply-add. This is
the operation @math{(@var{x} @mul{} @var{y}) + @var{z}}, but the
intermediate result is not rounded to the destination type. This can
@@ -1925,6 +2003,7 @@ available in three variants, one for each of the three complex types.
@comment complex.h
@comment ISO
@deftypefunx {long double} creall (complex long double @var{z})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the real part of the complex number @var{z}.
@end deftypefun
@@ -1937,6 +2016,7 @@ These functions return the real part of the complex number @var{z}.
@comment complex.h
@comment ISO
@deftypefunx {long double} cimagl (complex long double @var{z})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the imaginary part of the complex number @var{z}.
@end deftypefun
@@ -1949,6 +2029,7 @@ These functions return the imaginary part of the complex number @var{z}.
@comment complex.h
@comment ISO
@deftypefunx {complex long double} conjl (complex long double @var{z})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the conjugate value of the complex number
@var{z}. The conjugate of a complex number has the same real part and a
negated imaginary part. In other words, @samp{conj(a + bi) = a + -bi}.
@@ -1963,6 +2044,7 @@ negated imaginary part. In other words, @samp{conj(a + bi) = a + -bi}.
@comment complex.h
@comment ISO
@deftypefunx {long double} cargl (complex long double @var{z})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the argument of the complex number @var{z}.
The argument of a complex number is the angle in the complex plane
between the positive real axis and a line passing through zero and the
@@ -1981,6 +2063,7 @@ number. This angle is measured in the usual fashion and ranges from
@comment complex.h
@comment ISO
@deftypefunx {complex long double} cprojl (complex long double @var{z})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions return the projection of the complex value @var{z} onto
the Riemann sphere. Values with a infinite imaginary part are projected
to positive infinity on the real axis, even if the real part is NaN. If
@@ -2026,6 +2109,16 @@ as well.
@comment stdlib.h
@comment ISO
@deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
+@c strtol uses the thread-local pointer to the locale in effect, and
+@c strtol_l loads the LC_NUMERIC locale data from it early on and once,
+@c but if the locale is the global locale, and another thread calls
+@c setlocale in a way that modifies the pointer to the LC_CTYPE locale
+@c category, the behavior of e.g. IS*, TOUPPER will vary throughout the
+@c execution of the function, because they re-read the locale data from
+@c the given locale pointer. We solved this by documenting setlocale as
+@c MT-Unsafe, but there might be other reasons why it's neither MT- nor
+@c AS-Safe; recheck.
The @code{strtol} (``string-to-long'') function converts the initial
part of @var{string} to a signed integer, which is returned as a value
of type @code{long int}.
@@ -2089,6 +2182,7 @@ There is an example at the end of this section.
@comment wchar.h
@comment ISO
@deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstol} function is equivalent to the @code{strtol} function
in nearly all aspects but handles wide character strings.
@@ -2098,6 +2192,7 @@ The @code{wcstol} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@comment stdlib.h
@comment ISO
@deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{strtoul} (``string-to-unsigned-long'') function is like
@code{strtol} except it converts to an @code{unsigned long int} value.
The syntax is the same as described above for @code{strtol}. The value
@@ -2116,6 +2211,7 @@ range, or @code{ERANGE} on overflow.
@comment wchar.h
@comment ISO
@deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstoul} function is equivalent to the @code{strtoul} function
in nearly all aspects but handles wide character strings.
@@ -2125,6 +2221,7 @@ The @code{wcstoul} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@comment stdlib.h
@comment ISO
@deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{strtoll} function is like @code{strtol} except that it returns
a @code{long long int} value, and accepts numbers with a correspondingly
larger range.
@@ -2141,6 +2238,7 @@ The @code{strtoll} function was introduced in @w{ISO C99}.
@comment wchar.h
@comment ISO
@deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstoll} function is equivalent to the @code{strtoll} function
in nearly all aspects but handles wide character strings.
@@ -2150,12 +2248,14 @@ The @code{wcstoll} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@comment stdlib.h
@comment BSD
@deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
@code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstoq} function is equivalent to the @code{strtoq} function
in nearly all aspects but handles wide character strings.
@@ -2165,6 +2265,7 @@ The @code{wcstoq} function is a GNU extension.
@comment stdlib.h
@comment ISO
@deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{strtoull} function is related to @code{strtoll} the same way
@code{strtoul} is related to @code{strtol}.
@@ -2174,6 +2275,7 @@ The @code{strtoull} function was introduced in @w{ISO C99}.
@comment wchar.h
@comment ISO
@deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstoull} function is equivalent to the @code{strtoull} function
in nearly all aspects but handles wide character strings.
@@ -2183,12 +2285,14 @@ The @code{wcstoull} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@comment stdlib.h
@comment BSD
@deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
@code{strtouq} is the BSD name for @code{strtoull}.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstouq} function is equivalent to the @code{strtouq} function
in nearly all aspects but handles wide character strings.
@@ -2198,6 +2302,7 @@ The @code{wcstouq} function is a GNU extension.
@comment inttypes.h
@comment ISO
@deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{strtoimax} function is like @code{strtol} except that it returns
a @code{intmax_t} value, and accepts numbers of a corresponding range.
@@ -2214,6 +2319,7 @@ See @ref{Integers} for a description of the @code{intmax_t} type. The
@comment wchar.h
@comment ISO
@deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstoimax} function is equivalent to the @code{strtoimax} function
in nearly all aspects but handles wide character strings.
@@ -2223,6 +2329,7 @@ The @code{wcstoimax} function was introduced in @w{ISO C99}.
@comment inttypes.h
@comment ISO
@deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{strtoumax} function is related to @code{strtoimax}
the same way that @code{strtoul} is related to @code{strtol}.
@@ -2233,6 +2340,7 @@ See @ref{Integers} for a description of the @code{intmax_t} type. The
@comment wchar.h
@comment ISO
@deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstoumax} function is equivalent to the @code{strtoumax} function
in nearly all aspects but handles wide character strings.
@@ -2242,6 +2350,7 @@ The @code{wcstoumax} function was introduced in @w{ISO C99}.
@comment stdlib.h
@comment ISO
@deftypefun {long int} atol (const char *@var{string})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
This function is similar to the @code{strtol} function with a @var{base}
argument of @code{10}, except that it need not detect overflow errors.
The @code{atol} function is provided mostly for compatibility with
@@ -2251,6 +2360,7 @@ existing code; using @code{strtol} is more robust.
@comment stdlib.h
@comment ISO
@deftypefun int atoi (const char *@var{string})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
This function is like @code{atol}, except that it returns an @code{int}.
The @code{atoi} function is also considered obsolete; use @code{strtol}
instead.
@@ -2259,6 +2369,7 @@ instead.
@comment stdlib.h
@comment ISO
@deftypefun {long long int} atoll (const char *@var{string})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
This function is similar to @code{atol}, except it returns a @code{long
long int}.
@@ -2323,6 +2434,7 @@ as well.
@comment stdlib.h
@comment ISO
@deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{strtod} (``string-to-double'') function converts the initial
part of @var{string} to a floating-point number, which is returned as a
value of type @code{double}.
@@ -2408,6 +2520,7 @@ examining @var{errno} and @var{tailptr}.
@comment stdlib.h
@comment ISO
@deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
These functions are analogous to @code{strtod}, but return @code{float}
and @code{long double} values respectively. They report errors in the
same way as @code{strtod}. @code{strtof} can be substantially faster
@@ -2427,6 +2540,7 @@ These functions have been GNU extensions and are new to @w{ISO C99}.
@comment stdlib.h
@comment ISO
@deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are
equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and
@code{strtold} functions but it handles wide character string.
@@ -2439,6 +2553,7 @@ C90}. The @code{wcstof} and @code{wcstold} functions were introduced in
@comment stdlib.h
@comment ISO
@deftypefun double atof (const char *@var{string})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
This function is similar to the @code{strtod} function, except that it
need not detect overflow and underflow errors. The @code{atof} function
is provided mostly for compatibility with existing code; using
@@ -2465,6 +2580,7 @@ All these functions are defined in @file{stdlib.h}.
@comment stdlib.h
@comment SVID, Unix98
@deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@mtunsafe{static buffer}@assafe{static buffer}@acsafe{}}
The function @code{ecvt} converts the floating-point number @var{value}
to a string with at most @var{ndigit} decimal digits. The
returned string contains no decimal point or sign. The first digit of
@@ -2490,6 +2606,7 @@ and sets @var{d} to @code{2} and @var{n} to @code{0}.
@comment stdlib.h
@comment SVID, Unix98
@deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@mtunsafe{static buffer}@assafe{static buffer}@acsafe{}}
The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies
the number of digits after the decimal point. If @var{ndigit} is less
than zero, @var{value} is rounded to the @math{@var{ndigit}+1}'th place to the
@@ -2508,6 +2625,9 @@ to @code{fcvt}.
@comment stdlib.h
@comment SVID, Unix98
@deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
+@c gcvt calls sprintf, that ultimately calls vfprintf, which malloc()s
+@c args_value if it's too large, but gcvt never exercises this path.
@code{gcvt} is functionally equivalent to @samp{sprintf(buf, "%*g",
ndigit, value}. It is provided only for compatibility's sake. It
returns @var{buf}.
@@ -2522,6 +2642,7 @@ functions that take @code{long double} arguments.
@comment stdlib.h
@comment GNU
@deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@mtunsafe{static buffer}@assafe{static buffer}@acsafe{}}
This function is equivalent to @code{ecvt} except that it takes a
@code{long double} for the first parameter and that @var{ndigit} is
restricted by the precision of a @code{long double}.
@@ -2530,6 +2651,7 @@ restricted by the precision of a @code{long double}.
@comment stdlib.h
@comment GNU
@deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@mtunsafe{static buffer}@assafe{static buffer}@acsafe{}}
This function is equivalent to @code{fcvt} except that it
takes a @code{long double} for the first parameter and that @var{ndigit} is
restricted by the precision of a @code{long double}.
@@ -2538,6 +2660,7 @@ restricted by the precision of a @code{long double}.
@comment stdlib.h
@comment GNU
@deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This function is equivalent to @code{gcvt} except that it takes a
@code{long double} for the first parameter and that @var{ndigit} is
restricted by the precision of a @code{long double}.
@@ -2558,6 +2681,7 @@ user-supplied buffer.
@comment stdlib.h
@comment GNU
@deftypefun int ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{ecvt_r} function is the same as @code{ecvt}, except
that it places its result into the user-specified buffer pointed to by
@var{buf}, with length @var{len}. The return value is @code{-1} in
@@ -2569,6 +2693,7 @@ This function is a GNU extension.
@comment stdlib.h
@comment SVID, Unix98
@deftypefun int fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{fcvt_r} function is the same as @code{fcvt}, except that it
places its result into the user-specified buffer pointed to by
@var{buf}, with length @var{len}. The return value is @code{-1} in
@@ -2580,6 +2705,7 @@ This function is a GNU extension.
@comment stdlib.h
@comment GNU
@deftypefun int qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{qecvt_r} function is the same as @code{qecvt}, except
that it places its result into the user-specified buffer pointed to by
@var{buf}, with length @var{len}. The return value is @code{-1} in
@@ -2591,6 +2717,7 @@ This function is a GNU extension.
@comment stdlib.h
@comment GNU
@deftypefun int qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{qfcvt_r} function is the same as @code{qfcvt}, except
that it places its result into the user-specified buffer pointed to by
@var{buf}, with length @var{len}. The return value is @code{-1} in
Thread safety documentation.
From: Alexandre Oliva <aoliva@redhat.com>
for ChangeLog
* manual/stdio.texi: Document thread safety properties.
---
manual/stdio.texi | 207 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 207 insertions(+)
diff --git a/manual/stdio.texi b/manual/stdio.texi
index 3f9be9bc5..8765be3 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -148,6 +148,8 @@ Everything described in this section is declared in the header file
@comment stdio.h
@comment ISO
@deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
+@safety{@mtsafe{}@assafe{}@acunsafe{memleak, fdleak, lockleak}}
+@c fopen may leak the list lock if cancelled within _IO_link_in.
The @code{fopen} function opens a stream for I/O to the file
@var{filename}, and returns a pointer to the stream.
@@ -265,6 +267,7 @@ Locks}.
@comment stdio.h
@comment Unix98
@deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
+@safety{@mtsafe{}@assafe{}@acsafe{memleak, fdleak}}
This function is similar to @code{fopen} but the stream it returns a
pointer for is opened using @code{open64}. Therefore this stream can be
used even on files larger then @math{2^31} bytes on 32 bit machines.
@@ -294,6 +297,16 @@ resource limit; @pxref{Limits on Resources}.
@comment stdio.h
@comment ISO
@deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{badstream, fdleak}}
+@c Like most I/O operations, this one is guarded by a recursive lock,
+@c released even upon cancellation, but cancellation may leak file
+@c descriptors and leave the stream in an inconsistent state (e.g.,
+@c still bound to the closed descriptor). Also, if the stream is
+@c part-way through a significant update (say running freopen) when a
+@c signal handler calls freopen again on the same stream, the result is
+@c likely to be an inconsistent stream, and the possibility of closing
+@c twice file descriptor number that the stream used to use, the second
+@c time when it might have already been reused by another thread.
This function is like a combination of @code{fclose} and @code{fopen}.
It first closes the stream referred to by @var{stream}, ignoring any
errors that are detected in the process. (Because errors are ignored,
@@ -320,6 +333,7 @@ interface replaces transparently the old interface.
@comment stdio.h
@comment Unix98
@deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{badstream, fdleak}}
This function is similar to @code{freopen}. The only difference is that
on 32 bit machine the stream returned is able to read beyond the
@math{2^31} bytes limits imposed by the normal interface. It should be
@@ -341,6 +355,7 @@ descriptor and these functions are also available in @theglibc{}.
@comment stdio_ext.h
@comment GNU
@deftypefun int __freadable (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{__freadable} function determines whether the stream
@var{stream} was opened to allow reading. In this case the return value
is nonzero. For write-only streams the function returns zero.
@@ -351,6 +366,7 @@ This function is declared in @file{stdio_ext.h}.
@comment stdio_ext.h
@comment GNU
@deftypefun int __fwritable (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{__fwritable} function determines whether the stream
@var{stream} was opened to allow writing. In this case the return value
is nonzero. For read-only streams the function returns zero.
@@ -364,6 +380,7 @@ They provide even finer-grained information.
@comment stdio_ext.h
@comment GNU
@deftypefun int __freading (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{__freading} function determines whether the stream
@var{stream} was last read from or whether it is opened read-only. In
this case the return value is nonzero, otherwise it is zero.
@@ -377,6 +394,7 @@ This function is declared in @file{stdio_ext.h}.
@comment stdio_ext.h
@comment GNU
@deftypefun int __fwriting (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{__fwriting} function determines whether the stream
@var{stream} was last written to or whether it is opened write-only. In
this case the return value is nonzero, otherwise it is zero.
@@ -396,6 +414,21 @@ cannot perform any additional operations on it.
@comment stdio.h
@comment ISO
@deftypefun int fclose (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak, memleak, fdleak}}
+@c After fclose, it is undefined behavior to use the stream it points
+@c to. Therefore, one must only call fclose when the stream is
+@c otherwise unused. Concurrent uses started before will complete
+@c successfully because of the lock, which makes it MT-Safe. Calling it
+@c from a signal handler is perfectly safe if the stream is known to be
+@c no longer used, which is a precondition for fclose to be safe in the
+@c first place; since this is no further requirement, fclose is safe for
+@c use in async signals too. After calling fclose, you can no longer
+@c use the stream, not even to fclose it again, so its memory and file
+@c descriptor may leak if fclose is canceled before @c releasing them.
+@c That the stream must be unused and it becomes unused after the call
+@c is what would enable fclose to be AS- and AC-Safe while freopen
+@c isn't. However, because of the possibility of leaving __gconv_lock
+@c taken upon cancellation, AC-Safety is lost.
This function causes @var{stream} to be closed and the connection to
the corresponding file to be broken. Any buffered output is written
and any buffered input is discarded. The @code{fclose} function returns
@@ -418,6 +451,12 @@ another function.
@comment stdio.h
@comment GNU
@deftypefun int fcloseall (void)
+@safety{@mtunsafe{nolock}@asunsafe{nolock}@acsafe{}}
+@c Like fclose, using any previously-opened streams after fcloseall is
+@c undefined. However, the implementation of fcloseall isn't equivalent
+@c to calling fclose for all streams: it just flushes and unbuffers all
+@c streams, without any locking. It's the flushing without locking that
+@c makes it unsafe.
This function causes all open streams of the process to be closed and
the connection to corresponding files to be broken. All buffered data
is written and any buffered input is discarded. The @code{fcloseall}
@@ -474,6 +513,9 @@ perform the stream locking in the application code.
@comment stdio.h
@comment POSIX
@deftypefun void flockfile (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak}}
+@c There's no way to tell whether the lock was acquired before or after
+@c cancellation so as to unlock only when appropriate.
The @code{flockfile} function acquires the internal locking object
associated with the stream @var{stream}. This ensures that no other
thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
@@ -485,6 +527,7 @@ thread will block until the lock is acquired. An explicit call to
@comment stdio.h
@comment POSIX
@deftypefun int ftrylockfile (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak}}
The @code{ftrylockfile} function tries to acquire the internal locking
object associated with the stream @var{stream} just like
@code{flockfile}. But unlike @code{flockfile} this function does not
@@ -496,6 +539,7 @@ another thread.
@comment stdio.h
@comment POSIX
@deftypefun void funlockfile (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak}}
The @code{funlockfile} function releases the internal locking object of
the stream @var{stream}. The stream must have been locked before by a
call to @code{flockfile} or a successful call of @code{ftrylockfile}.
@@ -621,6 +665,15 @@ was introduced in Solaris and is available in @theglibc{} as well.
@comment stdio_ext.h
@comment GNU
@deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
+@safety{@mtunsafe{unguarded-uses, fxlock, lockleak}@asunsafe{lockleak}@acsafe{}}
+@c Changing the implicit-locking status of a stream while it's in use by
+@c another thread may cause a lock to be implicitly acquired and not
+@c released, or vice-versa. This function should probably hold the lock
+@c while changing this setting, to make sure we don't change it while
+@c there are any concurrent uses. Meanwhile, callers should acquire the
+@c lock themselves to be safe, and even concurrent uses with external
+@c locking will be fine, as long as functions that require external
+@c locking are not called without holding locks.
The @code{__fsetlocking} function can be used to select whether the
stream operations will implicitly acquire the locking object of the
@@ -635,6 +688,9 @@ locking. Every stream operation with exception of the @code{_unlocked}
variants will implicitly lock the stream.
@item FSETLOCKING_BYCALLER
+@c ??? Does the possibility of disabling implicit locking on any stream
+@c make any of the non-_unlocked functions as MT-unsafe as the _unlocked
+@c ones?
After the @code{__fsetlocking} function returns the user is responsible
for locking the stream. None of the stream operations will implicitly
do this anymore until the state is set back to
@@ -725,6 +781,10 @@ will simply be strange or the application will simply crash. The
@comment wchar.h
@comment ISO
@deftypefun int fwide (FILE *@var{stream}, int @var{mode})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak}}
+@c Querying is always safe, but changing the stream when it's in use
+@c upthread may be problematic. Like most lock-acquiring functions,
+@c this one may leak the lock if canceled.
The @code{fwide} function can be used to set and query the state of the
orientation of the stream @var{stream}. If the @var{mode} parameter has
@@ -811,6 +871,16 @@ These narrow streams functions are declared in the header file
@comment stdio.h
@comment ISO
@deftypefun int fputc (int @var{c}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
+@c If the stream is in use when interrupted by a signal, the recursive
+@c lock won't help ensure the stream is consistent; indeed, if fputc
+@c gets a signal precisely before the post-incremented _IO_write_ptr
+@c value is stored, we may overwrite the interrupted write. Conversely,
+@c depending on compiler optimizations, the incremented _IO_write_ptr
+@c may be stored before the character is stored in the buffer,
+@c corrupting the stream if async cancel hits between the two stores.
+@c There may be other reasons for AS- and AC-unsafety in the overflow
+@c cases.
The @code{fputc} function converts the character @var{c} to type
@code{unsigned char}, and writes it to the stream @var{stream}.
@code{EOF} is returned if a write error occurs; otherwise the
@@ -820,6 +890,7 @@ character @var{c} is returned.
@comment wchar.h
@comment ISO
@deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{fputwc} function writes the wide character @var{wc} to the
stream @var{stream}. @code{WEOF} is returned if a write error occurs;
otherwise the character @var{wc} is returned.
@@ -828,6 +899,10 @@ otherwise the character @var{wc} is returned.
@comment stdio.h
@comment POSIX
@deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
+@c The unlocked functions can't possibly satisfy the MT-Safety
+@c requirements on their own, because they require external locking for
+@c safety.
The @code{fputc_unlocked} function is equivalent to the @code{fputc}
function except that it does not implicitly lock the stream.
@end deftypefun
@@ -835,6 +910,7 @@ function except that it does not implicitly lock the stream.
@comment wchar.h
@comment POSIX
@deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
function except that it does not implicitly lock the stream.
@@ -844,6 +920,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefun int putc (int @var{c}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This is just like @code{fputc}, except that most systems implement it as
a macro, making it faster. One consequence is that it may evaluate the
@var{stream} argument more than once, which is an exception to the
@@ -854,6 +931,7 @@ use for writing a single character.
@comment wchar.h
@comment ISO
@deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This is just like @code{fputwc}, except that it can be implement as
a macro, making it faster. One consequence is that it may evaluate the
@var{stream} argument more than once, which is an exception to the
@@ -864,6 +942,7 @@ use for writing a single wide character.
@comment stdio.h
@comment POSIX
@deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{putc_unlocked} function is equivalent to the @code{putc}
function except that it does not implicitly lock the stream.
@end deftypefun
@@ -871,6 +950,7 @@ function except that it does not implicitly lock the stream.
@comment wchar.h
@comment GNU
@deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{putwc_unlocked} function is equivalent to the @code{putwc}
function except that it does not implicitly lock the stream.
@@ -880,6 +960,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefun int putchar (int @var{c})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{putchar} function is equivalent to @code{putc} with
@code{stdout} as the value of the @var{stream} argument.
@end deftypefun
@@ -887,6 +968,7 @@ The @code{putchar} function is equivalent to @code{putc} with
@comment wchar.h
@comment ISO
@deftypefun wint_t putwchar (wchar_t @var{wc})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{putwchar} function is equivalent to @code{putwc} with
@code{stdout} as the value of the @var{stream} argument.
@end deftypefun
@@ -894,6 +976,7 @@ The @code{putwchar} function is equivalent to @code{putwc} with
@comment stdio.h
@comment POSIX
@deftypefun int putchar_unlocked (int @var{c})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{putchar_unlocked} function is equivalent to the @code{putchar}
function except that it does not implicitly lock the stream.
@end deftypefun
@@ -901,6 +984,7 @@ function except that it does not implicitly lock the stream.
@comment wchar.h
@comment GNU
@deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
function except that it does not implicitly lock the stream.
@@ -910,6 +994,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The function @code{fputs} writes the string @var{s} to the stream
@var{stream}. The terminating null character is not written.
This function does @emph{not} add a newline character, either.
@@ -933,6 +1018,7 @@ outputs the text @samp{Are you hungry?} followed by a newline.
@comment wchar.h
@comment ISO
@deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The function @code{fputws} writes the wide character string @var{ws} to
the stream @var{stream}. The terminating null character is not written.
This function does @emph{not} add a newline character, either. It
@@ -945,6 +1031,7 @@ a non-negative value.
@comment stdio.h
@comment GNU
@deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fputs_unlocked} function is equivalent to the @code{fputs}
function except that it does not implicitly lock the stream.
@@ -954,6 +1041,7 @@ This function is a GNU extension.
@comment wchar.h
@comment GNU
@deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fputws_unlocked} function is equivalent to the @code{fputws}
function except that it does not implicitly lock the stream.
@@ -963,6 +1051,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefun int puts (const char *@var{s})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{puts} function writes the string @var{s} to the stream
@code{stdout} followed by a newline. The terminating null character of
the string is not written. (Note that @code{fputs} does @emph{not}
@@ -982,6 +1071,7 @@ outputs the text @samp{This is a message.} followed by a newline.
@comment stdio.h
@comment SVID
@deftypefun int putw (int @var{w}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function writes the word @var{w} (that is, an @code{int}) to
@var{stream}. It is provided for compatibility with SVID, but we
recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
@@ -1014,6 +1104,11 @@ it will fit in a @samp{char} variable without loss of information.
@comment stdio.h
@comment ISO
@deftypefun int fgetc (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
+@c Same caveats as fputc, but instead of losing a write in case of async
+@c signals, we may read the same character more than once, and the
+@c stream may be left in odd states due to cancellation in the underflow
+@c cases.
This function reads the next character as an @code{unsigned char} from
the stream @var{stream} and returns its value, converted to an
@code{int}. If an end-of-file condition or read error occurs,
@@ -1023,6 +1118,7 @@ the stream @var{stream} and returns its value, converted to an
@comment wchar.h
@comment ISO
@deftypefun wint_t fgetwc (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function reads the next wide character from the stream @var{stream}
and returns its value. If an end-of-file condition or read error
occurs, @code{WEOF} is returned instead.
@@ -1031,6 +1127,7 @@ occurs, @code{WEOF} is returned instead.
@comment stdio.h
@comment POSIX
@deftypefun int fgetc_unlocked (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
function except that it does not implicitly lock the stream.
@end deftypefun
@@ -1038,6 +1135,7 @@ function except that it does not implicitly lock the stream.
@comment wchar.h
@comment GNU
@deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
function except that it does not implicitly lock the stream.
@@ -1047,6 +1145,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefun int getc (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This is just like @code{fgetc}, except that it is permissible (and
typical) for it to be implemented as a macro that evaluates the
@var{stream} argument more than once. @code{getc} is often highly
@@ -1057,6 +1156,7 @@ character.
@comment wchar.h
@comment ISO
@deftypefun wint_t getwc (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This is just like @code{fgetwc}, except that it is permissible for it to
be implemented as a macro that evaluates the @var{stream} argument more
than once. @code{getwc} can be highly optimized, so it is usually the
@@ -1066,6 +1166,7 @@ best function to use to read a single wide character.
@comment stdio.h
@comment POSIX
@deftypefun int getc_unlocked (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{getc_unlocked} function is equivalent to the @code{getc}
function except that it does not implicitly lock the stream.
@end deftypefun
@@ -1073,6 +1174,7 @@ function except that it does not implicitly lock the stream.
@comment wchar.h
@comment GNU
@deftypefun wint_t getwc_unlocked (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{getwc_unlocked} function is equivalent to the @code{getwc}
function except that it does not implicitly lock the stream.
@@ -1082,6 +1184,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefun int getchar (void)
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
as the value of the @var{stream} argument.
@end deftypefun
@@ -1089,6 +1192,7 @@ as the value of the @var{stream} argument.
@comment wchar.h
@comment ISO
@deftypefun wint_t getwchar (void)
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
as the value of the @var{stream} argument.
@end deftypefun
@@ -1096,6 +1200,7 @@ as the value of the @var{stream} argument.
@comment stdio.h
@comment POSIX
@deftypefun int getchar_unlocked (void)
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{getchar_unlocked} function is equivalent to the @code{getchar}
function except that it does not implicitly lock the stream.
@end deftypefun
@@ -1103,6 +1208,7 @@ function except that it does not implicitly lock the stream.
@comment wchar.h
@comment GNU
@deftypefun wint_t getwchar_unlocked (void)
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
function except that it does not implicitly lock the stream.
@@ -1145,6 +1251,7 @@ y_or_n_p (const char *question)
@comment stdio.h
@comment SVID
@deftypefun int getw (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function reads a word (that is, an @code{int}) from @var{stream}.
It's provided for compatibility with SVID. We recommend you use
@code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc},
@@ -1173,6 +1280,7 @@ All these functions are declared in @file{stdio.h}.
@comment stdio.h
@comment GNU
@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function reads an entire line from @var{stream}, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in @code{*@var{lineptr}}.
@@ -1208,6 +1316,7 @@ If an error occurs or end of file is reached without any bytes read,
@comment stdio.h
@comment GNU
@deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function is like @code{getline} except that the character which
tells it to stop reading is not necessarily newline. The argument
@var{delimiter} specifies the delimiter character; @code{getdelim} keeps
@@ -1232,6 +1341,7 @@ getline (char **lineptr, size_t *n, FILE *stream)
@comment stdio.h
@comment ISO
@deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{fgets} function reads characters from the stream @var{stream}
up to and including a newline character and stores them in the string
@var{s}, adding a null character to mark the end of the string. You
@@ -1255,6 +1365,7 @@ error message. We recommend using @code{getline} instead of @code{fgets}.
@comment wchar.h
@comment ISO
@deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{fgetws} function reads wide characters from the stream
@var{stream} up to and including a newline character and stores them in
the string @var{ws}, adding a null wide character to mark the end of the
@@ -1280,6 +1391,7 @@ message.
@comment stdio.h
@comment GNU
@deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fgets_unlocked} function is equivalent to the @code{fgets}
function except that it does not implicitly lock the stream.
@@ -1289,6 +1401,7 @@ This function is a GNU extension.
@comment wchar.h
@comment GNU
@deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
function except that it does not implicitly lock the stream.
@@ -1298,6 +1411,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefn {Deprecated function} {char *} gets (char *@var{s})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The function @code{gets} reads characters from the stream @code{stdin}
up to the next newline character, and stores them in the string @var{s}.
The newline character is discarded (note that this differs from the
@@ -1388,6 +1502,7 @@ reverses the action of @code{getc}.
@comment stdio.h
@comment ISO
@deftypefun int ungetc (int @var{c}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{ungetc} function pushes back the character @var{c} onto the
input stream @var{stream}. So the next input from @var{stream} will
read @var{c} before anything else.
@@ -1425,6 +1540,7 @@ will encounter end of file.
@comment wchar.h
@comment ISO
@deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{ungetwc} function behaves just like @code{ungetc} just that it
pushes back a wide character.
@end deftypefun
@@ -1483,6 +1599,7 @@ These functions are declared in @file{stdio.h}.
@comment stdio.h
@comment ISO
@deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function reads up to @var{count} objects of size @var{size} into
the array @var{data}, from the stream @var{stream}. It returns the
number of objects actually read, which might be less than @var{count} if
@@ -1498,6 +1615,7 @@ object. Therefore, the stream remains at the actual end of the file.
@comment stdio.h
@comment GNU
@deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fread_unlocked} function is equivalent to the @code{fread}
function except that it does not implicitly lock the stream.
@@ -1507,6 +1625,7 @@ This function is a GNU extension.
@comment stdio.h
@comment ISO
@deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function writes up to @var{count} objects of size @var{size} from
the array @var{data}, to the stream @var{stream}. The return value is
normally @var{count}, if the call succeeds. Any other value indicates
@@ -1516,6 +1635,7 @@ some sort of error, such as running out of space.
@comment stdio.h
@comment GNU
@deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
function except that it does not implicitly lock the stream.
@@ -2257,6 +2377,7 @@ just include @file{stdio.h}.
@comment stdio.h
@comment ISO
@deftypefun int printf (const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
The @code{printf} function prints the optional arguments under the
control of the template string @var{template} to the stream
@code{stdout}. It returns the number of characters printed, or a
@@ -2266,6 +2387,7 @@ negative value if there was an output error.
@comment wchar.h
@comment ISO
@deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
The @code{wprintf} function prints the optional arguments under the
control of the wide template string @var{template} to the stream
@code{stdout}. It returns the number of wide characters printed, or a
@@ -2275,6 +2397,7 @@ negative value if there was an output error.
@comment stdio.h
@comment ISO
@deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is just like @code{printf}, except that the output is
written to the stream @var{stream} instead of @code{stdout}.
@end deftypefun
@@ -2282,6 +2405,7 @@ written to the stream @var{stream} instead of @code{stdout}.
@comment wchar.h
@comment ISO
@deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is just like @code{wprintf}, except that the output is
written to the stream @var{stream} instead of @code{stdout}.
@end deftypefun
@@ -2289,6 +2413,7 @@ written to the stream @var{stream} instead of @code{stdout}.
@comment stdio.h
@comment ISO
@deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is like @code{printf}, except that the output is stored in the character
array @var{s} instead of written to a stream. A null character is written
to mark the end of the string.
@@ -2313,6 +2438,7 @@ described below.
@comment wchar.h
@comment GNU
@deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is like @code{wprintf}, except that the output is stored in the
wide character array @var{ws} instead of written to a stream. A null
wide character is written to mark the end of the string. The @var{size}
@@ -2337,6 +2463,7 @@ again and decided to not define an function exactly corresponding to
@comment stdio.h
@comment GNU
@deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
The @code{snprintf} function is similar to @code{sprintf}, except that
the @var{size} argument specifies the maximum number of characters to
produce. The trailing null character is counted towards this limit, so
@@ -2407,6 +2534,7 @@ in dynamically allocated memory.
@comment stdio.h
@comment GNU
@deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This function is similar to @code{sprintf}, except that it dynamically
allocates a string (as with @code{malloc}; @pxref{Unconstrained
Allocation}) to hold the output, instead of putting the output in a
@@ -2439,6 +2567,7 @@ make_message (char *name, char *value)
@comment stdio.h
@comment GNU
@deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
+@safety{@mtunsafe{unlocked-obstack, glocale-revisit}@asunsafe{bad-obstack, glocale-revisit}@acsafe{bad-obstack, memleak}}
This function is similar to @code{asprintf}, except that it uses the
obstack @var{obstack} to allocate the space. @xref{Obstacks}.
@@ -2509,6 +2638,7 @@ Prototypes for these functions are declared in @file{stdio.h}.
@comment stdio.h
@comment ISO
@deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is similar to @code{printf} except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap}.
@@ -2517,6 +2647,7 @@ pointer @var{ap}.
@comment wchar.h
@comment ISO
@deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is similar to @code{wprintf} except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap}.
@@ -2525,6 +2656,12 @@ pointer @var{ap}.
@comment stdio.h
@comment ISO
@deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
+@c Although vfprintf sets up a cleanup region to release the lock on the
+@c output stream, it doesn't use it to release args_value or string in
+@c case of cancellation. This doesn't make it unsafe, but cancelling it
+@c may leak memory. The unguarded use of __printf_function_table is
+@c also of concern for all callers.
This is the equivalent of @code{fprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun
@@ -2532,6 +2669,7 @@ specified directly as for @code{vprintf}.
@comment wchar.h
@comment ISO
@deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This is the equivalent of @code{fwprintf} with the variable argument list
specified directly as for @code{vwprintf}.
@end deftypefun
@@ -2539,6 +2677,7 @@ specified directly as for @code{vwprintf}.
@comment stdio.h
@comment ISO
@deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is the equivalent of @code{sprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun
@@ -2546,6 +2685,7 @@ specified directly as for @code{vprintf}.
@comment wchar.h
@comment GNU
@deftypefun int vswprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is the equivalent of @code{swprintf} with the variable argument list
specified directly as for @code{vwprintf}.
@end deftypefun
@@ -2553,6 +2693,7 @@ specified directly as for @code{vwprintf}.
@comment stdio.h
@comment GNU
@deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is the equivalent of @code{snprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun
@@ -2560,6 +2701,7 @@ specified directly as for @code{vprintf}.
@comment stdio.h
@comment GNU
@deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
The @code{vasprintf} function is the equivalent of @code{asprintf} with the
variable argument list specified directly as for @code{vprintf}.
@end deftypefun
@@ -2567,6 +2709,10 @@ variable argument list specified directly as for @code{vprintf}.
@comment stdio.h
@comment GNU
@deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{unlocked-obstack, glocale-revisit}@asunsafe{bad-obstack, glocale-revisit}@acsafe{bad-obstack, memleak}}
+@c The obstack is not guarded by mutexes, it might be at an inconsistent
+@c state within a signal handler, and it could be left at an
+@c inconsistent state in case of cancellation.
The @code{obstack_vprintf} function is the equivalent of
@code{obstack_printf} with the variable argument list specified directly
as for @code{vprintf}.@refill
@@ -2639,6 +2785,7 @@ file @file{printf.h}.
@comment printf.h
@comment GNU
@deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{}}
This function returns information about the number and types of
arguments expected by the @code{printf} template string @var{template}.
The information is stored in the array @var{argtypes}; each element of
@@ -2879,6 +3026,12 @@ The function to register a new output conversion is
@comment printf.h
@comment GNU
@deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
+@safety{@mtunsafe{unguarded-uses, printfext}@asunsafe{deadlock}@acunsafe{memleak, lockleak}}
+@c This function is guarded by the global non-recursive libc lock, but
+@c users of the variables it sets aren't, and those should be MT-Safe,
+@c so we're ruling out the use of this extension with threads. Calling
+@c it from a signal handler may self-deadlock, and cancellation may
+@c leave the lock held, besides leaking allocated memory.
This function defines the conversion specifier character @var{spec}.
Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
You can redefine the built-in conversions like @samp{%s}, but flag
@@ -3125,6 +3278,12 @@ which implement a special way to print floating-point numbers.
@comment printf.h
@comment GNU
@deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
+@safety{@mtunsafe{nolock, glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, badstream}}
+@c This is meant to be called by vfprintf, that should hold the lock on
+@c the stream, but if this function is called directly, output will be
+@c racy, besides the uses of the global locale object while other
+@c threads may be changing it and the possbility of leaving the stream
+@c object in an inconsistent state in case of cancellation.
Print a given floating point number as for the format @code{%f} except
that there is a postfix character indicating the divisor for the
number to make this less than 1000. There are two possible divisors:
@@ -3183,6 +3342,7 @@ provide the function which returns information about the arguments.
@comment printf.h
@comment GNU
@deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
This function will return in @var{argtypes} the information about the
used parameters in the way the @code{vfprintf} implementation expects
it. The format always takes one argument.
@@ -3799,6 +3959,7 @@ Prototypes for these functions are in the header file @file{stdio.h}.
@comment stdio.h
@comment ISO
@deftypefun int scanf (const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
The @code{scanf} function reads formatted input from the stream
@code{stdin} under the control of the template string @var{template}.
The optional arguments are pointers to the places which receive the
@@ -3813,6 +3974,7 @@ template, then @code{EOF} is returned.
@comment wchar.h
@comment ISO
@deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
The @code{wscanf} function reads formatted input from the stream
@code{stdin} under the control of the template string @var{template}.
The optional arguments are pointers to the places which receive the
@@ -3827,6 +3989,7 @@ template, then @code{WEOF} is returned.
@comment stdio.h
@comment ISO
@deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is just like @code{scanf}, except that the input is read
from the stream @var{stream} instead of @code{stdin}.
@end deftypefun
@@ -3834,6 +3997,7 @@ from the stream @var{stream} instead of @code{stdin}.
@comment wchar.h
@comment ISO
@deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is just like @code{wscanf}, except that the input is read
from the stream @var{stream} instead of @code{stdin}.
@end deftypefun
@@ -3841,6 +4005,7 @@ from the stream @var{stream} instead of @code{stdin}.
@comment stdio.h
@comment ISO
@deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is like @code{scanf}, except that the characters are taken from the
null-terminated string @var{s} instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
@@ -3854,6 +4019,7 @@ as an argument to receive a string read under control of the @samp{%s},
@comment wchar.h
@comment ISO
@deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is like @code{wscanf}, except that the characters are taken from the
null-terminated string @var{ws} instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
@@ -3880,6 +4046,7 @@ introduced in @w{ISO C99} and were before available as GNU extensions.
@comment stdio.h
@comment ISO
@deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is similar to @code{scanf}, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@@ -3888,6 +4055,7 @@ pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@comment wchar.h
@comment ISO
@deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This function is similar to @code{wscanf}, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@@ -3896,6 +4064,7 @@ pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@comment stdio.h
@comment ISO
@deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This is the equivalent of @code{fscanf} with the variable argument list
specified directly as for @code{vscanf}.
@end deftypefun
@@ -3903,6 +4072,7 @@ specified directly as for @code{vscanf}.
@comment wchar.h
@comment ISO
@deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{badstream, glocale-revisit}@acunsafe{memleak, lockleak, badstream}}
This is the equivalent of @code{fwscanf} with the variable argument list
specified directly as for @code{vwscanf}.
@end deftypefun
@@ -3910,6 +4080,7 @@ specified directly as for @code{vwscanf}.
@comment stdio.h
@comment ISO
@deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is the equivalent of @code{sscanf} with the variable argument list
specified directly as for @code{vscanf}.
@end deftypefun
@@ -3917,6 +4088,7 @@ specified directly as for @code{vscanf}.
@comment wchar.h
@comment ISO
@deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@mtunsafe{glocale-revisit}@asunsafe{glocale-revisit}@acsafe{memleak}}
This is the equivalent of @code{swscanf} with the variable argument list
specified directly as for @code{vwscanf}.
@end deftypefun
@@ -3966,6 +4138,7 @@ This symbol is declared in @file{wchar.h}.
@comment stdio.h
@comment ISO
@deftypefun int feof (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak}}
The @code{feof} function returns nonzero if and only if the end-of-file
indicator for the stream @var{stream} is set.
@@ -3975,6 +4148,9 @@ This symbol is declared in @file{stdio.h}.
@comment stdio.h
@comment GNU
@deftypefun int feof_unlocked (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
+@c There isn't much of a thread unsafety risk in reading a flag word and
+@c testing a bit in it.
The @code{feof_unlocked} function is equivalent to the @code{feof}
function except that it does not implicitly lock the stream.
@@ -3986,6 +4162,7 @@ This symbol is declared in @file{stdio.h}.
@comment stdio.h
@comment ISO
@deftypefun int ferror (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak}}
The @code{ferror} function returns nonzero if and only if the error
indicator for the stream @var{stream} is set, indicating that an error
has occurred on a previous operation on the stream.
@@ -3996,6 +4173,7 @@ This symbol is declared in @file{stdio.h}.
@comment stdio.h
@comment GNU
@deftypefun int ferror_unlocked (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{ferror_unlocked} function is equivalent to the @code{ferror}
function except that it does not implicitly lock the stream.
@@ -4023,6 +4201,7 @@ function.
@comment stdio.h
@comment ISO
@deftypefun void clearerr (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak}}
This function clears the end-of-file and error indicators for the
stream @var{stream}.
@@ -4033,6 +4212,7 @@ end-of-file indicator for the stream.
@comment stdio.h
@comment GNU
@deftypefun void clearerr_unlocked (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@assafe{}@acunsafe{lockleak}}
The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
function except that it does not implicitly lock the stream.
@@ -4146,6 +4326,7 @@ are declared in the header file @file{stdio.h}.
@comment stdio.h
@comment ISO
@deftypefun {long int} ftell (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function returns the current file position of the stream
@var{stream}.
@@ -4158,6 +4339,7 @@ possibly for other reasons as well. If a failure occurs, a value of
@comment stdio.h
@comment Unix98
@deftypefun off_t ftello (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{ftello} function is similar to @code{ftell}, except that it
returns a value of type @code{off_t}. Systems which support this type
use it to describe all file positions, unlike the POSIX specification
@@ -4181,6 +4363,7 @@ LFS interface transparently replaces the old interface.
@comment stdio.h
@comment Unix98
@deftypefun off64_t ftello64 (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function is similar to @code{ftello} with the only difference that
the return value is of type @code{off64_t}. This also requires that the
stream @var{stream} was opened using either @code{fopen64},
@@ -4196,6 +4379,7 @@ and so transparently replaces the old interface.
@comment stdio.h
@comment ISO
@deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{fseek} function is used to change the file position of the
stream @var{stream}. The value of @var{whence} must be one of the
constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
@@ -4215,6 +4399,7 @@ place in the file.
@comment stdio.h
@comment Unix98
@deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function is similar to @code{fseek} but it corrects a problem with
@code{fseek} in a system with POSIX types. Using a value of type
@code{long int} for the offset is not compatible with POSIX.
@@ -4238,6 +4423,7 @@ LFS interface transparently replaces the old interface.
@comment stdio.h
@comment Unix98
@deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function is similar to @code{fseeko} with the only difference that
the @var{offset} parameter is of type @code{off64_t}. This also
requires that the stream @var{stream} was opened using either
@@ -4286,6 +4472,7 @@ the offset provided is relative to the end of the file.
@comment stdio.h
@comment ISO
@deftypefun void rewind (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{rewind} function positions the stream @var{stream} at the
beginning of the file. It is equivalent to calling @code{fseek} or
@code{fseeko} on the @var{stream} with an @var{offset} argument of
@@ -4407,6 +4594,7 @@ representation.
@comment stdio.h
@comment ISO
@deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function stores the value of the file position indicator for the
stream @var{stream} in the @code{fpos_t} object pointed to by
@var{position}. If successful, @code{fgetpos} returns zero; otherwise
@@ -4421,6 +4609,7 @@ interface transparently replaces the old interface.
@comment stdio.h
@comment Unix98
@deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function is similar to @code{fgetpos} but the file position is
returned in a variable of type @code{fpos64_t} to which @var{position}
points.
@@ -4433,6 +4622,7 @@ and so transparently replaces the old interface.
@comment stdio.h
@comment ISO
@deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function sets the file position indicator for the stream @var{stream}
to the position @var{position}, which must have been set by a previous
call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
@@ -4449,6 +4639,7 @@ interface transparently replaces the old interface.
@comment stdio.h
@comment Unix98
@deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function is similar to @code{fsetpos} but the file position used
for positioning is provided in a variable of type @code{fpos64_t} to
which @var{position} points.
@@ -4560,6 +4751,7 @@ If you want to flush the buffered output at another time, call
@comment stdio.h
@comment ISO
@deftypefun int fflush (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function causes any buffered output on @var{stream} to be delivered
to the file. If @var{stream} is a null pointer, then
@code{fflush} causes buffered output on @emph{all} open output streams
@@ -4572,6 +4764,7 @@ otherwise.
@comment stdio.h
@comment POSIX
@deftypefun int fflush_unlocked (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{fflush_unlocked} function is equivalent to the @code{fflush}
function except that it does not implicitly lock the stream.
@end deftypefun
@@ -4588,6 +4781,7 @@ exported.
@comment stdio_ext.h
@comment GNU
@deftypefun void _flushlbf (void)
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
The @code{_flushlbf} function flushes all line buffered streams
currently opened.
@@ -4609,6 +4803,7 @@ situation a non-standard function introduced in Solaris and available in
@comment stdio_ext.h
@comment GNU
@deftypefun void __fpurge (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@asunsafe{badstream}@acunsafe{badstream}}
The @code{__fpurge} function causes the buffer of the stream
@var{stream} to be emptied. If the stream is currently in read mode all
input in the buffer is lost. If the stream is in output mode the
@@ -4633,6 +4828,7 @@ file @file{stdio.h}.
@comment stdio.h
@comment ISO
@deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function is used to specify that the stream @var{stream} should
have the buffering mode @var{mode}, which can be either @code{_IOFBF}
(for full buffering), @code{_IOLBF} (for line buffering), or
@@ -4710,6 +4906,7 @@ efficient size.
@comment stdio.h
@comment ISO
@deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
If @var{buf} is a null pointer, the effect of this function is
equivalent to calling @code{setvbuf} with a @var{mode} argument of
@code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf}
@@ -4723,6 +4920,7 @@ use @code{setvbuf} in all new programs.
@comment stdio.h
@comment BSD
@deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
buffer. The @var{size} argument specifies the length of @var{buf}.
@@ -4734,6 +4932,7 @@ This function is provided for compatibility with old BSD code. Use
@comment stdio.h
@comment BSD
@deftypefun void setlinebuf (FILE *@var{stream})
+@safety{@mtsafe{}@asunsafe{badstream}@acunsafe{lockleak, badstream}}
This function makes @var{stream} be line buffered, and allocates the
buffer for you.
@@ -4748,6 +4947,7 @@ using a non-standard function introduced in Solaris and available in
@comment stdio_ext.h
@comment GNU
@deftypefun int __flbf (FILE *@var{stream})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
The @code{__flbf} function will return a nonzero value in case the
stream @var{stream} is line buffered. Otherwise the return value is
zero.
@@ -4761,6 +4961,7 @@ much of it is used. These functions were also introduced in Solaris.
@comment stdio_ext.h
@comment GNU
@deftypefun size_t __fbufsize (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@assafe{badstream}@acsafe{}}
The @code{__fbufsize} function return the size of the buffer in the
stream @var{stream}. This value can be used to optimize the use of the
stream.
@@ -4771,6 +4972,7 @@ This function is declared in the @file{stdio_ext.h} header.
@comment stdio_ext.h
@comment GNU
@deftypefun size_t __fpending (FILE *@var{stream})
+@safety{@mtunsafe{nolock}@assafe{badstream}@acsafe{}}
The @code{__fpending}
function returns the number of bytes currently in the output buffer.
For wide-oriented stream the measuring unit is wide characters. This
@@ -4818,6 +5020,7 @@ I/O to a string or memory buffer. These facilities are declared in
@comment stdio.h
@comment GNU
@deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
+@safety{@mtsafe{}@assafe{}@acsafe{memleak}}
This function opens a stream that allows the access specified by the
@var{opentype} argument, that reads from or writes to the buffer specified
by the argument @var{buf}. This array must be at least @var{size} bytes long.
@@ -4870,6 +5073,7 @@ Got r
@comment stdio.h
@comment GNU
@deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
+@safety{@mtsafe{}@assafe{}@acsafe{memleak}}
This function opens a stream for writing to a buffer. The buffer is
allocated dynamically and grown as necessary, using @code{malloc}.
After you've closed the stream, this buffer is your responsibility to
@@ -4985,6 +5189,7 @@ closed.
@comment stdio.h
@comment GNU
@deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
+@safety{@mtsafe{}@assafe{}@acunsafe{memleak, lockleak}}
This function actually creates the stream for communicating with the
@var{cookie} using the functions in the @var{io-functions} argument.
The @var{opentype} argument is interpreted as for @code{fopen};
@@ -5166,6 +5371,7 @@ It is a non-recoverable error.
@comment fmtmsg.h
@comment XPG
@deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag})
+@safety{@mtsafe{}@asunsafe{deadlock}@acsafe{}}
Display a message described by its parameters on the device(s) specified
in the @var{classification} parameter. The @var{label} parameter
identifies the source of the message. The string should consist of two
@@ -5306,6 +5512,7 @@ introducing new classes in a running program. One could use the
but this is toilsome.
@deftypefun int addseverity (int @var{severity}, const char *@var{string})
+@safety{@mtsafe{}@asunsafe{deadlock}@acunsafe{lockleak, memleak}}
This function allows the introduction of new severity classes which can be
addressed by the @var{severity} parameter of the @code{fmtmsg} function.
The @var{severity} parameter of @code{addseverity} must match the value
Thread safety documentation.
From: Alexandre Oliva <aoliva@redhat.com>
for ChangeLog
* manual/locale.texi: Document thread safety properties.
---
manual/locale.texi | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/manual/locale.texi b/manual/locale.texi
index 2f10fcd..8390bbd 100644
--- a/manual/locale.texi
+++ b/manual/locale.texi
@@ -224,6 +224,10 @@ The symbols in this section are defined in the header file @file{locale.h}.
@comment locale.h
@comment ISO
@deftypefun {char *} setlocale (int @var{category}, const char *@var{locale})
+@safety{@mtunsafe{unguarded-uses, glocale}}
+@c This function is MT-Safe, but uses of the global locale object are
+@c unguarded in functions that ought to be MT-Safe, so we're ruling out
+@c the use of this function once threads are started.
The function @code{setlocale} sets the current locale for category
@var{category} to @var{locale}. A list of all the locales the system
provides can be created by running
Thread safety documentation.
From: Alexandre Oliva <aoliva@redhat.com>
for ChangeLog
* manual/math.texi: Document thread safety properties.
---
manual/math.texi | 1 +
1 file changed, 1 insertion(+)
diff --git a/manual/math.texi b/manual/math.texi
index 193d415..fd5d0c8 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -560,6 +560,7 @@ negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero,
@comment math.h
@comment ISO
@deftypefunx int ilogbl (long double @var{x})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
These functions are equivalent to the corresponding @code{logb}
functions except that they return signed integer values.
@end deftypefun
--
Alexandre Oliva, freedom fighter http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/ FSF Latin America board member
Free Software Evangelist Red Hat Brazil Compiler Engineer