diff options
Diffstat (limited to 'manual')
43 files changed, 2220 insertions, 398 deletions
diff --git a/manual/README.pretty-printers b/manual/README.pretty-printers index a696406..c8824c4 100644 --- a/manual/README.pretty-printers +++ b/manual/README.pretty-printers @@ -14,7 +14,6 @@ $1 = { __nusers = 0, __kind = 576, __spins = 0, - __elision = 0, __list = { __prev = 0x0, __next = 0x0 diff --git a/manual/arith.texi b/manual/arith.texi index 034d9d2..a344153 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -1233,25 +1233,33 @@ whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt @pindex math.h @pindex stdlib.h -Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h}; -@code{imaxabs} is declared in @file{inttypes.h}; +Prototypes for @code{abs}, @code{labs}, @code{llabs}, +@code{uabs}, @code{ulabs} and @code{ullabs} are in @file{stdlib.h}; +@code{imaxabs} and @code{umaxabs} are declared in @file{inttypes.h}; the @code{fabs} functions are declared in @file{math.h}; the @code{cabs} functions are declared in @file{complex.h}. @deftypefun int abs (int @var{number}) @deftypefunx {long int} labs (long int @var{number}) @deftypefunx {long long int} llabs (long long int @var{number}) +@deftypefunx {unsigned int} uabs (int @var{number}) +@deftypefunx {unsigned long int} ulabs (long int @var{number}) +@deftypefunx {unsigned long long int} ullabs (long long int @var{number}) @deftypefunx intmax_t imaxabs (intmax_t @var{number}) +@deftypefunx uintmax_t umaxabs (intmax_t @var{number}) @standards{ISO, stdlib.h} @standardsx{imaxabs, ISO, inttypes.h} +@standardsx{umaxabs, ISO, inttypes.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the absolute value of @var{number}. Most computers use a two's complement integer representation, in which the absolute value of @code{INT_MIN} (the smallest possible @code{int}) cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined. +Using @code{uabs} avoids this. @code{llabs} and @code{imaxdiv} are new to @w{ISO C99}. +@code{uabs}, @code{ulabs}, @code{ullabs} and @code{umaxabs} are new to @w{ISO C2Y}. See @ref{Integers} for a description of the @code{intmax_t} type. @@ -1600,26 +1608,26 @@ These functions are just like @code{round}, but they return a @code{long long int} instead of a floating-point number. @end deftypefun -@deftypefun intmax_t fromfp (double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpf (float @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpl (long double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfp (double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpf (float @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpl (long double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpx (double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpxf (float @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpxfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx intmax_t fromfpxfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpx (double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpxf (float @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpxfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) -@deftypefunx uintmax_t ufromfpxfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefun double fromfp (double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx float fromfpf (float @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx {long double} fromfpl (long double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatN fromfpfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatNx fromfpfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx double ufromfp (double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx float ufromfpf (float @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx {long double} ufromfpl (long double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatN ufromfpfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatNx ufromfpfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx double fromfpx (double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx float fromfpxf (float @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx {long double} fromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatN fromfpxfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatNx fromfpxfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx double ufromfpx (double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx float ufromfpxf (float @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx {long double} ufromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatN ufromfpxfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width}) +@deftypefunx _FloatNx ufromfpxfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width}) @standards{ISO, math.h} @standardsx{fromfpfN, TS 18661-3:2015, math.h} @standardsx{fromfpfNx, TS 18661-3:2015, math.h} @@ -1630,17 +1638,22 @@ These functions are just like @code{round}, but they return a @standardsx{ufromfpxfN, TS 18661-3:2015, math.h} @standardsx{ufromfpxfNx, TS 18661-3:2015, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + These functions, from TS 18661-1:2014 and TS 18661-3:2015, convert a -floating-point number to an integer according to the rounding direction -@var{round} (one of the @code{FP_INT_*} macros). If the integer is -outside the range of a signed or unsigned (depending on the return type -of the function) type of width @var{width} bits (or outside the range of -the return type, if @var{width} is larger), or if @var{x} is infinite or -NaN, or if @var{width} is zero, a domain error occurs and an unspecified -value is returned. The functions with an @samp{x} in their names raise -the inexact exception when a domain error does not occur and the -argument is not an integer; the other functions do not raise the inexact -exception. +floating-point number to an integer according to the rounding +direction @var{round} (one of the @code{FP_INT_*} macros). If the +integer is outside the range of a two's complement signed or unsigned +(depending on the return type of the function) integer of width +@var{width} bits, or if @var{x} is infinite or NaN, or if @var{width} +is zero, a domain error occurs and a NaN is returned. The functions +with an @samp{x} in their names raise the inexact exception when a +domain error does not occur and the argument is not an integer; the +other functions do not raise the inexact exception. + +Following ISO C23, in @theglibc{} these functions return their result +in the floating-point argument type. In TS 18661-1:2014 and TS +18661-3:2015, they were originally defined to return @code{intmax_t} +and @code{uintmax_t}. @end deftypefun diff --git a/manual/contrib.texi b/manual/contrib.texi index 3d1b170..30681fa 100644 --- a/manual/contrib.texi +++ b/manual/contrib.texi @@ -22,10 +22,13 @@ Rogerio Alves Cardoso for various fixes to PowerPC. Amrita H. S. for contributions to the PowerPC port. @item -John David Anglin for various fixes and co-maintainership of the HPPA +John David Anglin for many fixes and co-maintainership of the HPPA port. @item +H. Peter Anvin for work on the termios code. + +@item Albert ARIBAUD for Y2038 related fixes. @item @@ -139,14 +142,15 @@ Joana Cruz for contributions to the AArch64 port. Palmer Dabbelt for contributing the port to Linux/RISC-V. @item -DJ Delorie for maintenance of Linux/RISC-V, and numerous fixes. +DJ Delorie for maintenance of Linux/RISC-V, numerous fixes, and handbook +contributions. @item Jianbo Deng for the work on the Loongson port. @item -Wilco Dijkstra for various fixes and many improvements of the AArch64 -port. +Wilco Dijkstra for various fixes and many improvements as well as +maintainership of the AArch64 port. @item Liubov Dmitrieva for optimized string and math functions on x86-64 and @@ -206,6 +210,9 @@ Olaf Flebbe and Ralf B@"achle for contributing @file{sysdeps/mips/fpu_control.h}. @item +Dylan Fleming for work on the AArch64 port. + +@item Alistair Francis for Y2038 related fixes. @item @@ -213,6 +220,9 @@ Mike Frysinger for his maintaining of the IA64 architecture and for testing and bug fixing. @item +Collin Funk for various fixes and manual improvements. + +@item Martin Galvan for contributing gdb pretty printer support to glibc and adding an initial set of pretty printers for structures in the POSIX Threads library. @@ -309,6 +319,9 @@ his direction as part of @theglibc{} steering committee. Simon Josefsson for the @code{libidn} add-on. @item +Ben Kallus for various fixes. + +@item Geoffrey Keating for the port to Linux on PowerPC (@code{powerpc-@var{anything}-linux}). @@ -322,7 +335,8 @@ Mark Kettenis for implementing the @code{utmpx} interface and a utmp daemon, and for a Hesiod NSS module. @item -Yury Khrustalev for work on the AArch64 port and various fixes. +Yury Khrustalev for extensive work on the AArch64 port and its +maintainership, and various fixes. @item Simon Kissane for gmon improvements. @@ -353,7 +367,7 @@ for NSS (@file{nscd}). Akhilesh Kumar for various fixes to locales. @item -Luna Lamb for contributions to the AArch64 port. +Luna Lamb for various contributions to the AArch64 port. @item Jeff Law for various fixes. @@ -384,6 +398,9 @@ implementations, for implementing Intel Control-Flow Enforcement Technology, many x86-64 improvements, and many bug fixes. @item +Zhaoming Luo for work on the hurd port. + +@item Rafa@l{} Lu@dotaccent{z}y@'nski for contributing support for two grammatical forms of month names, and for various fixes to locales. @@ -449,6 +466,9 @@ Cupertino Miranda for various fixes. Alan Modra for his improvements for Linux on PowerPC. @item +Lenard Mollenkopf for work on C2Y support. + +@item Sachin Monga for various fixes and contributions to the PowerPC port. @item @@ -496,7 +516,7 @@ encryption support for ARM and various fixes. @item Carlos O'Donell for his maintainership of the HPPA architecture, for maintaining @theglibc{} web pages and wiki, for his direction as FSF -Project Steward for @theglibc{} and various bug fixes. +Project Steward for @theglibc{} and numerous bug fixes. @item Alexandre Oliva for adding TLS descriptors for LD and GD on x86 and @@ -506,7 +526,7 @@ safety documentation in the manual, for his direction as FSF Project Maintainer and for various fixes. @item -Sunil K. Pandey for many fixes. +Sunil K. Pandey for many fixes and x86-64 improvements. @item Ronan Pigott for various fixes. @@ -525,8 +545,8 @@ Yat Long Poon for contributions to the Aarch64 port. @item Siddhesh Poyarekar for various fixes, an implementation of a framework for -performance benchmarking of functions and implementing the tunables -infrastructure. +performance benchmarking of functions, implementing the tunables +infrastructure, and handbook improvements. @item Tom Quinn for contributing the startup code to support SunOS shared @@ -587,7 +607,7 @@ Andrew Senkevich for contributing vector math function implementations for x86. Carlos Eduardo Seo for optimized functions on PowerPC. @item -Arjun Shankar for testing, bug fixing, and handbook contributions. +Arjun Shankar for testing, bug fixing, and many handbook contributions. @item Marcus Shawcroft for contributing the AArch64 port. @@ -658,8 +678,9 @@ function family. Ulrich Weigand for various fixes to the PowerPC64 and Arm ports. @item -Florian Weimer for his maintainership of the network component, for handling -of security issues, and for numerous fixes and contributions. +Florian Weimer for his maintainership of the network and dynamic-link +components, for handling of security issues, and for numerous fixes and +contributions. @item Zack Weinberg for the @code{explicit_bzero} implementation and for various @@ -686,7 +707,8 @@ YunQiang Su for work on the MIPS port. @item Adhemerval Zanella for optimized functions on PowerPC, ISO C threads support, the work on tunables, fortify improvements, the CORE-MATH integration, -thread safety, and numerous further contributions and fixes. +thread safety, handling of security issues, and numerous further contributions +and fixes. @item Xuelei Zhang for optimized functions on AArch64. @@ -698,6 +720,9 @@ Junxian Zhu for work on the MIPS and RISC-V port. Paul Zimmermann for the work on mathematical functions and their testsuite. +@item +Claudiu Zissulescu for work on the SFrame support. + @end itemize Some code in @theglibc{} comes from other projects and might be under diff --git a/manual/creature.texi b/manual/creature.texi index 09e1c96..90f9f8e 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -73,6 +73,10 @@ If you define this macro to a value greater than or equal to @code{200809L}, then the functionality from the 2008 edition of the POSIX standard (IEEE Standard 1003.1-2008) is made available. +If you define this macro to a value greater than or equal to +@code{202405L}, then the functionality from the 2024 edition of the +POSIX standard (IEEE Standard 1003.1-2024) is made available. + Greater values for @code{_POSIX_C_SOURCE} will enable future extensions. The POSIX standards process will define these values as necessary, and @theglibc{} should support them some time after they become standardized. @@ -104,7 +108,7 @@ all functionality described so far plus some new definitions from the Single Unix Specification, @w{version 2}. The value @math{600} (corresponding to the sixth revision) includes definitions from SUSv3, and using @math{700} (the seventh revision) includes definitions from -SUSv4. +SUSv4. The value @math{800} includes definitions from POSIX.1-2024. @end defvr @defvr Macro _LARGEFILE_SOURCE @@ -194,9 +198,9 @@ a fallback code is used with legacy (i.e. 32-bit) syscalls. On such platforms, @theglibc{} will also define @code{__USE_TIME64_REDIRECTS} to indicate whether the declarations are expanded to different ones -(either by redefiniding the symbol name or using symbol aliais). +(either by redefining the symbol name or using a symbol alias). For instance, if the symbol @code{clock_gettime} expands to -@code{__glock_gettime64}. +@code{__clock_gettime64}. @item If @code{_TIME_BITS} is defined to be 32, @code{time_t} is defined to diff --git a/manual/dynlink.texi b/manual/dynlink.texi index 3a4864f..a78a065 100644 --- a/manual/dynlink.texi +++ b/manual/dynlink.texi @@ -14,6 +14,8 @@ Dynamic linkers are sometimes called @dfn{dynamic loaders}. @menu * Dynamic Linker Invocation:: Explicit invocation of the dynamic linker. +* Dynamic Linker Environment Variables:: Environment variables that control the + dynamic linker. * Dynamic Linker Introspection:: Interfaces for querying mapping information. * Dynamic Linker Hardening:: Avoiding unexpected issues with dynamic linking. @end menu @@ -270,7 +272,7 @@ These are additional items for the i386 and x86-64 architectures, as described below. They mostly contain raw data from the CPUID instruction. The probes are performed for each active CPU for the @code{ld.so} process, and data for different probed CPUs receives a -uniqe @var{index} value. Some CPUID data is expected to differ from CPU +unique @var{index} value. Some CPUID data is expected to differ from CPU core to CPU core. In some cases, CPUs are not correctly initialized and indicate the presence of different feature sets. @@ -335,7 +337,7 @@ and @var{ecx_limit} (inclusive). @item x86.processor[@var{index}].cpuid.subleaf_eax[@var{query_eax}].ecx[@var{query_ecx}].ecx_query_mask=0xff This line indicates that in an @samp{.until_ecx} range, the CPUID -instruction preserved the lowested 8 bits of the input @code{%rcx} in +instruction preserved the lowest 8 bits of the input @code{%rcx} in the output @code{%rcx} registers. Otherwise, the subleaves in the range have identical values. This special treatment is necessary to report compact range information in case such copying occurs (because the @@ -349,6 +351,70 @@ probed CPU are omitted. Nothing is printed if the system does not support the XGETBV instruction. @end table +@node Dynamic Linker Environment Variables +@section Dynamic Linker Environment Variables + +The behavior of the dynamic linker can be modified through various environment +variables. + +@table @code +@item LD_DEBUG +@cindex @code{LD_DEBUG} environment variable +The @env{LD_DEBUG} environment variable can be set to a comma-separated list +of keywords to enable debugging output from the dynamic linker. Setting it to +@code{help} will display a list of all available keywords. The output is +written to standard output by default. + +@table @code +@item libs +Display library search paths. + +@item reloc +Display relocation processing. + +@item files +Display progress for input file processing. + +@item symbols +Display symbol table processing. + +@item bindings +Display information about symbol binding. + +@item versions +Display version dependencies. + +@item scopes +Display scope information. + +@item tls +Display information about Thread-Local Storage (TLS) handling, including TCB +allocation, deallocation, and reuse. This is useful for debugging issues +related to thread creation and lifecycle. + +@item all +All previous options combined. + +@item statistics +Display relocation statistics. + +@item unused +Determined unused DSOs. + +@item help +Display a help message with all available options and exit. +@end table + +@item LD_DEBUG_OUTPUT +@cindex @code{LD_DEBUG_OUTPUT} environment variable +If @env{LD_DEBUG} is set, the output is written to standard output by +default. If @env{LD_DEBUG_OUTPUT} is set, the output is written to the +file specified by its value, with the process ID appended. For example, if +@env{LD_DEBUG_OUTPUT} is set to @file{/tmp/glibc.debug}, the output will be +written to a file named @file{/tmp/glibc.debug.12345}, where @code{12345} is +the process ID. +@end table + @node Dynamic Linker Introspection @section Dynamic Linker Introspection @@ -545,7 +611,8 @@ result data to the caller. @table @code @item unsigned long long int dlfo_flags -Currently unused and always 0. +Bit zero signals if SFrame stack data is valid. See +@code{DLFO_FLAG_SFRAME} below. @item void *dlfo_map_start The start address of the inspected mapping. This information comes from @@ -562,6 +629,11 @@ This member contains a pointer to the link map of the object. This member contains a pointer to the exception handling data of the object. See @code{DLFO_EH_SEGMENT_TYPE} below. +@item void *dlfo_sframe +This member points to the SFrame stack trace data associated with the +object. It is valid only when @code{DLFO_FLAG_SFRAME} is set in +@code{dlfo_flags}; otherwise, it may be null or undefined. + @end table This structure is a GNU extension. @@ -639,6 +711,15 @@ information is processed. This function is a GNU extension. @end deftypefun +The following flag masks are defined for use with @code{dlfo_flags}: + +@table @code +@item DLFO_FLAG_SFRAME +A bit mask used to signal that the object contains SFrame data. See +@code{dlfo_sframe} above. + +@end table + @node Dynamic Linker Hardening @section Avoiding Unexpected Issues With Dynamic Linking @@ -1135,7 +1216,7 @@ If the dynamic segment contains a (deprecated) @code{HASH} tag, it must also contain a @code{GNU_HASH} tag. @item -The @code{INITFIRST} flag (undeer @code{FLAGS_1}) should not be used. +The @code{INITFIRST} flag (under @code{FLAGS_1}) should not be used. @item The program header must not have @code{LOAD} segments that are writable diff --git a/manual/errno.texi b/manual/errno.texi index bb8a6cb..84a142c 100644 --- a/manual/errno.texi +++ b/manual/errno.texi @@ -1476,6 +1476,7 @@ As mentioned above, the @code{error} and @code{error_at_line} functions can be customized by defining a variable named @code{error_print_progname}. +@vindex error_print_progname @deftypevar {void (*error_print_progname)} (void) @standards{GNU, error.h} If the @code{error_print_progname} variable is defined to a non-zero diff --git a/manual/examples/db.c b/manual/examples/db.c index 7befca7..5ded1ea 100644 --- a/manual/examples/db.c +++ b/manual/examples/db.c @@ -20,6 +20,7 @@ #include <sys/types.h> #include <unistd.h> #include <stdlib.h> +#include <stdio.h> int main (void) diff --git a/manual/examples/filesrv.c b/manual/examples/filesrv.c index 09c80c5..9b39350 100644 --- a/manual/examples/filesrv.c +++ b/manual/examples/filesrv.c @@ -20,6 +20,7 @@ #include <stdlib.h> #include <sys/socket.h> #include <sys/un.h> +#include <unistd.h> #define SERVER "/tmp/serversocket" #define MAXMSG 512 @@ -30,7 +31,7 @@ main (void) int sock; char message[MAXMSG]; struct sockaddr_un name; - size_t size; + socklen_t size; int nbytes; /* Remove the filename first, it's ok if the call fails */ diff --git a/manual/examples/inetcli.c b/manual/examples/inetcli.c index 657dcdb..8908341 100644 --- a/manual/examples/inetcli.c +++ b/manual/examples/inetcli.c @@ -18,6 +18,7 @@ #include <stdio.h> #include <errno.h> #include <stdlib.h> +#include <string.h> #include <unistd.h> #include <sys/types.h> #include <sys/socket.h> diff --git a/manual/examples/inetsrv.c b/manual/examples/inetsrv.c index 003a951..b854fe6 100644 --- a/manual/examples/inetsrv.c +++ b/manual/examples/inetsrv.c @@ -15,6 +15,7 @@ along with this program; if not, see <https://www.gnu.org/licenses/>. */ +#include <arpa/inet.h> #include <stdio.h> #include <errno.h> #include <stdlib.h> @@ -59,7 +60,7 @@ main (void) fd_set active_fd_set, read_fd_set; int i; struct sockaddr_in clientname; - size_t size; + socklen_t size; /* Create the socket and set it up to accept connections. */ sock = make_socket (PORT); diff --git a/manual/examples/mbstouwcs.c b/manual/examples/mbstouwcs.c index c94e1fa..c492f37 100644 --- a/manual/examples/mbstouwcs.c +++ b/manual/examples/mbstouwcs.c @@ -1,7 +1,9 @@ +#include <errno.h> #include <stdbool.h> #include <stdlib.h> #include <string.h> #include <wchar.h> +#include <wctype.h> /* Do not include the above headers in the example. */ diff --git a/manual/examples/memopen.c b/manual/examples/memopen.c index e87006d..8ef34fc 100644 --- a/manual/examples/memopen.c +++ b/manual/examples/memopen.c @@ -16,6 +16,7 @@ */ #include <stdio.h> +#include <string.h> static char buffer[] = "foobar"; diff --git a/manual/examples/memstrm.c b/manual/examples/memstrm.c index 9ee6298..28be892 100644 --- a/manual/examples/memstrm.c +++ b/manual/examples/memstrm.c @@ -16,6 +16,7 @@ */ #include <stdio.h> +#include <stdlib.h> int main (void) @@ -31,6 +32,7 @@ main (void) fprintf (stream, ", world"); fclose (stream); printf ("buf = `%s', size = %zu\n", bp, size); + free (bp); return 0; } diff --git a/manual/examples/select.c b/manual/examples/select.c index 1398c7f..db138c3 100644 --- a/manual/examples/select.c +++ b/manual/examples/select.c @@ -16,11 +16,12 @@ */ /*@group*/ +#define _GNU_SOURCE 1 #include <errno.h> #include <stdio.h> #include <unistd.h> #include <sys/types.h> -#include <sys/time.h> +#include <sys/select.h> /*@end group*/ /*@group*/ diff --git a/manual/examples/setjmp.c b/manual/examples/setjmp.c index 95e328d..3c7d979 100644 --- a/manual/examples/setjmp.c +++ b/manual/examples/setjmp.c @@ -27,17 +27,6 @@ abort_to_main_loop (int status) longjmp (main_loop, status); } -int -main (void) -{ - while (1) - if (setjmp (main_loop)) - puts ("Back at main loop...."); - else - do_command (); -} - - void do_command (void) { @@ -47,3 +36,13 @@ do_command (void) else exit (EXIT_SUCCESS); } + +int +main (void) +{ + while (1) + if (setjmp (main_loop)) + puts ("Back at main loop...."); + else + do_command (); +} diff --git a/manual/examples/sigh1.c b/manual/examples/sigh1.c index a540651..b770158 100644 --- a/manual/examples/sigh1.c +++ b/manual/examples/sigh1.c @@ -18,6 +18,7 @@ #include <signal.h> #include <stdio.h> #include <stdlib.h> +#include <unistd.h> /* This flag controls termination of the main loop. */ volatile sig_atomic_t keep_going = 1; diff --git a/manual/examples/sigusr.c b/manual/examples/sigusr.c index 13874fd..8f00cd9 100644 --- a/manual/examples/sigusr.c +++ b/manual/examples/sigusr.c @@ -18,6 +18,7 @@ /*@group*/ #include <signal.h> #include <stdio.h> +#include <stdlib.h> #include <sys/types.h> #include <unistd.h> /*@end group*/ diff --git a/manual/examples/strdupa.c b/manual/examples/strdupa.c index 7fd2293..004a3b3 100644 --- a/manual/examples/strdupa.c +++ b/manual/examples/strdupa.c @@ -15,6 +15,7 @@ along with this program; if not, see <https://www.gnu.org/licenses/>. */ +#define _GNU_SOURCE 1 #include <paths.h> #include <string.h> #include <stdio.h> diff --git a/manual/examples/subopt.c b/manual/examples/subopt.c index e7a0730..63b5271 100644 --- a/manual/examples/subopt.c +++ b/manual/examples/subopt.c @@ -61,7 +61,7 @@ main (int argc, char **argv) case 'o': subopts = optarg; while (*subopts != '\0') - switch (getsubopt (&subopts, mount_opts, &value)) + switch (getsubopt (&subopts, (char * const *) mount_opts, &value)) { case RO_OPTION: read_only = 1; diff --git a/manual/examples/twalk.c b/manual/examples/twalk.c index e9aa13d..970096d 100644 --- a/manual/examples/twalk.c +++ b/manual/examples/twalk.c @@ -15,6 +15,7 @@ along with this program; if not, see <https://www.gnu.org/licenses/>. */ +#define _GNU_SOURCE 1 #include <search.h> struct twalk_with_twalk_r_closure diff --git a/manual/filesys.texi b/manual/filesys.texi index aabb683..f49d7d7 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -310,12 +310,17 @@ This is a GNU extension. The flags argument in @code{@dots{}at} functions can be a combination of the following flags, defined in @file{fcntl.h}. Not all such functions support all flags, and some (such as @code{openat}) do not accept a -flags argument at all. - -In the flag descriptions below, the @dfn{effective final path component} -refers to the final component (basename) of the full path constructed -from the descriptor and file name arguments, using file name lookup, as -described above. +flags argument at all. Although the flags specific to each function have +distinct values from each other, some flags (relevant to different +functions) might share the same value and therefore are not guaranteed to +have unique values. + +A non-exhaustive list of common flags and their descriptions follows. Flags +specific to a function are described alongside the function itself. In +these flag descriptions, the @dfn{effective final path component} refers to +the final component (basename) of the full path constructed from the +descriptor and file name arguments, using file name lookup, as described +above. @vtable @code @item AT_EMPTY_PATH @@ -353,6 +358,28 @@ a non-final component of the file name are still followed. argument to the @code{getauxval} function (with @code{AT_@dots{}} constants defined in @file{elf.h}). @xref{Auxiliary Vector}. +@cindex common errors in descriptor-relative functions +@cindex common errors in @code{@dots{}at} functions + +The @code{@dots{}at} functions have some common error conditions due to the +nature of descriptor-relative access. A list of common errors and their +descriptions follows. Errors specific to a function are described alongside +the function itself. + +@table @code +@item EBADF +The file name argument is a relative path but the descriptor argument +is neither @code{AT_FDCWD} nor a valid file descriptor. + +@item EINVAL +If the function accepts a @var{flags} argument, the flag combination passed +is not valid for the function. + +@item ENOTDIR +The file name argument is a relative file name but the descriptor +argument is associated with a file that is not a directory. +@end table + @node Accessing Directories @section Accessing Directories @cindex accessing directories @@ -409,18 +436,41 @@ entries. It contains the following fields: This is the null-terminated file name component. This is the only field you can count on in all POSIX systems. +While this field is defined with a specified length, functions such as +@code{readdir} may return a pointer to a @code{struct dirent} where the +@code{d_name} extends beyond the end of the struct. + @item ino_t d_fileno This is the file serial number. For BSD compatibility, you can also refer to this member as @code{d_ino}. On @gnulinuxhurdsystems{} and most POSIX systems, for most files this the same as the @code{st_ino} member that @code{stat} will return for the file. @xref{File Attributes}. +@item off_t d_off +This value contains the offset of the next directory entry (after this +entry) in the directory stream. The value may not be compatible with +@code{lseek} or @code{seekdir}, especially if the width of @code{d_off} +is less than 64 bits. Directory entries are not ordered by offset, and +the @code{d_off} and @code{d_reclen} values are unrelated. Seeking on +directory streams is not recommended. The symbol +@code{_DIRENT_HAVE_D_OFF} is defined if the @code{d_ino} member is +available. + @item unsigned char d_namlen This is the length of the file name, not including the terminating null character. Its type is @code{unsigned char} because that is the integer type of the appropriate size. This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is -available. +available. (It is not available on Linux.) + +@item unsigned short int d_reclen +This is the length of the entire directory record. When iterating +through a buffer filled by @code{getdents64} (@pxref{Low-level Directory +Access}), this value needs to be added to the offset of the current +directory entry to obtain the offset of the next entry. When using +@code{readdir} and related functions, the value of @code{d_reclen} is +undefined and should not be accessed. The symbol +@code{_DIRENT_HAVE_D_RECLEN} is defined if this member is available. @item unsigned char d_type This is the type of the file, possibly unknown. The following constants @@ -457,7 +507,7 @@ This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_TYPE} is defined if this member is available. On systems where it is used, it corresponds to the file type bits in the @code{st_mode} member of @code{struct stat}. If the value cannot be determined the member -value is DT_UNKNOWN. These two macros convert between @code{d_type} +value is @code{DT_UNKNOWN}. These two macros convert between @code{d_type} values and @code{st_mode} values: @deftypefun int IFTODT (mode_t @var{mode}) @@ -632,6 +682,20 @@ and can be rewritten by a subsequent call. return entries for @file{.} and @file{..}, even though these are always valid file names in any directory. @xref{File Name Resolution}. +If a directory is modified between a call to @code{readdir} and after +the directory stream was created or @code{rewinddir} was last called on +it, it is unspecified according to POSIX whether newly created or +removed entries appear among the entries returned by repeated +@code{readdir} calls before the end of the directory is reached. +However, due to practical implementation constraints, it is possible +that entries (including unrelated, unmodified entries) appear multiple +times or do not appear at all if the directory is modified while listing +it. If the application intends to create files in the directory, it may +be necessary to complete the iteration first and create a copy of the +information obtained before creating any new files. (See below for +instructions regarding copying of @code{d_name}.) The iteration can be +restarted using @code{rewinddir}. @xref{Random Access Directory}. + If there are no more entries in the directory or an error is detected, @code{readdir} returns a null pointer. The following @code{errno} error conditions are defined for this function: @@ -812,6 +876,10 @@ directory since it was opened with @code{opendir}. (Entries for these files might or might not be returned by @code{readdir} if they were added or removed since you last called @code{opendir} or @code{rewinddir}.) + +For example, it is recommended to call @code{rewinddir} followed by +@code{readdir} to check if a directory is empty after listing it with +@code{readdir} and deleting all encountered files from it. @end deftypefun @deftypefun {long int} telldir (DIR *@var{dirstream}) @@ -823,6 +891,13 @@ added or removed since you last called @code{opendir} or The @code{telldir} function returns the file position of the directory stream @var{dirstream}. You can use this value with @code{seekdir} to restore the directory stream to that position. + +Using the the @code{telldir} function is not recommended. + +The value returned by @code{telldir} may not be compatible with the +@code{d_off} field in @code{struct dirent}, and cannot be used with the +@code{lseek} function. The returned value may not unambiguously +identify the position in the directory stream. @end deftypefun @deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos}) @@ -836,6 +911,9 @@ stream @var{dirstream} to @var{pos}. The value @var{pos} must be the result of a previous call to @code{telldir} on this particular stream; closing and reopening the directory can invalidate values returned by @code{telldir}. + +Using the the @code{seekdir} function is not recommended. To seek to +the beginning of the directory stream, use @code{rewinddir}. @end deftypefun @@ -1007,9 +1085,20 @@ Note that some file systems support file names longer than @code{NAME_MAX} bytes (e.g., because they support up to 255 Unicode characters), so a buffer size of at least 1024 is recommended. +If the directory has been modified since the first call to +@code{getdents64} on the directory (opening the descriptor or seeking to +offset zero), it is possible that the buffer contains entries that have +been encountered before. Likewise, it is possible that files that are +still present are not reported before the end of the directory is +encountered (and @code{getdents64} returns zero). + This function is specific to Linux. @end deftypefun +Systems that support @code{getdents64} support seeking on directory +streams. @xref{File Position Primitive}. However, the only offset that +works reliably is offset zero, indicating that reading the directory +should start from the beginning. @node Working with Directory Trees @section Working with Directory Trees @@ -1690,6 +1779,31 @@ file system and can't be modified. @end table @end deftypefun +@deftypefun int unlinkat (int @var{filedes}, const char *@var{filename}, int @var{flags}) +@standards{POSIX.1-2008, unistd.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{unlink} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument may either be @code{0} or contain the flag @code{AT_REMOVEDIR}: + +@table @code +@item AT_REMOVEDIR +This flag causes @code{unlinkat} to perform an @code{rmdir} operation on +@code{filename} instead of performing the equivalent of @code{unlink}. +@end table + +Compared to @code{unlink}, some additional error conditions can occur due to +descriptor-relative access. @xref{Descriptor-Relative Access}. In +addition to this, the following other errors can also occur: + +@table @code +@item EISDIR +The effective final path derived from @var{filename} and @var{filedes} is a +directory but @code{AT_REMOVEDIR} was not passed in @code{flags}. +@end table +@end deftypefun + @deftypefun int rmdir (const char *@var{filename}) @standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @@ -1821,6 +1935,20 @@ file systems. @end table @end deftypefun +@deftypefun int renameat (int @var{oldfiledes}, const char *@var{oldname}, int @var{newfiledes}, const char *@var{newname}) +@standards{POSIX.1-2008, stdio.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{rename} +function above. @xref{Descriptor-Relative Access}. If @var{oldname} or +@var{newname} is a relative path, it is interpreted relative to the +directory associated with @var{oldfiledes} or @var{newfiledes}, +respectively. Absolute paths are interpreted in the usual way. + +Compared to @code{rename}, some additional error conditions can occur. +@xref{Descriptor-Relative Access}. +@end deftypefun + @node Creating Directories @section Creating Directories @cindex creating a directory @@ -1875,6 +2003,17 @@ To use this function, your program should include the header file @pindex sys/stat.h @end deftypefun +@deftypefun int mkdirat (int @var{filedes}, const char *@var{filename}, mode_t @var{mode}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{mkdir} +function above. @xref{Descriptor-Relative Access}. + +Compared to @code{mkdir}, some additional error conditions can occur. +@xref{Descriptor-Relative Access}. +@end deftypefun + @node File Attributes @section File Attributes @@ -2259,6 +2398,11 @@ The @var{flags} argument is not valid for this function. @item ENOTDIR The descriptor @var{filedes} is not associated with a directory, and @var{filename} is a relative file name. + +@item ENOENT +The file named by @var{filename} does not exist, it's a dangling symbolic link +and @var{flags} does not contain @code{AT_SYMLINK_NOFOLLOW}, or @var{filename} +is an empty string and @var{flags} does not contain @code{AT_EMPTY_PATH}. @end table When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this @@ -2980,6 +3124,29 @@ Flag meaning test for execute/search permission. Flag meaning test for existence of the file. @end deftypevr +@deftypefun int faccessat (int @var{filedes}, const char *@var{filename}, int @var{how}, int @var{flags}) +@standards{POSIX.1-2008, unistd.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{access} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument can contain a combination of the flags @code{AT_EACCESS} described +below, @code{AT_EMPTY_PATH}, and @code{AT_SYMLINK_NOFOLLOW}. + +@vtable @code +@item AT_EACCESS +This flag when passed to the @code{faccessat} function causes it to perform +access checks using effective user and group IDs instead of real IDs, which +is the default and matches the @code{access} function. +@end vtable + +Compared to @code{access}, some additional error conditions can occur. +@xref{Descriptor-Relative Access}. + +This function may not work correctly on older kernels missing the +@code{faccessat2} system call. +@end deftypefun + @node File Times @subsection File Times @@ -3148,6 +3315,10 @@ permission for the file, or be a privileged user. @item EBADF The @var{filedes} argument is not a valid file descriptor. +@item EINVAL +At least one of the fields in the @code{tvp} array passed has an invalid +value. + @item EPERM If the @var{times} argument is not a null pointer, you must either be the owner of the file or be a privileged user. @@ -3157,6 +3328,64 @@ The file lives on a read-only file system. @end table @end deftypefun +@deftypefun int futimens (int @var{filedes}, const struct timespec @var{tsp}@t{[2]}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is like @code{futimes}, except that it sets the file access +and modification timestamps with nanosecond precision. The argument +@code{tsp} is used similarly to @code{futimes}' @code{tvp}, but has a +@code{const struct timespec} type that can express calendar time with +nanosecond precision. @xref{Time Types}. +@end deftypefun + +@deftypefun int utimensat (int @var{filedes}, const char *@var{filename}, const struct timespec @var{tsp}@t{[2]}, int @var{flags}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{futimens} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument can contain a combination of the flags @code{AT_EMPTY_PATH}, and +@code{AT_SYMLINK_NOFOLLOW}. The call: + +@smallexample +futimens (@var{filedes}, @var{tsp}) +@end smallexample + +is equivalent to: + +@smallexample +utimensat (@var{filedes}, @code{NULL}, @var{tsp}, 0) +@end smallexample + +Compared to @code{futimens}, some additional error conditions can occur due +to descriptor-relative access. @xref{Descriptor-Relative Access}. In +addition to this, the following other errors can also occur: + +@table @code +@item EINVAL +The @var{filename} argument is NULL, @var{filedes} is not @code{AT_FDCWD}, +and @var{flags} is not @code{0}. + +@item ELOOP +There are too many levels of indirection. This can be the result of +circular symbolic links to directories. + +@item ENAMETOOLONG +The resulting path is too long. This error only occurs on systems which +have a limit on the file name length. + +@item ENOENT +The @var{filename} argument is an empty string and @var{flags} does not +contain @code{AT_EMPTY_PATH}, or @var{filename} does not refer to an +existing file. + +@item ESRCH +Search permission was denied for one of the prefix components of the the +@var{filename} argument. +@end table +@end deftypefun + @node File Size @subsection File Size @@ -3760,22 +3989,17 @@ creation always works like @code{open} with @code{O_EXCL}. The @code{mkdtemp} function comes from OpenBSD. @c FIXME these are undocumented: -@c faccessat @c fchmodat @c fchownat @c futimesat @c fstatat (there's a commented-out safety assessment for this one) @c statx -@c mkdirat @c mkfifoat @c name_to_handle_at @c openat @c open_by_handle_at @c readlinkat -@c renameat @c renameat2 @c scandirat @c symlinkat -@c unlinkat -@c utimensat @c mknodat diff --git a/manual/getopt.texi b/manual/getopt.texi index b4c0b15..79a9423 100644 --- a/manual/getopt.texi +++ b/manual/getopt.texi @@ -301,7 +301,10 @@ application to pass long options with only @samp{-} instead of @samp{--}. The @samp{--} prefix is still recognized but instead of looking through the short options if a @samp{-} is seen it is first tried whether this parameter names a long option. If not, it is parsed -as a short option. +as a short option. In case both short and long options could be +matched (this can happen with single letter long options), the short +option is preferred (with some caveats). For long options, +abbreviations are detected as well. Assuming @code{getopt_long_only} is used starting an application with @@ -313,6 +316,32 @@ Assuming @code{getopt_long_only} is used starting an application with the @code{getopt_long_only} will first look for a long option named @samp{foo}. If this is not found, the short options @samp{f}, @samp{o}, and again @samp{o} are recognized. + +It gets more interesting with single letter long options. If we +define options in the following way + +@smallexample + static struct option long_options[] = @{ + @{"f", no_argument, 0, 0 @}, + @{"foo", no_argument, 0, 0 @}, + @{0, 0, 0, 0 @}, + @}; +@end smallexample + +@noindent +use @code{"f"} (as a C string) as an option string and start the +application with @option{-f}, the short option will be matched. +@option{--f} will match the long one. And both @option{-fo} and +@option{-foo} will match the long option @code{"foo"}. + +Be aware that if the option string would be @code{"f:"} (thus the +short option requires an argument), using just @option{-f} leads to an +error. But using @option{-fo} results in the long option being +matched. For passing an argument in this situation, you need to do it +as two arguments (@option{-f}, @option{o}). Though any other value +would work in a single argument (e.g., @option{-f1}), since it would +not match a long option (or its abbreviation). + @end deftypefun @node Getopt Long Option Example diff --git a/manual/install.texi b/manual/install.texi index 7fcdda9..8f8f0a1 100644 --- a/manual/install.texi +++ b/manual/install.texi @@ -320,6 +320,14 @@ If not provided, @option{LEVEL} defaults to highest possible value supported by the build compiler. Default is to disable fortification. + +@item --enable-sframe +Experimental option supported by some architectures, where @theglibc{} +is built with @option{-Wa,--gsframe} if @code{binutils} supports it. +Currently this is only supported on x86_64 and aarch64. The option +enables SFrame support on @code{backtrace}. + +Default is to disable SFrame support. @end table To build the library and related programs, type @code{make}. This will @@ -535,7 +543,7 @@ GCC 12.1 or newer GCC 12.1 or higher is required. In general it is recommended to use the newest version of the compiler that is known to work for building @theglibc{}, as newer compilers usually produce better code. As of -release time, GCC 14.2.1 is the newest compiler verified to work to build +release time, GCC 15.1.1 is the newest compiler verified to work to build @theglibc{}. For multi-arch support it is recommended to use a GCC which has been built with @@ -552,19 +560,13 @@ You can use whatever compiler you like to compile programs that use Check the FAQ for any special compiler issues on particular platforms. @item -GNU @code{binutils} 2.25 or later +GNU @code{binutils} 2.39 or later You must use GNU @code{binutils} (as and ld) to build @theglibc{}. No other assembler or linker has the necessary functionality at the -moment. As of release time, GNU @code{binutils} 2.43.1 is the newest +moment. As of release time, GNU @code{binutils} 2.45 is the newest verified to work to build @theglibc{}. -For PowerPC 64-bits little-endian (powerpc64le), @command{objcopy} is required -to support @option{--update-section}. This option requires binutils 2.26 or -newer. - -ARC architecture needs @code{binutils} 2.32 or higher for TLS related fixes. - @item GNU @code{texinfo} 4.7 or later @@ -581,7 +583,7 @@ GNU @code{awk} 3.1.2, or higher @code{awk} is used in several places to generate files. Some @code{gawk} extensions are used, including the @code{asorti} function, which was introduced in version 3.1.2 of @code{gawk}. -As of release time, @code{gawk} version 5.3.1 is the newest verified +As of release time, @code{gawk} version 5.3.2 is the newest verified to work to build @theglibc{}. Testing the GNU C Library requires @code{gawk} to be compiled with @@ -600,7 +602,7 @@ Perl 5 Perl is not required, but if present it is used in some tests and the @code{mtrace} program, to build the @glibcadj{} manual. As of release -time @code{perl} version 5.40.0 is the newest verified to work to +time @code{perl} version 5.42.0 is the newest verified to work to build @theglibc{}. @item @@ -614,7 +616,7 @@ with any version of @code{sed}. As of release time, @code{sed} version Python 3.4 or later Python is required to build @theglibc{}. As of release time, Python -3.12.8 is the newest verified to work for building and testing +3.13.5 is the newest verified to work for building and testing @theglibc{}. @item PExpect 4.0 @@ -634,7 +636,7 @@ missing @code{abnf} module does not reduce the test coverage of the library itself. @item -GDB 7.8 or later with support for Python 2.7/3.4 or later +GDB 7.8 or later with support for Python 3.4 or later GDB itself needs to be configured with Python support in order to use the pretty printers. Notice that your system having Python available @@ -663,7 +665,7 @@ and if you change any of the message translation files you will need @item GNU @code{gettext} 0.10.36 or later -As of release time, GNU @code{gettext} version 0.23 is the newest +As of release time, GNU @code{gettext} version 0.23.2 is the newest version verified to work to build @theglibc{}. @end itemize diff --git a/manual/intro.texi b/manual/intro.texi index d956484..3a45a51 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -1061,8 +1061,7 @@ put the @samp{#include} directives immediately afterwards, following the feature test macro definition (@pxref{Feature Test Macros}). For more information about the use of header files and @samp{#include} -directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor -Manual}. +directives, @pxref{Header Files,,, cpp, The GNU C Preprocessor Manual}. @Theglibc{} provides several header files, each of which contains the type and macro definitions and variable and function declarations diff --git a/manual/lgpl-2.1.texi b/manual/lgpl-2.1.texi index ab03d6c..93663f7 100644 --- a/manual/lgpl-2.1.texi +++ b/manual/lgpl-2.1.texi @@ -6,12 +6,12 @@ @display Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc. -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA +<https://fsf.org/> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. -[This is the first released version of the Lesser GPL. It also counts +[This is the first released version of the Lesser GPL@. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.] @end display @@ -474,13 +474,13 @@ and reuse of software generally. @item BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO -WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE -LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +PURPOSE@. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU@. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. @item @@ -523,13 +523,11 @@ your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, -USA. +License along with this library; if not, see <https://www.gnu.org/licenses/>. @end smallexample Also add information on how to contact you by electronic and paper mail. @@ -542,8 +540,8 @@ necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. -@var{signature of Ty Coon}, 1 April 1990 -Ty Coon, President of Vice +@var{signature of Moe Ghoul}, 1 April 1990 +Moe Ghoul, President of Vice @end smallexample That's all there is to it! diff --git a/manual/libc.texinfo b/manual/libc.texinfo index ff0beb1..870ed7a 100644 --- a/manual/libc.texinfo +++ b/manual/libc.texinfo @@ -29,7 +29,7 @@ @comment %**end of header (This is for running Texinfo on a region.) @c Everything related to printed editions is disabled until we have -@c resolved how to keep them in sync with the master sources of the +@c resolved how to keep them in sync with the primary sources of the @c manual. @c sold 0.06/1.09, print run out 21may96 @c @set EDITION 0.13 diff --git a/manual/llio.texi b/manual/llio.texi index 7b5f77b..7094ff4 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -218,6 +218,104 @@ new, extended API using 64 bit file sizes and offsets transparently replaces the old API. @end deftypefun +@deftp {Data Type} {struct open_how} +@standards{Linux, fcntl.h} +The @code{open_how} structure describes how to open a file using @code{openat2}. + +@strong{Portability note:} In the future, additional fields can be added +to @code{struct open_how}, so that the size of this data type increases. +Do not use it in places where this matters, such as structure fields in +installed header files, where such a change could affect the application +binary interface (ABI). + +The following generic fields are available. + +@table @code +@item flags +This field specifies the file creation and file status flags to use when +opening the file. +All of the @code{O_*} flags defined for @code{openat} are valid. +The @code{openat2} is stricter than @code{openat} in rejecting unknown or +conflicting values. For example, @code{openat2} rejects a mode that +exceeds 07777, whereas @code{openat} silently ignores +excess high-order bits. + +@item mode +This field specifies the mode for the new file, similar to @code{mode} +argument of @code{openat}. It should be in the range 0..07777. + +@item resolve +This is a bitmask of flags that affect the resolution of file name components. +Unlike @code{O_NOFOLLOW}, it affects all file name components, not just the +last one. The following flags are available. + +@table @code +@item RESOLVE_NO_XDEV +Disallow traversal of mount points during path resolution (including all +bind mounts). + +@item RESOLVE_NO_MAGICLINKS +Disallow all @strong{magic-link} resolution during path resolution. Magic +links are symbolic link-like objects that are found in @strong{procfs}; +for example the @code{/proc/pid/exe}. + +@item RESOLVE_NO_SYMLINKS +Disallow resolution of symbolic links during path resolution. +This option implies @code{RESOLVE_NO_MAGICLINKS}. + +@item RESOLVE_BENEATH +This rejects absolute pathnames, pathnames containing @file{..}@: +components that would be resolved relative to @var{dfd}, +and symbolic links that resolve to pathnames that would be rejected. +The rejection occurs even if @var{dfd} is the root directory. + +@item RESOLVE_IN_ROOT +Treat absolute pathnames as being relative to @var{dfd}, +treat a @file{..}@: component as being equivalent to @file{.}@: +if it is resolved relative to @var{dfd}, +and treat symbolic link contents consistently with this. +@end table + +@end table + +@end deftp + + +@deftypefun int openat2 (int @var{dirfd}, const char *@var{pathname}, const struct open_how *@var{how}, size_t @var{size}) +@standards{Linux, fcntl.h} +@safety{@mtsafe{}@assafe{}@acsafe{}} +This function is an extension of the @code{openat} and provides a superset of its +functionality. @xref{Descriptor-Relative Access}. + +The @var{size} argument must equal @code{sizeof *@var{how}}. For portability +to future API versions that may extend @code{struct open_how}, @code{*@var{how}} +should be fully initialized e.g., by a struct initializer, by @code{memset} to zero, +or by having static storage duration. + +On failure, @code{openat2} returns @math{-1} and sets @code{errno}. It can +fail for any of the reasons @code{openat} fails, plus the following reasons: + +@table @code +@item E2BIG +@var{size} is too large for any future extension, @code{*@var{how}} contains +non-zero members that are future extensions not supported by this kernel + +@item EINVAL +An unknown flag or invalid value was used on @code{*@var{how}}; or +@code{@var{how}->mode} is non-zero, but @code{@var{how}->flags} does not contain +@code{O_CREAT} or @code{O_TMPFILE}, or @var{size} is smaller than the ones supported +by the kernel. +@end table + +It can also return all the errors @code{openat} returns. + +Similar to @code{openat}, @code{openat2} is a cancellation point. + +Unlike other @code{open}-like functions, this function ignores +@code{_FILE_OFFSET_BITS} and always operates in large file mode. +@end deftypefun + + @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode}) @standards{POSIX.1, fcntl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} @@ -1414,6 +1512,10 @@ naturally-aligned with regard to total write length. The @code{atomic_*} values can be obtained with @code{statx} along with @code{STATX_WRITE_ATOMIC} flag. +@item RWF_DONTCACHE +Use uncached buffered IO. If the file system does not support it, the +call will fail and set @code{errno} to @code{EOPNOTSUPP}. + This is a Linux-specific extension. @end vtable @@ -2271,8 +2373,8 @@ inefficient. A better solution is to use the @code{select} function. This blocks the program until input or output is ready on a specified set of file descriptors, or until a timer expires, whichever comes first. This -facility is declared in the header file @file{sys/types.h}. -@pindex sys/types.h +facility is declared in the header file @file{sys/select.h}. +@pindex sys/select.h In the case of a server socket (@pxref{Listening}), we say that ``input'' is available when there are pending connections that could be @@ -2286,13 +2388,13 @@ as @code{fd_set} objects. Here is the description of the data type and some macros for manipulating these objects. @deftp {Data Type} fd_set -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} The @code{fd_set} data type represents file descriptor sets for the @code{select} function. It is actually a bit array. @end deftp @deftypevr Macro int FD_SETSIZE -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} The value of this macro is the maximum number of file descriptors that a @code{fd_set} object can hold information about. On systems with a fixed maximum number, @code{FD_SETSIZE} is at least that number. On @@ -2304,14 +2406,14 @@ that descriptor into an @code{fd_set}. @end deftypevr @deftypefn Macro void FD_ZERO (fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro initializes the file descriptor set @var{set} to be the empty set. @end deftypefn @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} @c Setting a bit isn't necessarily atomic, so there's a potential race @c here if set is not used exclusively. @@ -2322,7 +2424,7 @@ evaluated more than once. @end deftypefn @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} @c Setting a bit isn't necessarily atomic, so there's a potential race @c here if set is not used exclusively. @@ -2333,7 +2435,7 @@ evaluated more than once. @end deftypefn @deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro returns a nonzero value (true) if @var{filedes} is a member of the file descriptor set @var{set}, and zero (false) otherwise. @@ -2345,7 +2447,7 @@ evaluated more than once. Next, here is the description of the @code{select} function itself. @deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}} @c The select syscall is preferred, but pselect6 may be used instead, @c which requires converting timeout to a timespec and back. The @@ -2420,9 +2522,6 @@ or too large. @end table @end deftypefun -@strong{Portability Note:} The @code{select} function is a BSD Unix -feature. - Here is an example showing how you can use @code{select} to establish a timeout period for reading from a file descriptor. The @code{input_timeout} function blocks the calling process until input is available on the diff --git a/manual/maint.texi b/manual/maint.texi index b6ee5b6..2d540ce 100644 --- a/manual/maint.texi +++ b/manual/maint.texi @@ -323,6 +323,8 @@ The following functions and macros are fortified in @theglibc{}: @item @code{memset} +@item @code{memset_explicit} + @item @code{mq_open} @item @code{obstack_printf} @@ -496,7 +498,7 @@ the symbol's name. For instance, the macro @code{__clock_gettime64} expands to @code{clock_gettime}. When @code{__TIMESIZE} is set to 64, @theglibc{} will also define -the@code{__USE_TIME_BITS64} macro. It is used by the Linux kernel ABI +the @code{__USE_TIME_BITS64} macro. It is used by the Linux kernel ABI to set the expected @code{time_t} size used on some syscalls. These macros are purely internal to @theglibc{} and exist only so that @@ -725,8 +727,8 @@ just @w{@samp{--with-@var{package}}} (no argument), then it sets @item configure.ac This file is an Autoconf input fragment to be processed into the file -@file{configure} in this subdirectory. @xref{Introduction,,, -autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, +@file{configure} in this subdirectory. @xref{Introduction,,, autoconf, +Autoconf: Generating Automatic Configuration Scripts}, for a description of Autoconf. You should write either @file{configure} or @file{configure.ac}, but not both. The first line of @file{configure.ac} should invoke the @code{m4} macro diff --git a/manual/math.texi b/manual/math.texi index adbe271..fbabf37 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -803,6 +803,22 @@ The @code{pown} functions are from TS 18661-4:2015 (which used @code{long long int} in C23). @end deftypefun +@deftypefun double compoundn (double @var{x}, long long int @var{power}) +@deftypefunx float compoundnf (float @var{x}, long long int @var{power}) +@deftypefunx {long double} compoundnl (long double @var{x}, long long int @var{power}) +@deftypefunx _FloatN compoundnfN (_Float@var{N} @var{x}, long long int @var{power}) +@deftypefunx _FloatNx compoundnfNx (_Float@var{N}x @var{x}, long long int @var{power}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These return @code{1 + @var{x}} raised to @var{power} (an integer). +If @var{x} is less than @minus{}1, @code{compoundn} signals a domain +error. + +The @code{compoundn} functions are from TS 18661-4:2015 (which used +@code{intmax_t} as the type of @var{power}; the type changed to +@code{long long int} in C23). +@end deftypefun + @cindex square root function @deftypefun double sqrt (double @var{x}) @deftypefunx float sqrtf (float @var{x}) @@ -867,6 +883,22 @@ instead of the direct formula is wise, since the error is much smaller. See also the function @code{cabs} in @ref{Absolute Value}. @end deftypefun +@deftypefun double rootn (double @var{x}, long long int @var{n}) +@deftypefunx float rootnf (float @var{x}, long long int @var{n}) +@deftypefunx {long double} rootnl (long double @var{x}, long long int @var{n}) +@deftypefunx _FloatN rootnfN (_Float@var{N} @var{x}, long long int @var{n}) +@deftypefunx _FloatNx rootnfNx (_Float@var{N}x @var{x}, long long int @var{n}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These return the @var{n}th root of @var{x}. If @var{n} is zero, or if +@var{x} is negative and @var{n} is even, @code{rootn} signals a domain +error. + +The @code{rootn} functions are from TS 18661-4:2015 (which used +@code{intmax_t} as the type of @var{n}; the type changed to +@code{long long int} in C23). +@end deftypefun + @deftypefun double expm1 (double @var{x}) @deftypefunx float expm1f (float @var{x}) @deftypefunx {long double} expm1l (long double @var{x}) diff --git a/manual/memory.texi b/manual/memory.texi index 9a29c7d..74f3f6b 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -354,7 +354,7 @@ this function is in @file{stdlib.h}. @c that's protected by list_lock; next_free is only modified while @c list_lock is held too. All other data members of an arena, as well @c as the metadata of the memory areas assigned to it, are only modified -@c while holding the arena's mutex (fastbin pointers use catomic ops +@c while holding the arena's mutex (fastbin pointers use atomic ops @c because they may be modified by free without taking the arena's @c lock). Some reassurance was needed for fastbins, for it wasn't clear @c how they were initialized. It turns out they are always @@ -383,7 +383,7 @@ this function is in @file{stdlib.h}. @c mutex_lock (arena lock) dup @asulock @aculock [returns locked] @c __get_nprocs ext ok @acsfd @c NARENAS_FROM_NCORES ok -@c catomic_compare_and_exchange_bool_acq ok +@c atomic_compare_and_exchange_bool_acq ok @c _int_new_arena ok @asulock @aculock @acsmem @c new_heap ok @acsmem @c mmap ok @acsmem @@ -397,7 +397,7 @@ this function is in @file{stdlib.h}. @c mutex_lock (list_lock) dup @asulock @aculock @c atomic_write_barrier ok @c mutex_unlock (list_lock) @aculock -@c catomic_decrement ok +@c atomic_fetch_add ok @c reused_arena @asulock @aculock @c reads&writes next_to_use and iterates over arena next without guards @c those are harmless as long as we don't drop arenas from the @@ -414,7 +414,7 @@ this function is in @file{stdlib.h}. @c get_max_fast ok @c fastbin_index ok @c fastbin ok -@c catomic_compare_and_exhange_val_acq ok +@c atomic_compare_and_exhange_val_acq ok @c malloc_printerr dup @mtsenv @c if we get to it, we're toast already, undefined behavior must have @c been invoked before @@ -521,10 +521,9 @@ this function is in @file{stdlib.h}. @c chunk2mem dup ok @c free_perturb ok @c set_fastchunks ok -@c catomic_and ok @c fastbin_index dup ok @c fastbin dup ok -@c catomic_compare_and_exchange_val_rel ok +@c atomic_compare_and_exchange_val_rel ok @c chunk_is_mmapped ok @c contiguous dup ok @c prev_inuse ok @@ -706,7 +705,7 @@ The prototype for this function is in @file{stdlib.h}. @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c __libc_free @asulock @aculock @acsfd @acsmem @c releasing memory into fastbins modifies the arena without taking -@c its mutex, but catomic operations ensure safety. If two (or more) +@c its mutex, but atomic operations ensure safety. If two (or more) @c threads are running malloc and have their own arenas locked when @c each gets a signal whose handler free()s large (non-fastbin-able) @c blocks from each other's arena, we deadlock; this is a more general @@ -764,6 +763,34 @@ There is no point in freeing blocks at the end of a program, because all of the program's space is given back to the system when the process terminates. +@deftypefun void free_sized (void *@var{ptr}, size_t @var{size}) +@standards{ISO, stdlib.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +The @code{free_sized} function deallocates the block of memory pointed at +by @var{ptr} that was previously allocated by @code{malloc}, @code{calloc} +or @code{realloc}. The size @var{size} must match the previously requested +total size provided to @code{malloc}, @code{calloc} or @code{realloc}. +Attempting to deallocated memory allocated by @code{aligned_alloc}, +@code{memalign}, @code{posix_memalign}, @code{valloc} or @code{pvalloc} is +undefined behavior. For @code{aligned_alloc}, @code{memalign} or +@code{posix_memalign} use @code{free_aligned_sized} instead. Additionally +it is also undefined behavior to call @code{free_sized} for allocations +which the caller did not directly allocate but must still deallocate, such +as the result of @code{strdup} or @code{strndup}. Instead continue using +@code{free} for these cases. +@end deftypefun + +@deftypefun void free_aligned_sized (void *@var{ptr}, size_t @var{alignment}, size_t @var{size}) +@standards{ISO, stdlib.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +The @code{free_aligned_sized} function deallocates the block of memory +pointed at by @var{ptr} that was previously allocated by +@code{aligned_alloc}, @code{memalign} or @code{posix_memalign}. +The size @var{size} and alignment @var{alignment} must match the +previously requested size and alignment provided to +@code{aligned_alloc}, @code{memalign} or @code{posix_memalign}. +@end deftypefun + @node Changing Block Size @subsubsection Changing the Size of a Block @cindex changing the size of a block (@code{malloc}) @@ -1136,6 +1163,61 @@ The @code{valloc} function is obsolete and @code{aligned_alloc} or @code{posix_memalign} should be used instead. @end deftypefun +You can determine the alignment of a pointer with the +@code{memalignment} function. + +@deftypefun size_t memalignment (void *@var{p}) +@standards{C23, stdlib.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +This function, defined in C23, returns the alignment of @var{p}, as a +power of two. If @var{p} is a null pointer, it returns zero. C23 +requires @var{p} to be a valid pointer to an object or a null pointer; +as a GNU extension, @theglibc{} supports this function on arbitrary +bit patterns of pointer type. + +This function was added to the C23 standard to support unconventional +platforms where a pointer's low-order bits are unrelated to alignment. +For conventional platforms, one can instead cast the pointer to +@code{uintptr_t} and then test the low order bits: +this is portable to pre-C23 and is typically a bit faster. + +For example, if you want to read an @code{int} +addressed by possibly-misaligned pointer @code{p}, +the following pre-C23 code works on all conventional platforms: + +@smallexample +int i; +if (((uintptr_t) p & (alignof (int) - 1)) != 0) + memcpy (&i, p, sizeof i); +else + i = *p; +@end smallexample + +However, it might not work on unconventional platforms, where one +would need something like the following C23 code: + +@smallexample +int i; +if (memalignment (p) < alignof (int)) + memcpy (&i, p, sizeof i); +else + i = *p; +@end smallexample + +However, for this particular case, performance does not improve if +different code is used for aligned and unaligned pointers, +and the following code is preferable: + +@smallexample +int i; +memcpy (&i, p, sizeof i); +@end smallexample + +The compiler will generate the most efficient way to access unaligned +data for the architecture, optimizing away the @code{memcpy} call. +@end deftypefun + @node Malloc Tunable Parameters @subsubsection Malloc Tunable Parameters @@ -1854,6 +1936,8 @@ functions, too. Their names are listed in the following table. @table @code @item aligned_alloc +@item free_aligned_sized +@item free_sized @item malloc_usable_size @item memalign @item posix_memalign @@ -3072,6 +3156,75 @@ process memory, no matter how it was allocated. However, portable use of the function requires that it is only used with memory regions returned by @code{mmap} or @code{mmap64}. +@deftypefun int mseal (void *@var{address}, size_t @var{length}, unsigned long @var{flags}) +@standards{Linux, sys/mman.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +A successful call to the @code {mseal} function protects the memory +range @var{address} of @var{length} bytes, previously allocated with +@code{mmap} or @code{mremap}, against further metadata changes, such +as: + +@itemize @bullet +@item +Unmapping, moving to another location, extending or shrinking the size, +via @code{munmap} and @code{mremap}. + +@item +Moving or expanding a different VMA into the current location, via +@code{mremap}. + +@item +Modifying the memory range with @code{mmap} along with the flag @code{MAP_FIXED}. + +@item +Change the protection flags with @code{mprotect} or @code{pkey_mprotect}. Also +for certain destructive @code{madvise} behaviours (@code{MADV_DONTNEED}, +@code{MADV_FREE}, @code{MADV_DONTNEED_LOCKED}, and @code{MADV_WIPEONFORK}), +@code{mseal} only blocks the operation if the protection key associated with +the memory denies write. + +@item +Destructive behaviors on anonymous memory, such as @code{madvice} with +@code{MADV_DONTNEED}. +@end itemize + +The @var{address} must be an allocated virtual memory done by @code{mmap} +or @code{mremap}, and it must be page-aligned. The end address (@var{address} +plus @var{length}) must be within an allocated virtual memory range. There +should be no unallocated memory between the start and end of the address range. + +The @var{flags} is currently unused. + +The @code{mseal} function returns @math{0} on success and @math{-1} on +failure. + +The following @code{errno} error conditions are defined for this +function: + +@table @code +@item EPERM +The system blocked the operation, and the given address range is unmodified +without a partial update. This error is also returned when @code{mseal} is +issued on a 32-bit CPU (sealing is currently supported only on 64-bit CPUs, +although 32-bit binaries running on a 64-bit kernel are supported). + +@item ENOMEM +Either the @var{address} is not allocated, or the end address is not within the +allocation, or there is unallocated memory between the start and end address. + +@item ENOSYS +The kernel does not support the @code{mseal} syscall. + +@end table +@end deftypefun + +@strong{NB:} The memory sealing changes the lifetime of a mapping, where the +sealing memory could not be unmapped until the process terminates or replaces +the process image through @code{execve} function. The sealed mappings are +inherited through @code{fork}. + + @subsection Memory Protection Keys @cindex memory protection key @@ -3139,7 +3292,7 @@ used to temporarily acquire access to the memory region and relinquish it again: @smallexample - if (key >= 0 && pkey_set (key, 0) < 0) + if (key >= 0 && pkey_set (key, PKEY_UNRESTRICTED) < 0) ...; /* Perform error checking (generally fatal). */ /* At this point, the current thread has read-write access to the memory region. */ @@ -3256,9 +3409,9 @@ not @math{-1}. @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Change the access restrictions of the current thread for memory pages with the protection key @var{key} to @var{access_restrictions}. If -@var{access_restrictions} is zero, no additional access restrictions on top of -the page protection flags are applied. Otherwise, @var{access_restrictions} is -a combination of the following flags: +@var{access_restrictions} is @code{PKEY_UNRESTRICTED} (zero), no additional +access restrictions on top of the page protection flags are applied. Otherwise, +@var{access_restrictions} is a combination of the following flags: @vtable @code @item PKEY_DISABLE_READ diff --git a/manual/message.texi b/manual/message.texi index 71b56e6..0b0d420 100644 --- a/manual/message.texi +++ b/manual/message.texi @@ -1356,7 +1356,7 @@ The following rules are known at this point. The language with families are listed. But this does not necessarily mean the information can be generalized for the whole family (as can be easily seen in the table below).@footnote{Additions are welcome. Send appropriate information to -@email{bug-glibc-manual@@gnu.org}.} +@email{libc-alpha@@sourceware.org}.} @table @asis @item Only one form: diff --git a/manual/resource.texi b/manual/resource.texi index acdb1f3..1fd0310 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -977,7 +977,7 @@ multiple parameters (not just priority and niceness). It is expected that these interfaces will be compatible with all future scheduling policies. -For additional information about scheduling policies, consult consult +For additional information about scheduling policies, consult the manual pages @manpageurl{sched,7} and @manpageurl{sched_setattr,2}. @strong{Note:} Calling the @code{sched_setattr} function is incompatible @@ -1015,7 +1015,7 @@ For additional information, consult the manual page @manpageurl{sched_setattr,2}. @end deftp -@deftypefun int sched_setaddr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int flags) +@deftypefun int sched_setattr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int flags) @standards{Linux, sched.h} @safety{@mtsafe{}@assafe{}@acsafe{}} This functions applies the scheduling policy described by @@ -1058,7 +1058,7 @@ policy of the thread @var{tid}. Other error codes depend on the scheduling policy. @end deftypefun -@deftypefun int sched_getaddr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int size, unsigned int flags) +@deftypefun int sched_getattr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int size, unsigned int flags) @standards{Linux, sched.h} @safety{@mtsafe{}@assafe{}@acsafe{}} This function obtains the scheduling policy of the thread @var{tid} @@ -1362,26 +1362,73 @@ extent the Linux kernel interface. @standards{GNU, sched.h} This data set is a bitset where each bit represents a CPU. How the system's CPUs are mapped to bits in the bitset is system dependent. -The data type has a fixed size; in the unlikely case that the number -of bits are not sufficient to describe the CPUs of the system a -different interface has to be used. +The data type has a fixed size; it is strongly recommended to allocate +a dynamically sized set based on the actual number of CPUs detected, +such as via @code{get_nprocs_conf()}, and use the @code{CPU_*_S} +variants instead of the fixed-size ones. This type is a GNU extension and is defined in @file{sched.h}. @end deftp -To manipulate the bitset, to set and reset bits, a number of macros are -defined. Some of the macros take a CPU number as a parameter. Here -it is important to never exceed the size of the bitset. The following -macro specifies the number of bits in the @code{cpu_set_t} bitset. +To manipulate the bitset, to set and reset bits, and thus add and +remove CPUs from the sets, a number of macros are defined. Some of +the macros take a CPU number as a parameter. Here it is important to +never exceed the size of the bitset, either @code{CPU_SETSIZE} for +fixed sets or the allocated size for dynamic sets. For each macro +there is a fixed-size version (documented below) and a dynamic-sized +version (with a @code{_S} suffix). @deftypevr Macro int CPU_SETSIZE @standards{GNU, sched.h} The value of this macro is the maximum number of CPUs which can be -handled with a @code{cpu_set_t} object. +handled with a fixed @code{cpu_set_t} object. @end deftypevr +For applications that require CPU sets larger than the built-in size, +a set of macros that support dynamically-sized sets are defined. + +@deftypefn Macro size_t CPU_ALLOC_SIZE (size_t @var{count}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_ALLOC_SIZE ok +@c __CPU_ALLOC_SIZE ok +Given a count of CPUs to hold, returns the size of the set to +allocate. This return value is appropriate to be used in the *_S macros. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + +@deftypefn Macro {cpu_set_t *} CPU_ALLOC (size_t @var{count}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +@c CPU_ALLOC +@c __CPU_ALLOC +@c __sched_cpualloc +@c malloc +Given the count of CPUs to hold, returns a set large enough to hold +them; that is, the resulting set will be valid for CPUs numbered 0 +through @var{count}-1, inclusive. This set must be freed via +@code{CPU_FREE} to avoid memory leaks. Warning: the argument is the +CPU @emph{count} and not the size returned by @code{CPU_ALLOC_SIZE}. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + +@deftypefn Macro void CPU_FREE (cpu_set_t *@var{set}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +@c CPU_FREE +@c __CPU_FREE +@c __sched_cpufree +@c free +Frees a CPU set previously allocated by @code{CPU_ALLOC}. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + The type @code{cpu_set_t} should be considered opaque; all -manipulation should happen via the next four macros. +manipulation should happen via the @code{CPU_*} macros described +below. @deftypefn Macro void CPU_ZERO (cpu_set_t *@var{set}) @standards{GNU, sched.h} @@ -1424,6 +1471,39 @@ evaluated more than once. This macro is a GNU extension and is defined in @file{sched.h}. @end deftypefn +@deftypefn Macro {cpu_set_t *} CPU_AND (cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_AND ok +@c __CPU_OP_S ok +This macro populates @var{dest} with only those CPUs included in both +@var{src1} and @var{src2}. Its value is @var{dest}. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + +@deftypefn Macro {cpu_set_t *} CPU_OR (cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_OR ok +@c __CPU_OP_S ok +This macro populates @var{dest} with those CPUs included in either +@var{src1} or @var{src2}. Its value is @var{dest}. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + +@deftypefn Macro {cpu_set_t *} CPU_XOR (cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_XOR ok +@c __CPU_OP_S ok +This macro populates @var{dest} with those CPUs included in either +@var{src1} or @var{src2}, but not both. Its value is @var{dest}. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + @deftypefn Macro int CPU_ISSET (int @var{cpu}, const cpu_set_t *@var{set}) @standards{GNU, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @@ -1440,6 +1520,54 @@ evaluated more than once. This macro is a GNU extension and is defined in @file{sched.h}. @end deftypefn +@deftypefn Macro int CPU_COUNT (const cpu_set_t *@var{set}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_COUNT ok +@c __CPU_COUNT_S ok +@c __sched_cpucount ok +@c countbits ok +This macro returns the count of CPUs (bits) set in @var{set}. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + +@deftypefn Macro int CPU_EQUAL (cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@standards{GNU, sched.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_EQUAL ok +@c __CPU_EQUAL_S ok +@c memcmp ok +This macro returns nonzero if the two sets @var{set1} and @var{set2} +have the same contents; that is, the set of CPUs represented by both +sets is identical. + +This macro is a GNU extension and is defined in @file{sched.h}. +@end deftypefn + +@deftypefn Macro void CPU_ZERO_S (size_t @var{size}, cpu_set_t *@var{set}) +@end deftypefn +@deftypefn Macro void CPU_SET_S (int @var{cpu}, size_t @var{size}, cpu_set_t *@var{set}) +@end deftypefn +@deftypefn Macro void CPU_CLR_S (int @var{cpu}, size_t @var{size}, cpu_set_t *@var{set}) +@end deftypefn +@deftypefn Macro {cpu_set_t *} CPU_AND_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@end deftypefn +@deftypefn Macro {cpu_set_t *} CPU_OR_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@end deftypefn +@deftypefn Macro {cpu_set_t *} CPU_XOR_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@end deftypefn +@deftypefn Macro int CPU_ISSET_S (int @var{cpu}, size_t @var{size}, const cpu_set_t *@var{set}) +@end deftypefn +@deftypefn Macro int CPU_COUNT_S (size_t @var{size}, const cpu_set_t *@var{set}) +@end deftypefn +@deftypefn Macro int CPU_EQUAL_S (size_t @var{size}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2}) +@end deftypefn + +Each of these macros performs the same action as its non-@code{_S} variant, +but takes a @var{size} argument to specify the set size. This +@var{size} argument is as returned by the @code{CPU_ALLOC_SIZE} macro, +defined above. CPU bitsets can be constructed from scratch or the currently installed affinity mask can be retrieved from the system. @@ -1525,6 +1653,53 @@ The operating system does not support this function. This function is Linux-specific and is declared in @file{sched.h}. @end deftypefun +@deftypefun int sched_getcpu (void) +@standards{Linux, <sched.h>} + +Similar to @code{getcpu} but with a simpler interface. On success, +returns a nonnegative number identifying the CPU on which the current +thread is running. Returns @code{-1} on failure. The following +@code{errno} error condition is defined for this function: + +@table @code +@item ENOSYS +The operating system does not support this function. +@end table + +This function is Linux-specific and is declared in @file{sched.h}. +@end deftypefun + +Here's an example of how to use most of the above to limit the number +of CPUs a process runs on, not including error handling or good logic +on CPU choices: + +@example +#define _GNU_SOURCE +#include <sched.h> +#include <sys/sysinfo.h> +#include <unistd.h> +void +limit_cpus (void) +@{ + unsigned int mycpu; + size_t nproc, cssz, cpu; + cpu_set_t *cs; + getcpu (&mycpu, NULL); + nproc = get_nprocs_conf (); + cssz = CPU_ALLOC_SIZE (nproc); + cs = CPU_ALLOC (nproc); + sched_getaffinity (0, cssz, cs); + if (CPU_COUNT_S (cssz, cs) > nproc / 2) + @{ + for (cpu = nproc / 2; cpu < nproc; cpu ++) + if (cpu != mycpu) + CPU_CLR_S (cpu, cssz, cs); + sched_setaffinity (0, cssz, cs); + @} + CPU_FREE (cs); +@} +@end example + @node Memory Resources @section Querying memory available resources diff --git a/manual/search.texi b/manual/search.texi index cb08c49..d38e23a 100644 --- a/manual/search.texi +++ b/manual/search.texi @@ -156,6 +156,14 @@ that matches, the one that is returned is unspecified. This function derives its name from the fact that it is implemented using the binary search algorithm. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{array} has a type +that is a pointer to a @code{const}-qualified object type, +@code{bsearch} returns @code{const void *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{void *} regardless. @end deftypefun @node Array Sort Function diff --git a/manual/setjmp.texi b/manual/setjmp.texi index 7092a0d..6b044bd 100644 --- a/manual/setjmp.texi +++ b/manual/setjmp.texi @@ -347,7 +347,7 @@ programs would fail. Examples for such code include the calling sequences the GNU C compiler generates for calls to nested functions. Safe ways to allocate stacks correctly include using memory on the original thread's stack or explicitly allocating memory tagged for -execution using (@pxref{Memory-mapped I/O}). +execution using @code{mmap} (@pxref{Memory-mapped I/O}). @strong{Compatibility note}: The current Unix standard is very imprecise about the way the stack is allocated. All implementations seem to agree diff --git a/manual/socket.texi b/manual/socket.texi index 8708cbb..2ed8112 100644 --- a/manual/socket.texi +++ b/manual/socket.texi @@ -497,7 +497,20 @@ interface name, including its terminating zero byte. @c takes a lock, which makes all callers AS- and AC-Unsafe. @c opensock @asulock @aculock @acsfd This function yields the interface index corresponding to a particular -name. If no interface exists with the name given, it returns 0. +name specified with @var{ifname}. + +The return value is the interface index on success. On failure, the +function's return value is zero and @code{errno} is set accordingly. +The following @code{errno} values are specific to this function: + +@table @code +@item ENODEV +There is no interface by the name requested. +@end table + +Additionally, since @code{if_nametoindex} invokes @code{socket} +internally, @code{errno} may also be set to a value listed for the +@code{socket} function (@pxref{Creating a Socket}). @end deftypefun @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname}) @@ -505,11 +518,22 @@ name. If no interface exists with the name given, it returns 0. @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c It opens a socket with opensock to use ioctl on the fd to get the @c name from the index. -This function maps an interface index to its corresponding name. The -returned name is placed in the buffer pointed to by @code{ifname}, which -must be at least @code{IFNAMSIZ} bytes in length. If the index was -invalid, the function's return value is a null pointer, otherwise it is -@code{ifname}. +This function maps an interface index @var{ifindex} to its corresponding +name. The returned name is placed in the buffer pointed to by @var{ifname}, +which must be at least @code{IFNAMSIZ} bytes in length. + +The return value is @var{ifname} on success. On failure, the function's +return value is a null pointer and @code{errno} is set accordingly. The +following @code{errno} values are specific to this function: + +@table @code +@item ENXIO +There is no interface at the index requested. +@end table + +Additionally, since @code{if_indextoname} invokes @code{socket} +internally, @code{errno} may also be set to a value listed for the +@code{socket} function (@pxref{Creating a Socket}). @end deftypefun @deftp {Data Type} {struct if_nameindex} @@ -1192,6 +1216,17 @@ either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of address being converted. @var{cp} is a pointer to the input string, and @var{buf} is a pointer to a buffer for the result. It is the caller's responsibility to make sure the buffer is large enough. + +The return value is @code{1} on success and @code{0} if @var{cp} does not +point to a valid address string for the address family @var{af} requested. +On failure, the function's return value is @code{-1} and @code{errno} is +set accordingly. The following @code{errno} values are specific to this +function: + +@table @code +@item EAFNOSUPPORT +The address family requested is neither @code{AF_INET} nor @code{AF_INET6}. +@end table @end deftypefun @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len}) @@ -1211,7 +1246,19 @@ network (binary) to presentation (textual) form. @var{af} should be either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a pointer to the address to be converted. @var{buf} should be a pointer to a buffer to hold the result, and @var{len} is the length of this -buffer. The return value from the function will be this buffer address. +buffer. + +The return value is @var{buf} on success. On failure, the function's +return value is a null pointer and @code{errno} is set accordingly. +The following @code{errno} values are specific to this function: + +@table @code +@item EAFNOSUPPORT +The address family requested is neither @code{AF_INET} nor @code{AF_INET6}. + +@item ENOSPC +Insufficient space available for the result in the buffer provided. +@end table @end deftypefun @node Host Names @@ -2205,9 +2252,19 @@ socket, or @code{-1} in case of error. The following @code{errno} error conditions are defined for this function: @table @code +@item EAFNOSUPPORT +The @var{namespace} requested is not supported. + +@item ESOCKTNOSUPPORT +@itemx EPROTONOSUPPORT +@itemx EPROTOTYPE +The @var{style} is not supported by the @var{namespace} specified. + @item EPROTONOSUPPORT -The @var{protocol} or @var{style} is not supported by the -@var{namespace} specified. +The @var{protocol} is not supported by the @var{namespace} specified. + +@item EINVAL +The @var{style} or @var{protocol} requested is not valid. @item EMFILE The process already has too many file descriptors open. @@ -2216,11 +2273,13 @@ The process already has too many file descriptors open. The system already has too many file descriptors open. @item EACCES +@itemx EPERM The process does not have the privilege to create a socket of the specified @var{style} or @var{protocol}. @item ENOBUFS -The system ran out of internal buffer space. +@itemx ENOMEM +Insufficient memory was available. @end table The file descriptor returned by the @code{socket} function supports both @@ -2258,22 +2317,23 @@ The @code{shutdown} function shuts down the connection of socket @var{socket}. The argument @var{how} specifies what action to perform: -@table @code -@item 0 -Stop receiving data for this socket. If further data arrives, -reject it. +@vtable @code +@item SHUT_RD +Stop receiving data on the socket. -@item 1 -Stop trying to transmit data from this socket. Discard any data -waiting to be sent. Stop looking for acknowledgement of data already -sent; don't retransmit it if it is lost. +@item SHUT_WR +Indicate to the peer that no further data will be transmitted on the +socket. This indication is ordered with regard to past send +operations on the socket, and data pending at the time of the call is +still delivered. -@item 2 -Stop both reception and transmission. -@end table +@item SHUT_RDWR +Combine the actions of @code{SHUT_RD} and @code{SHUT_WR}. +@end vtable The return value is @code{0} on success and @code{-1} on failure. The -following @code{errno} error conditions are defined for this function: +following generic @code{errno} error conditions are defined for this +function: @table @code @item EBADF @@ -2287,6 +2347,27 @@ following @code{errno} error conditions are defined for this function: @end table @end deftypefun +Additional errors can be reported for specific socket types. + +The exact impact of the @code{shutdown} function depends on the socket +protocol and its implementation. In portable code, the @code{shutdown} +function cannot be used on its own to gracefully terminate a connection +which is operated in full-duplex mode (with both peers sending data). + +On Linux, when @code{SHUT_RD} is used to shut down a TCP socket, any +pending data in the incoming socket buffer and any data that arrives +subsequently is discarded, without reporting an error or generating a +TCP RST segment. Attempts to read data from this socket using +@code{recv} and similar functions (@pxref{Receiving Data}) return zero. +(Other systems may treat @code{SHUT_RD} with pending data as a data loss +event and generate RST segments. Linux @code{AF_LOCAL}/@code{AF_UNIX} +sockets also report errors to peers.) + +Similarly, when @code{SHUT_WR} is used on a Linux TCP socket, a FIN +segment is sent to the peer, ordered after any data written previously +to the socket. After encountering the FIN segment, the peer will +recognize this as an end-of-stream condition. + @node Socket Pairs @subsection Socket Pairs @cindex creating a socket pair @@ -2918,7 +2999,7 @@ discard_until_mark (int socket) success = ioctl (socket, SIOCATMARK, &atmark); if (success < 0) perror ("ioctl"); - if (result) + if (atmark) return; /* @r{Otherwise, read a bunch of ordinary data and discard it.} diff --git a/manual/startup.texi b/manual/startup.texi index 6f29ddd..11fe58c 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -219,8 +219,8 @@ argument which itself is a comma separated list of options. To ease the programming of code like this the function @code{getsubopt} is available. -@deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep}) -@standards{???, stdlib.h} +@deftypefun int getsubopt (char **restrict @var{optionp}, char *const *restrict @var{tokens}, char **restrict @var{valuep}) +@standards{POSIX, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c getsubopt ok @c strchrnul dup ok @@ -668,7 +668,7 @@ defined in @file{elf.h}. If a matching entry is found, the value is returned; if the entry is not found, zero is returned and @code{errno} is set to @code{ENOENT}. -@strong{Note:} There is no relationship between the @samp{AT_} contants +@strong{Note:} There is no relationship between the @samp{AT_} constants defined in @file{elf.h} and the file name lookup flags in @file{fcntl.h}. @xref{Descriptor-Relative Access}. @end deftypefun @@ -737,6 +737,12 @@ anyway. @code{syscall} does not provide cancellation logic, even if the system call you're calling is listed as cancellable above. +Using @code{syscall} with system calls that affect the internal state of +process of thread will likely result in undefined behavior. For this reason, +at least the following system call numbers are not supported when invoked via +@code{syscall}: @code{SYS_clone}, @code{SYS_clone2}, @code{SYS_clone3}, +@code{SYS_rt_sigreturn}, @code{SYS_sigreturn}, @code{SYS_vfork}. + @code{syscall} is declared in @file{unistd.h}. @deftypefun {long int} syscall (long int @var{sysno}, @dots{}) @@ -804,7 +810,6 @@ if (rc == -1) @end deftypefun - @node Program Termination @section Program Termination @cindex program termination diff --git a/manual/stdio.texi b/manual/stdio.texi index 01b9f47..c01feae 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -1231,17 +1231,18 @@ convenient to have functions to read a line of text from a stream. Standard C has functions to do this, but they aren't very safe: null characters and even (for @code{gets}) long lines can confuse them. So -@theglibc{} provides the nonstandard @code{getline} function that -makes it easy to read lines reliably. +@theglibc{} provides the @code{getline} function that makes it easy to +read lines reliably. -Another GNU extension, @code{getdelim}, generalizes @code{getline}. It -reads a delimited record, defined as everything through the next -occurrence of a specified delimiter character. +The @code{getdelim} function is a generalized version of @code{getline}. +It reads a delimited record, defined as everything through the next +occurrence of a specified delimiter character. These functions were +both GNU extensions until standardized by POSIX.1-2008. All these functions are declared in @file{stdio.h}. -@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream}) -@standards{GNU, stdio.h} +@deftypefun ssize_t getline (char **restrict @var{lineptr}, size_t *restrict @var{n}, FILE *restrict @var{stream}) +@standards{POSIX.1-2008, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c Besides the usual possibility of getting an inconsistent stream in a @c signal handler or leaving it inconsistent in case of cancellation, @@ -1274,15 +1275,20 @@ read (including the newline, but not including the terminating null). This value enables you to distinguish null characters that are part of the line from the null character inserted as a terminator. -This function is a GNU extension, but it is the recommended way to read -lines from a stream. The alternative standard functions are unreliable. +This function was originally a GNU extension, but was added in +POSIX.1-2008. If an error occurs or end of file is reached without any bytes read, -@code{getline} returns @code{-1}. +@code{getline} returns @code{-1}. POSIX leaves the contents of +@code{*@var{lineptr}} undefined when @code{getline} returns @code{-1}. +If the @glibcadj{} implementation of @code{getline} allocates the +initial buffer it will null terminate it to prevent the caller from +reading uninitialized memory if no characters can be read from +@code{stream}. @end deftypefun -@deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream}) -@standards{GNU, stdio.h} +@deftypefun ssize_t getdelim (char **restrict @var{lineptr}, size_t *restrict @var{n}, int @var{delimiter}, FILE *restrict @var{stream}) +@standards{POSIX.1-2008, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c See the getline @acucorrupt note. This function is like @code{getline} except that the character which @@ -1294,6 +1300,9 @@ The text is stored in @var{lineptr}, including the delimiter character and a terminating null. Like @code{getline}, @code{getdelim} makes @var{lineptr} bigger if it isn't big enough. +This function was originally a GNU extension, but was added in +POSIX.1-2008. + @code{getline} is in fact implemented in terms of @code{getdelim}, just like this: @@ -3514,8 +3523,8 @@ If you are trying to read input that doesn't match a single, fixed pattern, you may be better off using a tool such as Flex to generate a lexical scanner, or Bison to generate a parser, rather than using @code{scanf}. For more information about these tools, see @ref{Top, , , -flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , , -bison.info, The Bison Reference Manual}. +flex, Flex: The Lexical Scanner Generator}, and @ref{Top, , , bison, The +Bison Reference Manual}. @node Input Conversion Syntax @subsection Input Conversion Syntax @@ -5131,13 +5140,21 @@ remain valid only as long as no further output on the stream takes place. If you do more output, you must flush the stream again to store new values before you use them again. -A null character is written at the end of the buffer. This null character -is @emph{not} included in the size value stored at @var{sizeloc}. +A null character is written at the end of the buffer when the stream +is flushed, and at the current location when closed (these locations +may be different if @code{fseek} is used). This null character is +@emph{not} included in the size value stored at @var{sizeloc}. You can move the stream's file position with @code{fseek} or -@code{fseeko} (@pxref{File Positioning}). Moving the file position past -the end of the data already written fills the intervening space with -zeroes. +@code{fseeko} (@pxref{File Positioning}). Moving the file position +past the end of the data already written fills the intervening space +with zeroes. Note that seeking backwards into existing written data +will change the effective ``end of file'' used by @code{fflush} and +@code{SEEK_END} (and where the trailing null character is written, +when closed). Thus, if you wish to do ``random-access'' I/O in a +memstream, it's important to use @code{fseek} to move the file +position to the desired data end (using @code{SEEK_POS}) before +closing it. @end deftypefun Here is an example of using @code{open_memstream}: diff --git a/manual/string.texi b/manual/string.texi index feba0b7..24004f1 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -1802,6 +1802,15 @@ This function finds the first occurrence of the byte @var{c} (converted to an @code{unsigned char}) in the initial @var{size} bytes of the object beginning at @var{block}. The return value is a pointer to the located byte, or a null pointer if no match was found. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{block} has a type +that is a pointer to a @code{const}-qualified object type, +@code{memchr} returns @code{const void *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{void *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wmemchr (const wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size}) @@ -1811,6 +1820,15 @@ This function finds the first occurrence of the wide character @var{wc} in the initial @var{size} wide characters of the object beginning at @var{block}. The return value is a pointer to the located wide character, or a null pointer if no match was found. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{block} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wmemchr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {void *} rawmemchr (const void *@var{block}, int @var{c}) @@ -1869,6 +1887,15 @@ When @code{strchr} returns a null pointer, it does not let you know the position of the terminating null byte it has found. If you need that information, it is better (but less portable) to use @code{strchrnul} than to search for it a second time. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{string} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strchr} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcschr (const wchar_t *@var{wstring}, wchar_t @var{wc}) @@ -1884,6 +1911,15 @@ string, so you can use this function get a pointer to the end of a wide string by specifying a null wide character as the value of the @var{wc} argument. It would be better (but less portable) to use @code{wcschrnul} in this case, though. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{wstring} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcschr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {char *} strchrnul (const char *@var{string}, int @var{c}) @@ -1943,6 +1979,15 @@ For example, strrchr ("hello, world", 'l') @result{} "ld" @end smallexample + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{string} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strrchr} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcsrchr (const wchar_t *@var{wstring}, wchar_t @var{wc}) @@ -1951,6 +1996,15 @@ strrchr ("hello, world", 'l') The function @code{wcsrchr} is like @code{wcschr}, except that it searches backwards from the end of the string @var{wstring} (instead of forwards from the front). + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{wstring} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcsrchr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {char *} strstr (const char *@var{haystack}, const char *@var{needle}) @@ -1969,6 +2023,15 @@ strstr ("hello, world", "l") strstr ("hello, world", "wo") @result{} "world" @end smallexample + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{haystack} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strstr} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcsstr (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) @@ -1979,6 +2042,15 @@ substring @var{needle} rather than just a single wide character. It returns a pointer into the string @var{haystack} that is the first wide character of the substring, or a null pointer if no match was found. If @var{needle} is an empty string, the function returns @var{haystack}. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{haystack} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcsstr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcswcs (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) @@ -2104,6 +2176,15 @@ strpbrk ("hello, world", " \t\n,.;!?") In a multibyte string, characters consisting of more than one byte are not treated as single entities. Each byte is treated separately. The function is not locale-dependent. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{string} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strpbrk} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcspbrk (const wchar_t *@var{wstring}, const wchar_t *@var{stopset}) @@ -2114,6 +2195,15 @@ related to @code{wcscspn}, except that it returns a pointer to the first wide character in @var{wstring} that is a member of the set @var{stopset} instead of the length of the initial substring. It returns a null pointer if no such wide character from @var{stopset} is found. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{wstring} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcspbrk} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @@ -2436,8 +2526,8 @@ heap object containing the sensitive data after it's deallocated. Since erasure is a precaution against bugs, this optimization is inappropriate. -The function @code{explicit_bzero} erases a block of memory, and -guarantees that the compiler will not remove the erasure as +The functions @code{explicit_bzero} and @code{memset_explicit} erase a +block of memory, and guarantee that the compiler will not remove the erasure as ``unnecessary.'' @smallexample @@ -2463,16 +2553,18 @@ void encrypt_with_phrase (const char *phrase, const char *in, In this example, if @code{memset}, @code{bzero}, or a hand-written loop had been used, the compiler might remove them as ``unnecessary.'' -@strong{Warning:} @code{explicit_bzero} does not guarantee that +@strong{Warning:} @code{explicit_bzero} and @code{memset_explicit} do +not guarantee that sensitive data is @emph{completely} erased from the computer's memory. There may be copies in temporary storage areas, such as registers and ``scratch'' stack space; since these are invisible to the source code, a library function cannot erase them. -Also, @code{explicit_bzero} only operates on RAM. If a sensitive data -object never needs to have its address taken other than to call -@code{explicit_bzero}, it might be stored entirely in CPU registers -@emph{until} the call to @code{explicit_bzero}. Then it will be +Also, @code{explicit_bzero} and @code{memset_explicit} only operate on +RAM. If a sensitive data object never needs to have its address taken +other than to call @code{explicit_bzero} or @code{memset_explicit}, it +might be stored entirely in CPU registers @emph{until} the call to +@code{explicit_bzero} or @code{memset_explicit}. Then it will be copied into RAM, the copy will be erased, and the original will remain intact. Data in RAM is more likely to be exposed by a bug than data in registers, so this creates a brief window where the data is at @@ -2489,10 +2581,12 @@ variable itself is not @code{volatile}, some compilers will ignore the qualification on the pointer and remove the erasure anyway. Having said all that, in most situations, using @code{explicit_bzero} +or @code{memset_explicit} is better than not using it. At present, the only way to do a more thorough job is to write the entire sensitive operation in assembly language. We anticipate that future compilers will recognize calls to -@code{explicit_bzero} and take appropriate steps to erase all the +@code{explicit_bzero} or @code{memset_explicit} and take appropriate +steps to erase all the copies of the affected data, wherever they may be. @deftypefun void explicit_bzero (void *@var{block}, size_t @var{len}) @@ -2520,6 +2614,25 @@ functionality under a different name, such as @code{explicit_memset}, systems it may be in @file{strings.h} instead. @end deftypefun +@deftypefun {void *} memset_explicit (void *@var{block}, int @var{c}, size_t @var{size}) +@standards{C23, string.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +This function copies the value of @var{c} (converted to an +@code{unsigned char}) into each of the first @var{size} bytes of the +object beginning at @var{block}, just as @code{memset} would. It +returns the value of @var{block}. The bytes are always written, even +if the compiler could determine that this is ``unnecessary'' because +no correct program could read them back. + +@strong{Note:} The @emph{only} optimization that @code{memset_explicit} +disables is removal of ``unnecessary'' writes to memory. The compiler +can perform all the other optimizations that it could for a call to +@code{memset}. For instance, it may replace the function call with +inline memory writes, and it may assume that @var{block} cannot be a +null pointer. +@end deftypefun + @node Shuffling Bytes @section Shuffling Bytes diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi index 1ca77ad..a97e372 100644 --- a/manual/sysinfo.texi +++ b/manual/sysinfo.texi @@ -145,7 +145,7 @@ This process cannot set the host name because it is not privileged. @end table @end deftypefun -@deftypefun int getdomainnname (char *@var{name}, size_t @var{length}) +@deftypefun int getdomainname (char *@var{name}, size_t @var{length}) @standards{???, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Syscalls uname, then strlen and memcpy. diff --git a/manual/terminal.texi b/manual/terminal.texi index b437cb5..8f4bb84 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -13,6 +13,7 @@ Most of the functions in this chapter operate on file descriptors. descriptor is and how to open a file descriptor for a terminal device. @menu +* Terminal Device Model:: The fundamental concepts of a terminal device * Is It a Terminal:: How to determine if a file is a terminal device, and what its name is. * I/O Queues:: About flow control and typeahead. @@ -28,6 +29,83 @@ descriptor is and how to open a file descriptor for a terminal device. * Pseudo-Terminals:: How to open a pseudo-terminal. @end menu +@node Terminal Device Model +@section Terminal Device Model +@cindex terminal model + +A @dfn{terminal device}, abbreviated @code{tty} (for @dfn{teletype}), is +a character device which implements a set of functionality appropriate +for communications devices, and which can host an interactive login +session. Conceptually, a terminal device implements an RS232 +asynchronous serial interface, but the actual hardware implementation +may be entirely different, or it may be entirely virtual, notably +@pxref{Pseudo-Terminals}. + +For a true conventional asynchronous serial port, such as RS232/V.24, +RS422/V.11, RS423, or RS485, the functionality is generally as +described, whereas for other devices, the meaning of serial port +specific functionality such as modem control signals, BREAK, and line +speed is device specific. + +The rest of this section is described in terms of a physical RS232 +interface. + +The RS232 specification assumes the host (Data Terminal Equipment, DTE) +connects to a modem (Data Communications Equipment, DCE), regardless of +if a physical modem is present or not. + +In addition to the serial data, the DTE provides a set of control +signals to the DCE, and the DCE a set of status signals to the DTE. The +full RS232 and V.24 specifications provide a large number of signals, +but the ones that are typically implemented in contemporary hardware and +are relevant to the terminal device interface are: + +@table @asis +@item DTR - Data Terminal Ready (control) + +If asserted (true), the DTE is ready to accept/continue an incoming +communications session. If deasserted (false), this is a +@dfn{modem disconnect request} to the DCE. The DCE may, but is not +required to, trigger a modem disconnect in response. +@cindex modem disconnect request + +@item RTS - Request To Send (control) + +This signal is also referred to as Ready To Receive (RTR). + +If asserted, the DTE is ready to accept data. If deasserted, the DCE is +requested to hold data temporarily without disconnecting. This is known +as hardware or RTS/CTS @dfn{flow control} and can be handled +automatically if the appropriate terminal mode flags are set. + +@item DSR - Data Set Ready (status) + +If asserted, the DCE is ready to communicate, but may or may not have a +connection to a remote peer. + +@item DCD - Data Carrier Detect (status) + +If asserted, the DCE has a connection to the remote peer. If +deasserted, this is a @dfn{modem disconnect} signal to the DTE. A modem +disconnect may be triggered in response to the DTR control signal being +deasserted, or it may be caused by an external event. +@cindex modem disconnect + +@item CTS - Clear To Send (status) + +If asserted, the DCE is ready to accept data. If deasserted, the DTE is +requested to hold data temporarily but should not interpret it as a +disconnect. This is the DCE to DTE part of RTS/CTS flow +control. + +@item RI - Ring Indicator (status) + +If asserted, this indicates that a remote peer is requesting to connect +(``the phone is ringing''). Depending on how the DCE is configured, the +DTE may need to assert the DTR control signal before the DCE will accept +the incoming connection. +@end table + @node Is It a Terminal @section Identifying Terminals @cindex terminal identification @@ -685,8 +763,10 @@ clear the condition. @deftypevr Macro tcflag_t HUPCL @standards{POSIX.1, termios.h} -If this bit is set, a modem disconnect is generated when all processes -that have the terminal device open have either closed the file or exited. +If this bit is set, a modem disconnect request is generated when all +processes that have the terminal device open have either closed the file +or exited. +@cindex modem disconnect request @end deftypevr @deftypevr Macro tcflag_t CREAD @@ -771,11 +851,11 @@ If this bit is set, it says to ignore the control modes and line speed values entirely. This is only meaningful in a call to @code{tcsetattr}. The @code{c_cflag} member and the line speed values returned by -@code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the -call. @code{CIGNORE} is useful if you want to set all the software -modes in the other members, but leave the hardware details in -@code{c_cflag} unchanged. (This is how the @code{TCSASOFT} flag to -@code{tcsettattr} works.) +@code{cfgetispeed}, @code{cfgetospeed}, @code{cfgetibaud} and +@code{cfsetibaud} will be unaffected by the call. @code{CIGNORE} is +useful if you want to set all the software modes in the other members, +but leave the hardware details in @code{c_cflag} unchanged. (This is +how the @code{TCSASOFT} flag to @code{tcsetattr} works.) This bit is never set in the structure filled in by @code{tcgetattr}. @end deftypevr @@ -965,106 +1045,82 @@ bit remains set until reprinting is finished. @xref{Editing Characters}. The terminal line speed tells the computer how fast to read and write data on the terminal. -If the terminal is connected to a real serial line, the terminal speed -you specify actually controls the line---if it doesn't match the -terminal's own idea of the speed, communication does not work. Real -serial ports accept only certain standard speeds. Also, particular -hardware may not support even all the standard speeds. Specifying a -speed of zero hangs up a dialup connection and turns off modem control -signals. - -If the terminal is not a real serial line (for example, if it is a -network connection), then the line speed won't really affect data -transmission speed, but some programs will use it to determine the -amount of padding needed. It's best to specify a line speed value that -matches the actual speed of the actual terminal, but you can safely -experiment with different values to vary the amount of padding. +For standard asynchronous serial lines employing binary NRZ encoding +such as RS232, RS422, RS423, or RS485, the terminal speed will equal the +physical layer baud rate including asynchronous framing and parity bits. +This needs to match the communication speed expected by the peer device, +or communication will not work. Which particular speeds are supported +by any particular interface is hardware specific. + +For other types of devices the meaning of the line speed is +device-specific and may not even affect the actual data transmission +speed at all (for example, if it is a pseudo-terminal or network +connection), but some programs will use it to determine the amount of +padding needed. It's best to specify a line speed value that matches +the actual speed of the actual terminal, but you can safely experiment +with different values to vary the amount of padding. + +As the terminal interface models an RS232 serial interface +(@pxref{Terminal Device Model}), the term ``baud rate'' is frequently +used as a direct alias for ``line speed''; this convention is followed +in the following descriptions. There are actually two line speeds for each terminal, one for input and one for output. You can set them independently, but most often -terminals use the same speed for both directions. +terminals use the same speed for both directions. If the hardware does +not support different speeds for each direction, the output speed will +be used for both input and output. -The speed values are stored in the @code{struct termios} structure, but -don't try to access them in the @code{struct termios} structure -directly. Instead, you should use the following functions to read and -store them: +Specifying an output speed of zero generates a modem disconnect request. +For the @code{speed_t} interface, this is the constant @code{B0} which +may or may not have the numeric value @math{0}. -@deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Direct access to a single termios field, except on Linux, where -@c multiple accesses may take place. No worries either way, callers -@c must ensure mutual exclusion on such non-opaque types. -This function returns the output line speed stored in the structure -@code{*@var{termios-p}}. -@end deftypefun - -@deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function returns the input line speed stored in the structure -@code{*@var{termios-p}}. -@end deftypefun - -@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function stores @var{speed} in @code{*@var{termios-p}} as the output -speed. The normal return value is @math{0}; a value of @math{-1} -indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} -returns @math{-1}. -@end deftypefun +Specifying an input speed value of zero sets the input speed to equal +the output speed. This is the numeric constant @math{0} (not +necessarily the same as @code{B0}) for both the @code{speed_t} and +@code{baud_t} interfaces. This use is deprecated. -@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function stores @var{speed} in @code{*@var{termios-p}} as the input -speed. The normal return value is @math{0}; a value of @math{-1} -indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} -returns @math{-1}. -@end deftypefun - -@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed}) -@standards{BSD, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c There's no guarantee that the two calls are atomic, but since this is -@c not an opaque type, callers ought to ensure mutual exclusion to the -@c termios object. - -@c cfsetspeed ok -@c cfsetispeed ok -@c cfsetospeed ok -This function stores @var{speed} in @code{*@var{termios-p}} as both the -input and output speeds. The normal return value is @math{0}; a value -of @math{-1} indicates an error. If @var{speed} is not a speed, -@code{cfsetspeed} returns @math{-1}. This function is an extension in -4.4 BSD. -@end deftypefun +The line speed values are stored in the @code{struct termios} structure, but +don't try to access them in the @code{struct termios} structure +directly. Instead, you should use the functions defined by the +interfaces below to access them. + +The line speed setting functions report errors only when attempting to +set line rate values that the system simply cannot handle. If you +specify a line speed value that is plausible for the system, then the +functions will succeed. However, they do not check that a particular +hardware device can actually support the specified value---in fact, they +don't know which device you plan to set the line speed for until +@code{tcsetattr} is called. If you use @code{tcsetattr} to set the +speed of a particular device to a value that it cannot handle, either +@code{tcsetattr} returns @math{-1} and sets @code{errno} to +@code{EINVAL}, or the value is adjusted to the closest supported value, +depending on the policy of the kernel driver. In the latter case, a +subsequent call to @code{tcgetattr} may or may not reflect this +adjustment. + +@Theglibc{} supports two interoperable interfaces for setting the line +speed: the POSIX.1 @code{speed_t} interface, which requires the use of a +set of enumerated constants, and the @code{baud_t} interface, a GNU +extension, which is guaranteed to use plain numeric values. + +@subsubsection The @code{speed_t} interface @deftp {Data Type} speed_t @standards{POSIX.1, termios.h} The @code{speed_t} type is an unsigned integer data type used to represent line speeds. -@end deftp -The functions @code{cfsetospeed} and @code{cfsetispeed} report errors -only for speed values that the system simply cannot handle. If you -specify a speed value that is basically acceptable, then those functions -will succeed. But they do not check that a particular hardware device -can actually support the specified speeds---in fact, they don't know -which device you plan to set the speed for. If you use @code{tcsetattr} -to set the speed of a particular device to a value that it cannot -handle, @code{tcsetattr} returns @math{-1}. - -@strong{Portability note:} In @theglibc{}, the functions above -accept speeds measured in bits per second as input, and return speed -values measured in bits per second. Other libraries require speeds to -be indicated by special codes. For POSIX.1 portability, you must use +@strong{Portability note:} In the current version of @theglibc{}, the +@code{speed_t} type is numerically indentical to the line speed rate. +Other libraries and older versions of @theglibc{} may require speeds to +be indicated by enumerated constants, which may not be numerically +identical to the requested line speed. For portability, you must use one of the following symbols to represent the speed; their precise numeric values are system-dependent, but each name has a fixed meaning: @code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on. -There is no portable way to represent any speed but these, but these are -the only speeds that typical serial lines can support. +There is no portable way to represent any speed but these. +@end deftp @comment termios.h @comment POSIX.1 @@ -1114,23 +1170,92 @@ the only speeds that typical serial lines can support. @comment termios.h @comment POSIX.1 @vindex B38400 +@smallexample +B0 B50 B75 B110 B134 B150 B200 B300 B600 B1200 +B1800 B2400 B4800 B9600 B19200 B38400 +@end smallexample + +@Theglibc{} defines these additional constants: + +@comment termios.h +@comment GNU +@vindex B7200 +@comment termios.h +@comment GNU +@vindex B14400 +@comment termios.h +@comment GNU +@vindex B28800 +@comment termios.h +@comment GNU +@vindex B33600 @comment termios.h @comment GNU @vindex B57600 @comment termios.h @comment GNU +@vindex B76800 +@comment termios.h +@comment GNU @vindex B115200 @comment termios.h @comment GNU +@vindex B153600 +@comment termios.h +@comment GNU @vindex B230400 @comment termios.h @comment GNU +@vindex B307200 +@comment termios.h +@comment GNU @vindex B460800 +@comment termios.h +@comment GNU +@vindex B500000 +@comment termios.h +@comment GNU +@vindex B576000 +@comment termios.h +@comment GNU +@vindex B614400 +@comment termios.h +@comment GNU +@vindex B921600 +@comment termios.h +@comment GNU +@vindex B1000000 +@comment termios.h +@comment GNU +@vindex B1152000 +@comment termios.h +@comment GNU +@vindex B1500000 +@comment termios.h +@comment GNU +@vindex B2000000 +@comment termios.h +@comment GNU +@vindex B2500000 +@comment termios.h +@comment GNU +@vindex B3000000 +@comment termios.h +@comment GNU +@vindex B3500000 +@comment termios.h +@comment GNU +@vindex B4000000 +@comment termios.h +@comment GNU +@vindex B5000000 +@comment termios.h +@comment GNU +@vindex B10000000 @smallexample -B0 B50 B75 B110 B134 B150 B200 -B300 B600 B1200 B1800 B2400 B4800 -B9600 B19200 B38400 B57600 B115200 -B230400 B460800 +B7200 B14400 B28800 B33600 B57600 B76800 B115200 B153600 B230400 B307200 +B460800 B500000 B576000 B614400 B921600 B1000000 B1152000 B1500000 +B2000000 B2500000 B3000000 B3500000 B4000000 B5000000 B10000000 @end smallexample @vindex EXTA @@ -1139,6 +1264,172 @@ BSD defines two additional speed symbols as aliases: @code{EXTA} is an alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}. These aliases are obsolete. +@deftypevr Macro speed_t SPEED_MAX +@standards{GNU, termios.h} + +@Theglibc{} defines the constant @code{SPEED_MAX} for the largest valid +value of type @code{speed_t}. This value may be smaller than the +underlying C type can store. + +For compatiblity with some other platforms the alias @code{__MAX_BAUD} +is defined for this constant. +@end deftypevr + +@deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field. However, this may not be +@c true on other implementations; callers must ensure mutual exclusion +@c on such non-opaque types. +This function returns the output line speed stored in the structure +@code{*@var{termios-p}}. +@end deftypefun + +@deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function returns the input line speed stored in the structure +@code{*@var{termios-p}}. +@end deftypefun + +@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field, except on Linux, where two +@c fields are accessed, one of which (c_cflag) is read-modify-write. No +@c worries either way, callers must ensure mutual exclusion on such +@c non-opaque types. +This function stores @var{speed} in @code{*@var{termios-p}} as the +output line speed. If @var{speed} is @code{B0}, generates a modem +disconnect request. + +If @var{speed} is neither a plausible line speed nor @code{B0}, +@code{cfsetospeed} returns @math{-1} and sets @code{errno} to +@code{EINVAL}. +@end deftypefun + +@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function stores @var{speed} in @code{*@var{termios-p}} as the input +speed. If @var{speed} is @math{0}, the input speed is set to equal the +output speed; note that POSIX.1 specifies this as the numeric value +@math{0} which is not required to equal the constant @code{B0}. + +If @var{speed} is not a plausible line speed or @math{0}, +@code{cfsetispeed} returns @math{-1} and sets @code{errno} to +@code{EINVAL}. + +@strong{Portability note:} POSIX.1-2024 has deprecated setting of the +input speed to @math{0} to set the input line speed to equal the output +line speed. After calling @code{tcsetattr} followed by +@code{tcgetattr}, @code{cfgetispeed} may report the input line speed +either as @math{0} or the same as @code{cfgetospeed}. +@end deftypefun + +@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{BSD, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c There's no guarantee that the two calls are atomic, but since this is +@c not an opaque type, callers ought to ensure mutual exclusion to the +@c termios object. + +@c cfsetspeed ok +@c cfsetispeed ok +@c cfsetospeed ok +This function stores @var{speed} in @code{*@var{termios-p}} as both the +input and output speeds. + +If @var{baud} is not a plausible line speed, @code{cfsetbaud} returns +@math{-1} and sets @code{errno} to @code{EINVAL}. + +This function is an extension which originated in 4.4 BSD. +@end deftypefun + +@subsubsection The @code{baud_t} interface + +@deftp {Data Type} baud_t +@standards{GNU, termios.h} +The @code{baud_t} type is a numeric data type used to represent line +baud rates. It will always represent the actual numeric value +corresponding to the line speed, unlike @code{speed_t}. In the current +version of @theglibc{} this is the same type as @code{speed_t}, but this +may not be the case in future versions or on other implementations; it +is specifically not guaranteed to be an integer type. +@end deftp + +@deftypevr Macro baud_t BAUD_MAX +@standards{GNU, termios.h} +The constant @code{BAUD_MAX} is defined to the maximum valid value of +type @code{baud_t}. This value may be smaller than the underlying C +type can store. +@end deftypevr + +@deftypefun baud_t cfgetobaud (const struct termios *@var{termios-p}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field. However, this may not be +@c true on other implementations; callers must ensure mutual exclusion +@c on such non-opaque types. +This function returns the output line speed stored in the structure +@code{*@var{termios-p}} as a numeric value. +@end deftypefun + +@deftypefun baud_t cfgetibaud (const struct termios *@var{termios-p}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function returns the input line speed stored in the structure +@code{*@var{termios-p}} as a numeric value. +@end deftypefun + +@deftypefun int cfsetobaud (struct termios *@var{termios-p}, baud_t @var{baud}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field, except on Linux, where two +@c fields are accessed, one of which (c_cflag) is read-modify-write. No +@c worries either way, callers must ensure mutual exclusion on such +@c non-opaque types. +This function stores @var{baud} in @code{*@var{termios-p}} as the output +line speed. If @var{baud} is @math{0}, generates a modem disconnect. + +If @var{speed} is not a plausible line speed, @code{cfsetspeed} returns +@math{-1} and sets @code{errno} to @code{EINVAL}. +@end deftypefun + +@deftypefun int cfsetibaud (struct termios *@var{termios-p}, baud_t @var{baud}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function stores @var{baud} in @code{*@var{termios-p}} as the input +line speed. + +To simplify conversions from the @code{speed_t} interface, setting the +input line speed to @math{0} is interpreted as setting the input line +speed equal to the output line speed. The caveats described under +@code{cfsetispeed} apply equally to @code{cfsetibaud}. As for +@code{cfsetispeed}, this usage is deprecated. + +If @var{baud} is not a plausible line speed or @math{0}, +@code{cfsetibaud} returns @math{-1} and sets @code{errno} to +@code{EINVAL}. +@end deftypefun + +@deftypefun int cfsetbaud (struct termios *@var{termios-p}, baud_t @var{baud}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c There's no guarantee that the two calls are atomic, but since this is +@c not an opaque type, callers should ensure mutual exclusion to the +@c termios object. + +@c cfsetbaud ok +@c cfsetibaud ok +@c cfsetobaud ok +This function stores @var{baud} in @code{*@var{termios-p}} as both the +input and output line speeds. + +If @var{baud} is not a plausible line speed, @code{cfsetbaud} returns +@math{-1} and sets @code{errno} to @code{EINVAL}. +@end deftypefun + @node Special Characters @subsection Special Characters diff --git a/manual/threads.texi b/manual/threads.texi index 67955e1..b9d1247 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -23,8 +23,15 @@ POSIX threads. This section describes the @glibcadj{} ISO C threads implementation. To have a deeper understanding of this API, it is strongly recommended to read ISO/IEC 9899:2011, section 7.26, in which ISO C threads were -originally specified. All types and function prototypes are declared -in the header file @file{threads.h}. +originally specified. + +All types and function prototypes are declared in the header file +@file{threads.h}. When compiling for C, some functionality is also +available in @file{stdlib.h}. + +It is recommended that GNU systems use the functionality in +@file{pthread.h} instead of @file{thread.h}, as they are more portable +between C and C++. @menu * ISO C Threads Return Values:: Symbolic constants that represent a @@ -203,11 +210,17 @@ called once in the presence of multiple, potentially calling threads. @deftp {Data Type} once_flag @standards{C11, threads.h} A complete object type capable of holding a flag used by @code{call_once}. + +As of C23, @code{once_flag} is also defined in @file{stdlib.h}, +but only for C, not for C++. @end deftp @defvr Macro ONCE_FLAG_INIT @standards{C11, threads.h} This value is used to initialize an object of type @code{once_flag}. + +As of C23, @code{ONCE_FLAG_INIT} is also defined in @file{stdlib.h}, +but only for C, not for C++. @end defvr @deftypefun void call_once (once_flag *@var{flag}, void (*@var{func}) (void)) @@ -219,6 +232,9 @@ invoked from several threads. The completion of the function @code{call_once} with the same @code{flag} variable. @end deftypefun +These definitions are from C11, where they appear in @file{threads.h}. +In C23, they appear in @file{stdlib.h} as well as in @file{threads.h}. + @node ISO C Mutexes @subsection Mutexes @@ -552,16 +568,99 @@ get different values identified by the same key. On failure, This section describes the @glibcadj{} POSIX Threads implementation. @menu +* Creating and Destroying Threads:: * Thread-specific Data:: Support for creating and managing thread-specific data * Waiting with Explicit Clocks:: Functions for waiting with an explicit clock specification. * POSIX Semaphores:: Support for process and thread synchronization using semaphores +* POSIX Barriers:: Support for process and thread + synchronization using barriers +* POSIX Spin Locks:: Support for process and thread + synchronization using spinlocks +* POSIX Mutexes:: Support for mutual exclusion +* POSIX Threads Other APIs:: Other Standard functions * Non-POSIX Extensions:: Additional functions to extend POSIX Thread functionality @end menu +@node Creating and Destroying Threads +@subsection Creating and Destroying Threads + +@deftypefun int pthread_create (pthread_t *@var{newthread}, const pthread_attr_t *@var{attr}, void *(*@var{start_routine}) (void *), void *@var{arg}) +This function creates a new thread with attributes @var{attr}. This +thread will call @var{start_routine} and pass it @var{arg}. If +@var{start_routine} returns, the thread will exit and the return value +will become the thread's exit value. The new thread's ID is stored in +@var{newthread}. Returns 0 on success. +@manpagefunctionstub{pthread_create, 3} +@end deftypefun + +@deftypefun int pthread_detach (pthread_t @var{th}) +Indicates that thread @var{th} must clean up after itself +automatically when it exits, as the parent thread will not call +@code{pthread_join} on it. +@manpagefunctionstub{pthread_detach, 3} +@end deftypefun + +@deftypefun int pthread_join (pthread_t @var{th}, void **@var{thread_return}) +Waits for thread @var{th} to exit, and stores its return value in +@var{thread_return}. +@manpagefunctionstub{pthread_join, 3} +@end deftypefun + +@deftypefun int pthread_kill (pthread_t @var{th}, int @var{signal}) +Sends signal @var{signal} to thread @var{th}. +@manpagefunctionstub{pthread_kill, 3} +@end deftypefun + +@deftypefun pthread_t pthread_self (void) +Returns the ID of the thread which performed the call. +@manpagefunctionstub{pthread_self, 3} +@end deftypefun + +Each thread has a set of attributes which are passed to +@code{pthread_create} via the @code{pthread_attr_t} type, which should +be considered an opaque type. + +@deftypefun int pthread_attr_init (pthread_attr_t *@var{attr}) +Initializes @var{attr} to its default values and allocates any +resources required. Once initialized, @var{attr} can be modified by +other @code{pthread_attr_*} functions, or used by +@code{pthread_create}. +@manpagefunctionstub{pthread_attr_init, 3} +@end deftypefun + +@deftypefun int pthread_attr_destroy (pthread_attr_t *@var{attr}) +When no longer needed, @var{attr} should be destroyed with this +function, which releases any resources allocated. Note that +@var{attr} is only needed for the @code{pthread_create} call, not for +the running thread itself. +@manpagefunctionstub{pthread_attr_destroy, 3} +@end deftypefun + +@deftypefun int pthread_attr_setdetachstate (pthread_attr_t *@var{attr}, int @var{detachstate}) +Sets the detach state attribute for @var{attr}. This attribute may be one of the following: + +@table @code +@item PTHREAD_CREATE_DETACHED +Causes the created thread to be detached, that is, as if +@code{pthread_detach} had been called on it. + +@item PTHREAD_CREATE_JOINABLE +Causes the created thread to be joinable, that is, @code{pthread_join} +must be called on it. +@end table + +@manpagefunctionstub{pthread_attr_setdetachstate, 3} +@end deftypefun + +@deftypefun int pthread_attr_getdetachstate (const pthread_attr_t *@var{attr}, int *@var{detachstate}) +Gets the detach state attribute from @var{attr}. +@manpagefunctionstub{pthread_attr_getdetachstate, 3} +@end deftypefun + @node Thread-specific Data @subsection Thread-specific Data @@ -769,6 +868,272 @@ against the clock specified by @var{clockid} rather than @end deftypefun +@node POSIX Barriers +@subsection POSIX Barriers + +A POSIX barrier works as follows: a file-local or global +@code{pthread_barrier_t} object is initialized via +@code{pthread_barrier_init} to require @var{count} threads to wait on +it. After that, up to @var{count}-1 threads will wait on the barrier +via @code{pthread_barrier_wait}. None of these calls will return +until @var{count} threads are waiting via the next call to +@code{pthread_barrier_wait}, at which point, all of these calls will +return. The net result is that @var{count} threads will be +synchronized at that point. At some point after this, the barrier is +destroyed via @code{pthread_barrier_destroy}. Note that a barrier +must be destroyed before being re-initialized, to ensure that all +threads are properly synchronized, but need not be destroyed and +re-initialized before being reused. + +@deftypefun int pthread_barrier_init (pthread_barrier_t *@var{barrier}, const pthread_barrierattr_t *@var{attr}, unsigned int @var{count}) +@standards{POSIX, pthread.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +This function initializes a barrier to synchronize @var{count} +threads. The barrier must be uninitialized or destroyed before it is +initialized; attempting to initialize an in-use barrier results in +undefined behavior. + +The @var{attr} argument to @code{pthread_barrier_init} is typically +NULL for a process-private barrier, but may be used to share a barrier +across processes (documentation TBD). + +On success, 0 is returned. On error, one of the following is returned: + +@table @code +@item EINVAL +Either @var{count} is zero, or is large enough to cause an internal +overflow. +@end table + +@end deftypefun + +@deftypefun int pthread_barrier_wait (pthread_barrier_t *@var{barrier}) +@standards{POSIX, pthread.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +This function synchronizes threads. The first @var{count}-1 threads +that wait on @var{barrier} will just wait. The next thread that waits +on @var{barrier} will cause all @var{count} threads' calls to return. +The @var{barrier} must be initialized with @code{pthread_barrier_init} +and not yet destroyed with @code{pthread_barrier_destroy}. + +The return value of this function is +@code{PTHREAD_BARRIER_SERIAL_THREAD} for one thread (it is unspecified +which thread) and 0 for the remainder, for each batch of @var{count} +threads synchronized. After such a batch is synchronized, the +@var{barrier} will begin synchronizing the next @var{count} threads. + +@end deftypefun + + +@deftypefun int pthread_barrier_destroy (pthread_barrier_t *@var{barrier}) +@standards{POSIX, pthread.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +Destroys @var{barrier} and releases any resources it may have +allocated. A barrier must not be destroyed if any thread is waiting +on it, or if it was not initialized. This call always succeeds and +returns 0. + +@end deftypefun + +@node POSIX Spin Locks +@subsection POSIX Spin Locks + +A spinlock is a low overhead lock suitable for use in a realtime +thread where it's known that the thread won't be paused by the +scheduler. Non-realtime threads should use mutexes instead. + +@deftypefun int pthread_spin_init (pthread_spinlock_t *@var{lock}, int @var{pshared}) +Initializes a spinlock. @var{pshared} is one of: + +@table @code +@item PTHREAD_PROCESS_PRIVATE +This spinlock is private to the process which created it. + +@item PTHREAD_PROCESS_SHARED +This spinlock is shared across any process that can access it, for +example through shared memory. +@end table + +@manpagefunctionstub{pthread_spin_init, 3} +@end deftypefun + +@deftypefun int pthread_spin_destroy (pthread_spinlock_t *@var{lock}) +Destroys a spinlock and releases any resources it held. +@manpagefunctionstub{pthread_spin_destroy, 3} +@end deftypefun + +@deftypefun int pthread_spin_lock (pthread_spinlock_t *@var{lock}) +Locks a spinlock. Only one thread at a time can lock a spinlock. If +another thread has locked this spinlock, the calling thread waits +until it is unlocked, then attempts to lock it. +@manpagefunctionstub{pthread_spin_lock, 3} +@end deftypefun + +@deftypefun int pthread_spin_unlock (pthread_spinlock_t *@var{lock}) +Unlocks a spinlock. If one or more threads are waiting for the lock +to be unlocked, one of them (unspecified which) will succeed in +locking it, and will return from @code{pthread_spin_lock}). +@manpagefunctionstub{pthread_spin_unlock, 3} +@end deftypefun + +@deftypefun int pthread_spin_trylock (pthread_spinlock_t *@var{lock}) +Like @code{pthread_spin_unlock} but returns 0 if the lock was +unlocked, or EBUSY if it was locked. +@manpagefunctionstub{pthread_spin_trylock, 3} +@end deftypefun + +@node POSIX Mutexes +@subsection POSIX Mutexes + +A @emph{mutex}, or ``mutual exclusion'', is a way of guaranteeing that +only one thread at a time is able to execute a protected bit of code +(or access any other resource). Two or more threads trying to execute +the same code at the same time, will instead take turns, according to +the mutex. + +A mutex is much like a spinlock, but implemented in a way that is more +appropriate for use in non-realtime threads, and is more +resource-conserving. + +@deftypefun int pthread_mutex_init (pthread_mutex_t *@var{mutex}, const pthread_mutexattr_t *@var{mutexattr}) +Initiailizes a mutex. +@manpagefunctionstub{pthread_mutex_init, 3} +@end deftypefun + +@deftypefun int pthread_mutex_destroy (pthread_mutex_t *@var{mutex}) +Destroys a no-longer-needed mutex. +@manpagefunctionstub{pthread_mutex_destroy, 3} +@end deftypefun + +@deftypefun int pthread_mutex_lock (pthread_mutex_t *@var{mutex}) +Only one thread at a time may lock @var{mutex}, and must unlock it +when appropriate. If a thread calls @code{pthread_mutex_lock} while +@var{mutex} is locked by another thread, the calling thread will wait +until @var{mutex} is unlocked, then attempt to lock it. Since there +may be many threads waiting at the same time, the calling thread may +need to repeat this wait-and-try many times before it successfully +locks @var{mutex}, at which point the call to +@code{pthread_mutex_locks} returns succesfully. + +This function may fail with the following: + +@table @code +@item EAGAIN +Too many locks were attempted. + +@item EDEADLK +The calling thread already holds a lock on @var{mutex}. + +@item EINVAL +@var{mutex} has an invalid kind, or an invalid priority was requested. + +@item ENOTRECOVERABLE +The thread holding the lock died in a way that the system cannot recover from. + +@item EOWNERDEAD +The thread holding the lock died in a way that the system can recover from. + +@end table + +@manpagefunctionstub{pthread_mutex_lock, 3} +@end deftypefun + +@deftypefun int pthread_mutex_trylock (pthread_mutex_t *@var{mutex}) +Like @code{pthread_mutex_lock} but if the lock cannot be immediately +obtained, returns EBUSY. +@manpagefunctionstub{pthread_mutex_trylock, 3} +@end deftypefun + +@deftypefun int pthread_mutex_unlock (pthread_mutex_t *@var{mutex}) +Unlocks @var{mutex}. Returns EPERM if the calling thread doesn't hold +the lock on @var{mutex}. +@manpagefunctionstub{pthread_mutex_unlock, 3} +@end deftypefun + +@deftypefun int pthread_mutex_clocklock (pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@end deftypefun + +@deftypefun int pthread_mutex_timedlock (pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime}) + +These two functions act like @code{pthread_mutex_lock} with the +exception that the call will not wait past time @var{abstime}, as +reported by @var{clockid} or (for @code{pthread_mutex_timedlock}) +@code{CLOCK_REALTIME}. If @var{abstime} is reached and the mutex +still cannot be locked, an @code{ETIMEDOUT} error is returned. +If the time had already passed when these functions +are called, and the mutex cannot be immediately locked, the function +times out immediately. +@end deftypefun + +@deftypefun int pthread_mutexattr_init (const pthread_mutexattr_t *@var{attr}) +Initializes @var{attr} with default values. +@manpagefunctionstub{pthread_mutexattr_init, 3} +@end deftypefun + +@deftypefun int pthread_mutexattr_destroy (pthread_mutexattr_t *@var{attr}) +Destroys @var{attr} and releases any resources it may have allocated. +@manpagefunctionstub{pthread_mutexattr_destroy, 3} +@end deftypefun + +@deftypefun int pthread_mutexattr_settype (pthread_mutexattr_t *@var{attr}, int @var{kind}) +This functions allow you to change what kind of mutex a mutex is, by +changing the attributes used to initialize it. The values for +@var{kind} are: + +@table @code +@item PTHREAD_MUTEX_NORMAL +No attempt to detect deadlock is performed; a thread will deadlock if +it tries to lock this mutex yet already holds a lock to it. +Attempting to unlock a mutex not locked by the calling thread results +in undefined behavior. + +@item PTHREAD_MUTEX_ERRORCHECK +Attemps to relock a mutex, or unlock a mutex not held, will result in an error. + +@item PTHREAD_MUTEX_RECURSIVE +Attempts to relock a mutex already held succeed, but require a +matching number of unlocks to release it. Attempts to unlock a mutex +not held will result in an error. + +@item PTHREAD_MUTEX_DEFAULT +Attemps to relock a mutex, or unlock a mutex not held, will result in +undefined behavior. This is the default. + +@end table +@end deftypefun + +@deftypefun int pthread_mutexattr_gettype (const pthread_mutexattr_t *@var{attr}, int *@var{kind}) +This function gets the kind of mutex @var{mutex} is. +@end deftypefun + +@node POSIX Threads Other APIs +@subsection POSIX Threads Other APIs + +@deftypefun int pthread_equal (pthread_t @var{thread1}, pthread_t @var{thread2}) +Compares two thread IDs. If they are the same, returns nonzero, else returns zero. +@manpagefunctionstub{pthread_equal, 3} +@end deftypefun + +@deftypefun int pthread_getcpuclockid (pthread_t @var{th}, __clockid_t *@var{clock_id}) +Get the clock associated with @var{th}. +@manpagefunctionstub{pthread_getcpuclockid, 3} +@end deftypefun + +@deftypefun int pthread_once (pthread_once_t *@var{once_control}, void (*@var{init_routine}) (void)) +Calls @var{init_routine} once for each @var{once_control}, which must +be statically initalized to @code{PTHREAD_ONCE_INIT}. Subsequent +calls to @code{pthread_once} with the same @var{once_control} do not +call @var{init_routine}, even in multi-threaded environments. +@manpagefunctionstub{pthread_once, 3} +@end deftypefun + +@deftypefun int pthread_sigmask (int @var{how}, const __sigset_t *@var{newmask}, __sigset_t *@var{oldmask}) +@manpagefunctionstub{pthread_sigmask, 3} +@end deftypefun + @node Non-POSIX Extensions @subsection Non-POSIX Extensions @@ -780,7 +1145,9 @@ the standard. * Default Thread Attributes:: Setting default attributes for threads in a process. * Initial Thread Signal Mask:: Setting the initial mask of threads. +* Thread CPU Affinity:: Limiting which CPUs can run a thread. * Joining Threads:: Wait for a thread to terminate. +* Thread Names:: Changing the name of a thread. * Single-Threaded:: Detecting single-threaded execution. * Restartable Sequences:: Linux-specific restartable sequences integration. @@ -899,6 +1266,36 @@ signal mask and use @code{pthread_sigmask} to apply it to the thread. If the signal mask was copied to a heap allocation, the copy should be freed. +@node Thread CPU Affinity +@subsubsection Thread CPU Affinity + +Processes and threads normally run on any available CPU. However, +they can be given an @emph{affinity} to one or more CPUs, which limits +them to the CPU set specified. + +@deftypefun int pthread_attr_setaffinity_np (pthread_attr_t *@var{attr}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset}) +Sets the CPU affinity in @var{attr}. The CPU affinity +controls which CPUs a thread may execute on. @xref{CPU Affinity}. +@manpagefunctionstub{pthread_attr_setaffinity_np, 3} +@end deftypefun + +@deftypefun int pthread_attr_getaffinity_np (const pthread_attr_t *@var{attr}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset}) +Gets the CPU affinity settings from @var{attr}. +@manpagefunctionstub{pthread_attr_getaffinity_np, 3} +@end deftypefun + +@deftypefun int pthread_setaffinity_np (pthread_t *@var{th}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset}) +Sets the CPU affinity for thread @var{th}. The CPU affinity controls +which CPUs a thread may execute on. @xref{CPU Affinity}. +@manpagefunctionstub{pthread_setaffinity_np, 3} +@end deftypefun + +@deftypefun int pthread_getaffinity_np (const pthread_t *@var{th}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset}) +Gets the CPU affinity for thread @var{th}. The CPU affinity controls +which CPUs a thread may execute on. @xref{CPU Affinity}. +@manpagefunctionstub{pthread_getaffinity_np, 3} +@end deftypefun + @node Joining Threads @subsubsection Wait for a thread to terminate @@ -940,6 +1337,21 @@ Currently, @var{clockid} must be either @code{CLOCK_MONOTONIC} or The @code{sem_clockwait} function also works using a @code{clockid_t} argument. @xref{POSIX Semaphores}. +@node Thread Names +@subsubsection Thread Names + +@deftypefun int pthread_setname_np (pthread_t @var{th}, const char *@var{name}) +Gives thread @var{th} the name @var{name}. This name shows up in +@code{ps} when it's listing individual threads. @var{name} is a +NUL-terminated string of no more than 15 non-NUL characters. +@manpagefunctionstub{pthread_setname_np, 3} +@end deftypefun + +@deftypefun int pthread_getname_np (pthread_t @var{th}, char *@var{buf}, size_t @var{buflen}) +Retrieves the name of thread @var{th}. +@manpagefunctionstub{pthread_getname_np, 3} +@end deftypefun + @node Single-Threaded @subsubsection Detecting Single-Threaded Execution diff --git a/manual/time.texi b/manual/time.texi index 04c97f5..254638c 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -148,7 +148,8 @@ and pass them to the functions that convert them to broken-down time On POSIX-conformant systems, @code{time_t} is an integer type and its values represent the number of seconds elapsed since the @dfn{POSIX Epoch}, which is January 1, 1970, at 00:00:00 Coordinated Universal Time (UTC)@. -The count of seconds ignores leap seconds. +The count of seconds ignores leap seconds. Additionally, POSIX.1-2024 +added the requirement that @code{time_t} be at least 64 bits wide. @Theglibc{} additionally guarantees that @code{time_t} is a signed type, and that all of its functions operate correctly on negative @@ -528,7 +529,36 @@ Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure absolute time, only elapsed time. @end deftypevr -Systems may support more than just these two POSIX clocks. +The following clocks are defined by POSIX, but may not be supported by +all POSIX systems: + +@deftypevr Macro clockid_t CLOCK_PROCESS_CPUTIME_ID +@standards{POSIX.1, time.h} +This POSIX clock measures the amount of CPU time used by the calling +process. +@end deftypevr + +@deftypevr Macro clockid_t CLOCK_THREAD_CPUTIME_ID +@standards{POSIX.1, time.h} +This POSIX clock measures the amount of CPU time used by the calling +thread. +@end deftypevr + +The following clocks are Linux extensions: + +@deftypevr Macro clockid_t CLOCK_MONOTONIC_RAW +@deftypevrx Macro clockid_t CLOCK_REALTIME_COARSE +@deftypevrx Macro clockid_t CLOCK_MONOTONIC_COARSE +@deftypevrx Macro clockid_t CLOCK_BOOTTIME +@deftypevrx Macro clockid_t CLOCK_REALTIME_ALARM +@deftypevrx Macro clockid_t CLOCK_BOOTTIME_ALARM +@deftypevrx Macro clockid_t CLOCK_TAI +@standards{Linux, time.h} +For details of these clocks, see the manual page +@manpageurl{clock_gettime,2}. +@end deftypevr + +Systems may support additional clocks beyond those listed here. @deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts}) @standards{POSIX.1, time.h} @@ -599,6 +629,19 @@ Systems may support more than just this @w{ISO C} clock. Store into @code{*@var{ts}} the current time according to the @w{ISO C} time @var{base}. +The base @code{TIME_UTC} returns the time since the epoch. It corresponds +to @code{CLOCK_REALTIME}. + +The base @code{TIME_MONOTONIC} returns a monotonically nondecreasing time since +an unspecified point in the past that may change if the system is rebooted or +suspended. It corresponds to @code{CLOCK_MONOTONIC}. + +The base @code{TIME_ACTIVE} returns the CPU time consumed by the process +(including all threads). It corresponds to @code{CLOCK_PROCESS_CPUTIME_ID}. + +The base @code{TIME_THREAD_ACTIVE} returns the CPU time consumed by the +calling thread. It corresponds to @code{CLOCK_THREAD_CPUTIME_ID}. + The return value is @var{base} on success and @code{0} on failure. @end deftypefun @@ -3150,12 +3193,12 @@ On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in the same program, because @code{sleep} does not work by means of @code{SIGALRM}. -@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) +@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) @standards{POSIX.1, time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses @c ports. -If resolution to seconds is not enough the @code{nanosleep} function can +If resolution to seconds is not enough, the @code{nanosleep} function can be used. As the name suggests the sleep interval can be specified in nanoseconds. The actual elapsed time of the sleep interval might be longer since the system rounds the elapsed time you request up to the @@ -3164,36 +3207,93 @@ next integer multiple of the actual resolution the system can deliver. @code{*@var{requested_time}} is the elapsed time of the interval you want to sleep. -The function returns as @code{*@var{remaining}} the elapsed time left -in the interval for which you requested to sleep. If the interval -completed without getting interrupted by a signal, this is zero. +If @var{remaining_time} is not the null pointer, the function returns as +@code{*@var{remaining_time}} the elapsed time left in the interval for which +you requested to sleep. If the interval completed without getting +interrupted by a signal, this is zero. @code{struct timespec} is described in @ref{Time Types}. -If the function returns because the interval is over the return value is -zero. If the function returns @math{-1} the global variable @code{errno} -is set to the following values: +If the function returns because the interval is over, it returns zero. +Otherwise it returns @math{-1} and sets the global variable @code{errno} to +one of the following values: @table @code @item EINTR The call was interrupted because a signal was delivered to the thread. -If the @var{remaining} parameter is not the null pointer the structure -pointed to by @var{remaining} is updated to contain the remaining +If the @var{remaining_time} parameter is not the null pointer, the structure +pointed to by @var{remaining_time} is updated to contain the remaining elapsed time. @item EINVAL The nanosecond value in the @var{requested_time} parameter contains an -illegal value. Either the value is negative or greater than or equal to +invalid value. Either the value is negative or greater than or equal to 1000 million. @end table This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{nanosleep} is -called. If the thread gets canceled these resources stay allocated -until the program ends. To avoid this calls to @code{nanosleep} should +called. If the thread gets canceled, these resources stay allocated +until the program ends. To avoid this, calls to @code{nanosleep} should be protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The @code{nanosleep} function is declared in @file{time.h}. @end deftypefun + +@deftypefun int clock_nanosleep (clockid_t @var{clock}, int @var{flags}, const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) +@standards{POSIX.1-2001, time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function is similar to @code{nanosleep} while additionally providing +the caller with a way to specify the clock to be used to measure elapsed +time and express the sleep interval in absolute or relative terms. It +returns zero when returning because the interval is over, and a positive +error number corresponding to the error encountered otherwise. This is +different from @code{nanosleep}, which returns @math{-1} upon failure and +sets the global variable @code{errno} according to the error encountered +instead. + +Except for the return value convention and the way to communicate an error +condition the call: + +@smallexample +nanosleep (@var{requested_time}, @var{remaining_time}) +@end smallexample + +is analogous to: + +@smallexample +clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time}, @var{remaining_time}) +@end smallexample + +The @var{clock} argument specifies the clock to use. +@xref{Getting the Time}, for the @code{clockid_t} type and possible values +of @var{clock}. Not all clocks listed are supported for use with +@code{clock_nanosleep}. For details, see the manual page +@manpageurl{clock_nanosleep,2}. + +The @var{flags} argument is either @code{0} or @code{TIMER_ABSTIME}. If +@var{flags} is @code{0}, then @code{clock_nanosleep} interprets +@var{requested_time} as an interval relative to the current time specified +by @var{clock}. If it is @code{TIMER_ABSTIME} instead, @var{requested_time} +specifies an absolute time measured by @var{clock}; if at the time of the +call the value requested is less than or equal to the clock specified, then +the function returns right away. When @var{flags} is @code{TIMER_ABSTIME}, +@var{remaining_time} is not updated. + +The @code{clock_nanosleep} function returns error codes as positive return +values. The error conditions for @code{clock_nanosleep} are the same as for +@code{nanosleep}, with the following conditions additionally defined: + +@table @code +@item EINVAL +The @var{clock} argument is not a valid clock. + +@item EOPNOTSUPP +The @var{clock} argument is not supported by the kernel for +@code{clock_nanosleep}. +@end table + +The @code{clock_nanosleep} function is declared in @file{time.h}. +@end deftypefun diff --git a/manual/tunables.texi b/manual/tunables.texi index 7f0246c..7956df9 100644 --- a/manual/tunables.texi +++ b/manual/tunables.texi @@ -35,20 +35,16 @@ tunables with minimum and maximum values: @example $ /lib64/ld-linux-x86-64.so.2 --list-tunables glibc.rtld.nns: 0x4 (min: 0x1, max: 0x10) -glibc.elision.skip_lock_after_retries: 3 (min: 0, max: 2147483647) glibc.malloc.trim_threshold: 0x0 (min: 0x0, max: 0xffffffffffffffff) glibc.malloc.perturb: 0 (min: 0, max: 255) glibc.cpu.x86_shared_cache_size: 0x100000 (min: 0x0, max: 0xffffffffffffffff) glibc.pthread.rseq: 1 (min: 0, max: 1) glibc.cpu.prefer_map_32bit_exec: 0 (min: 0, max: 1) glibc.mem.tagging: 0 (min: 0, max: 255) -glibc.elision.tries: 3 (min: 0, max: 2147483647) -glibc.elision.enable: 0 (min: 0, max: 1) glibc.malloc.hugetlb: 0x0 (min: 0x0, max: 0xffffffffffffffff) glibc.cpu.x86_rep_movsb_threshold: 0x2000 (min: 0x100, max: 0xffffffffffffffff) glibc.malloc.mxfast: 0x0 (min: 0x0, max: 0xffffffffffffffff) glibc.rtld.dynamic_sort: 2 (min: 1, max: 2) -glibc.elision.skip_lock_busy: 3 (min: 0, max: 2147483647) glibc.malloc.top_pad: 0x20000 (min: 0x0, max: 0xffffffffffffffff) glibc.cpu.x86_rep_stosb_threshold: 0x800 (min: 0x1, max: 0xffffffffffffffff) glibc.cpu.x86_non_temporal_threshold: 0xc0000 (min: 0x4040, max: 0xfffffffffffffff) @@ -56,12 +52,10 @@ glibc.cpu.x86_memset_non_temporal_threshold: 0xc0000 (min: 0x4040, max: 0xffffff glibc.cpu.x86_shstk: glibc.pthread.stack_cache_size: 0x2800000 (min: 0x0, max: 0xffffffffffffffff) glibc.malloc.mmap_max: 0 (min: 0, max: 2147483647) -glibc.elision.skip_trylock_internal_abort: 3 (min: 0, max: 2147483647) glibc.cpu.plt_rewrite: 0 (min: 0, max: 2) glibc.malloc.tcache_unsorted_limit: 0x0 (min: 0x0, max: 0xffffffffffffffff) glibc.cpu.x86_ibt: glibc.cpu.hwcaps: -glibc.elision.skip_lock_internal_abort: 3 (min: 0, max: 2147483647) glibc.malloc.arena_max: 0x0 (min: 0x1, max: 0xffffffffffffffff) glibc.malloc.mmap_threshold: 0x0 (min: 0x0, max: 0xffffffffffffffff) glibc.cpu.x86_data_cache_size: 0x8000 (min: 0x0, max: 0xffffffffffffffff) @@ -77,7 +71,6 @@ glibc.malloc.check: 0 (min: 0, max: 3) * Tunable names:: The structure of a tunable name * Memory Allocation Tunables:: Tunables in the memory allocation subsystem * Dynamic Linking Tunables:: Tunables in the dynamic linking subsystem -* Elision Tunables:: Tunables in elision subsystem * POSIX Thread Tunables:: Tunables in the POSIX thread subsystem * Hardware Capability Tunables:: Tunables that modify the hardware capabilities seen by @theglibc{} @@ -365,8 +358,11 @@ change the main stack permission if kernel starts with a non-executable stack. The @code{glibc.rtld.execstack} can be used to control whether an executable stack is allowed from the main program. Setting the value to @code{0} disables the ABI auto-negotiation (meaning no executable stacks even if the ABI or ELF -header requires it), while @code{1} enables auto-negotiation (although the -program might not need an executable stack). +header requires it), @code{1} enables auto-negotiation (although the program +might not need an executable stack), while @code{2} forces an executable +stack at process start. This is provided for compatibility reasons, when +the program dynamically loads modules with @code{dlopen} which require +an executable stack. When executable stacks are not allowed, and if the main program requires it, the loader will fail with an error message. @@ -380,75 +376,8 @@ of hardware capabilities and kernel configuration. @strong{NB:} Trying to load a dynamic shared library with @code{dlopen} or @code{dlmopen} that requires an executable stack will always fail if the main program does not require an executable stack at loading time. This -is enforced regardless of the tunable value. -@end deftp - -@node Elision Tunables -@section Elision Tunables -@cindex elision tunables -@cindex tunables, elision - -@deftp {Tunable namespace} glibc.elision -Contended locks are usually slow and can lead to performance and scalability -issues in multithread code. Lock elision will use memory transactions to under -certain conditions, to elide locks and improve performance. -Elision behavior can be modified by setting the following tunables in -the @code{elision} namespace: -@end deftp - -@deftp Tunable glibc.elision.enable -The @code{glibc.elision.enable} tunable enables lock elision if the feature is -supported by the hardware. If elision is not supported by the hardware this -tunable has no effect. - -Elision tunables are supported for 64-bit Intel, IBM POWER, and z System -architectures. -@end deftp - -@deftp Tunable glibc.elision.skip_lock_busy -The @code{glibc.elision.skip_lock_busy} tunable sets how many times to use a -non-transactional lock after a transactional failure has occurred because the -lock is already acquired. Expressed in number of lock acquisition attempts. - -The default value of this tunable is @samp{3}. -@end deftp - -@deftp Tunable glibc.elision.skip_lock_internal_abort -The @code{glibc.elision.skip_lock_internal_abort} tunable sets how many times -the thread should avoid using elision if a transaction aborted for any reason -other than a different thread's memory accesses. Expressed in number of lock -acquisition attempts. - -The default value of this tunable is @samp{3}. -@end deftp - -@deftp Tunable glibc.elision.skip_lock_after_retries -The @code{glibc.elision.skip_lock_after_retries} tunable sets how many times -to try to elide a lock with transactions, that only failed due to a different -thread's memory accesses, before falling back to regular lock. -Expressed in number of lock elision attempts. - -This tunable is supported only on IBM POWER, and z System architectures. - -The default value of this tunable is @samp{3}. -@end deftp - -@deftp Tunable glibc.elision.tries -The @code{glibc.elision.tries} sets how many times to retry elision if there is -chance for the transaction to finish execution e.g., it wasn't -aborted due to the lock being already acquired. If elision is not supported -by the hardware this tunable is set to @samp{0} to avoid retries. - -The default value of this tunable is @samp{3}. -@end deftp - -@deftp Tunable glibc.elision.skip_trylock_internal_abort -The @code{glibc.elision.skip_trylock_internal_abort} tunable sets how many -times the thread should avoid trying the lock if a transaction aborted due to -reasons other than a different thread's memory accesses. Expressed in number -of try lock attempts. - -The default value of this tunable is @samp{3}. +can be worked around by setting the tunable to @code{2}, where the stack is +always executable. @end deftp @node POSIX Thread Tunables @@ -669,6 +598,23 @@ This tunable is specific to x86-64 and effective only when the lazy binding is disabled. @end deftp +@deftp Tunable glibc.cpu.aarch64_bti +This tunable controls Branch Target Identification (BTI) handling for the +process. This handling is implemented via protecting the memory mapping +with @code{PROT_BTI} for modules that are marked with the appropriate ELF +property @code{GNU_PROPERTY_AARCH64_FEATURE_1_BTI} (see Program Loading in +@url{https://github.com/ARM-software/abi-aa/blob/main/sysvabi64/sysvabi64.rst}). + +Accepted values are: + +0 = permissive: BTI protection is enabled only for modules that have BTI +marking (default). + +1 = enforced: if a module that does not have BTI marking is loaded, it is +an error (either a process abort or a @code{dlopen} error if this binary +is loaded via @code{dlopen}). +@end deftp + @deftp Tunable glibc.cpu.aarch64_gcs This tunable controls Guarded Control Stack (GCS) for the process. @@ -755,7 +701,7 @@ Linux version 5.17, although not always enabled by some kernel configurations), this tunable can be used to control whether @theglibc{} decorates the underlying memory obtained from operating system with a string describing its usage (for instance, on the thread -stack created by @code{ptthread_create} or memory allocated by +stack created by @code{pthread_create} or memory allocated by @code{malloc}). The process mappings can be obtained by reading the @code{/proc/<pid>maps} |