diff options
Diffstat (limited to 'manual')
77 files changed, 2800 insertions, 523 deletions
diff --git a/manual/Makefile b/manual/Makefile index a6c05db..06f3500 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -1,4 +1,4 @@ -# Copyright (C) 1992-2024 Free Software Foundation, Inc. +# Copyright (C) 1992-2025 Free Software Foundation, Inc. # This file is part of the GNU C Library. # The GNU C Library is free software; you can redistribute it and/or @@ -55,7 +55,7 @@ examples = $(filter %.c.texi, $(texis)) # Generated files directly included from libc.texinfo. libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \ - libm-err.texi version.texi pkgvers.texi + version.texi pkgvers.texi # Add path to build dir for generated files texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \ @@ -69,6 +69,11 @@ chapters.% top-menu.%: libc-texinfo.sh $(texis-path) Makefile '$(chapters)' \ '$(appendices) $(licenses)' +# Verify validity of texinfo sources against project rules. +tests-special += \ + $(objpfx)check-deftype.out \ + $(objpfx)check-safety.out \ + # tests-special $(objpfx)libc.dvi $(objpfx)libc.pdf $(objpfx)libc.info: \ $(addprefix $(objpfx),$(libc-texi-generated)) @@ -83,10 +88,19 @@ $(objpfx)summary.texi: $(objpfx)stamp-summary ; $(objpfx)stamp-summary: summary.pl $(filter-out $(objpfx)summary.texi, \ $(texis-path)) $(SHELL) ./check-safety.sh $(filter-out $(objpfx)%, $(texis-path)) + $(SHELL) ./check-deftype.sh $(filter-out $(objpfx)%, $(texis-path)) LC_ALL=C $(PERL) $^ > $(objpfx)summary-tmp $(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi touch $@ +$(objpfx)check-safety.out: check-safety.sh + $(SHELL) $< > $@ ; \ + $(evaluate-test) + +$(objpfx)check-deftype.out: check-deftype.sh + $(SHELL) $< > $@ ; \ + $(evaluate-test) + # Generate a file which can be added to the `dir' content to provide direct # access to the documentation of the function, variables, and other # definitions. @@ -97,16 +111,6 @@ $(objpfx)dir-add.texi: xtract-typefun.awk $(texis-path) echo "@end direntry") > $@.new mv -f $@.new $@ -# The table with the math errors is generated. -$(objpfx)libm-err.texi: $(objpfx)stamp-libm-err -$(objpfx)stamp-libm-err: $(..)math/gen-libm-test.py \ - $(wildcard $(foreach dir,$(sysdirs),\ - $(dir)/libm-test-ulps)) - pwd=`pwd`; \ - $(PYTHON) $< -s $$pwd/.. -m $(objpfx)libm-err-tmp - $(move-if-change) $(objpfx)libm-err-tmp $(objpfx)libm-err.texi - touch $@ - # Package version and bug reporting URL. $(objpfx)pkgvers.texi: $(objpfx)stamp-pkgvers ; $(objpfx)stamp-pkgvers: $(common-objpfx)config.make @@ -152,10 +156,19 @@ $(objpfx)%.pdf: %.texinfo # Distribution. -minimal-dist = summary.pl texis.awk tsort.awk libc-texinfo.sh libc.texinfo \ - libm-err.texi stamp-libm-err check-safety.sh \ - $(filter-out summary.texi, $(nonexamples)) \ - $(patsubst %.c.texi,examples/%.c, $(examples)) +minimal-dist = \ + $(filter-out summary.texi, $(nonexamples)) \ + $(patsubst %.c.texi,examples/%.c, $(examples)) \ + check-deftype.sh \ + check-safety.sh \ + libc-texinfo.sh \ + libc.texinfo \ + libm-err.texi \ + stamp-libm-err \ + summary.pl \ + texis.awk \ + tsort.awk \ + # minimal-dist indices = cp fn pg tp vr ky generated-dirs += libc diff --git a/manual/arith.texi b/manual/arith.texi index 034d9d2..d500dcf 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{uimaxabs} 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 uimaxabs (intmax_t @var{number}) @standards{ISO, stdlib.h} @standardsx{imaxabs, ISO, inttypes.h} +@standardsx{uimaxabs, 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{uimaxabs} are new to @w{ISO C2Y}. See @ref{Integers} for a description of the @code{intmax_t} type. diff --git a/manual/charset.texi b/manual/charset.texi index 427db3b..3aaa62d 100644 --- a/manual/charset.texi +++ b/manual/charset.texi @@ -2422,11 +2422,11 @@ written into the buffer to signal how much output is available. If this conversion step is not the last one, the element must not be modified. The @code{__outbufend} element must not be modified. -@item int __is_last -This element is nonzero if this conversion step is the last one. This -information is necessary for the recursion. See the description of the -conversion function internals below. This element must never be -modified. +@item int __flags +This field is a set of flags. The @code{__GCONV_IS_LAST} bit is set if +this conversion step is the last one. This information is necessary for +the recursion. See the description of the conversion function internals +below. This element must never be modified. @item int __invocation_counter The conversion function can use this element to see how many calls of @@ -2731,8 +2731,8 @@ Otherwise the function has to emit a byte sequence to bring the state object into the initial state. Once this all happened the other conversion modules in the chain of conversions have to get the same chance. Whether another step follows can be determined from the -@code{__is_last} element of the step data structure to which the first -parameter points. +@code{__GCONV_IS_LAST} flag in the @code{__flags} field of the step +data structure to which the first parameter points. The more interesting mode is when actual text has to be converted. The first step in this case is to convert as much text as possible from the @@ -2866,7 +2866,7 @@ gconv (struct __gconv_step *step, struct __gconv_step_data *data, /* @r{Call the steps down the chain if there are any but only} @r{if we successfully emitted the escape sequence.} */ - if (status == __GCONV_OK && ! data->__is_last) + if (status == __GCONV_OK && ! (data->__flags & __GCONV_IS_LAST)) status = fct (next_step, next_data, NULL, NULL, written, 1); @} @@ -2892,7 +2892,7 @@ gconv (struct __gconv_step *step, struct __gconv_step_data *data, /* @r{If this is the last step, leave the loop. There is} @r{nothing we can do.} */ - if (data->__is_last) + if (data->__flags & __GCONV_IS_LAST) @{ /* @r{Store information about how many bytes are} @r{available.} */ diff --git a/manual/check-deftype.sh b/manual/check-deftype.sh new file mode 100644 index 0000000..c44644e --- /dev/null +++ b/manual/check-deftype.sh @@ -0,0 +1,50 @@ +#!/bin/sh + +# Copyright 2024-2025 Free Software Foundation, Inc. +# This file is part of the GNU C Library. + +# The GNU C Library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. + +# The GNU C 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 +# Lesser General Public License for more details. + +# You should have received a copy of the GNU Lesser General Public +# License along with the GNU C Library; if not, see +# <https://www.gnu.org/licenses/>. + +# Check that the @deftypefun command is called with the expected +# arguments and includes checking for common mistakes including +# failure to include a space after the function name, or incorrect +# quoting. + +success=: + +# If no arguments are given, take all *.texi files in the current directory. +test $# != 0 || set *.texi + +# We search for all @deftypefun and @deftypefunx command uses. +# Then we remove all of those that match our expectations. +# A @deftypefun or @deftypefunx command takes 3 arguments: +# - return type +# - name +# - arguments +# This is different from @deftypefn which includes an additional +# category which is implicit here. +grep -n -r '^@deftypefun' "$@" | +grep -v '^.*@deftypefunx\?'\ +' \({\?[a-zA-Z0-9_ *]*}\?\) \([a-zA-Z0-9_]*\) (.*)$' && +success=false + +# We search for all @deftypefn and @deftypefnx command uses. +# We have 4 arguments in the command including the category. +grep -n -r '^@deftypefn' "$@" | +grep -v '^.*@deftypefnx\?'\ +' {\?[a-zA-Z ]*}\? \({\?[a-zA-Z0-9@{}_ *]*}\?\) \([a-zA-Z0-9_]*\) (.*)$' && +success=false + +$success diff --git a/manual/check-safety.sh b/manual/check-safety.sh index b80fa30..c758c46 100644 --- a/manual/check-safety.sh +++ b/manual/check-safety.sh @@ -1,6 +1,6 @@ #!/bin/sh -# Copyright 2014-2024 Free Software Foundation, Inc. +# Copyright 2014-2025 Free Software Foundation, Inc. # This file is part of the GNU C Library. # The GNU C Library is free software; you can redistribute it and/or @@ -22,7 +22,7 @@ # in proper order (mt then as then ac), that remarks appear within # corresponding sections (mt within mt, etc), that unsafety always has # an explicit reason and when there's a reason for unsafety it's not -# safe, and that there aren't duplicates remarks. +# safe. success=: @@ -37,10 +37,15 @@ test $# != 0 || set *.texi # Check that all safety remarks have entries for all of MT, AS and AC, # in this order, with an optional prelim note before them. +ret=true grep -n '^@safety' "$@" | grep -v ':@safety{\(@prelim{}\)\?@mt\(un\)\?safe{.*}'\ '@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #1 - Missing context in @safety macro." + success=false +fi # Check that @mt-started notes appear within @mtsafe or @mtunsafe, # that @as-started notes appear within @assafe or @asunsafe, and that @@ -49,6 +54,7 @@ success=false # unsafe), but let @mt have as, ac or asc before [su], and let @as # have a c (for cancel) before [su]. Also make sure blanks separate # each of the annotations. +ret=true grep -n '^@safety' "$@" | grep -v ':@safety{\(@prelim{}\)\?'\ '@mt\(un\)\?safe{\(@mt\(asc\?\|ac\)\?[su][^ ]*}\)\?'\ @@ -57,68 +63,98 @@ grep -v ':@safety{\(@prelim{}\)\?'\ '\( @asc\?[su][^ ]*}\)*}'\ '@ac\(un\)\?safe{\(@ac[su][^ ]*}\)\?'\ '\( @ac[su][^ ]*}\)*}}' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #2 - Incorrect @safety macro formatting." + success=false +fi # Make sure safety lines marked as @mtsafe do not contain any # MT-Unsafe remark; that would be @mtu, but there could be as, ac or # asc between mt and u. +ret=true grep -n '^@safety.*@mtsafe' "$@" | -grep '@mt\(asc\?\|ac\)?u' "$@" && -success=false +grep '@mt\(asc\?\|ac\)\?u' && +ret=false +if ! $ret; then + echo "FAIL: #3 - MT context contains remarks when it should not." + success=false +fi # Make sure @mtunsafe lines contain at least one @mtu remark (with # optional as, ac or asc between mt and u). +ret=true grep -n '^@safety.*@mtunsafe' "$@" | grep -v '@mtunsafe{.*@mt\(asc\?\|ac\)\?u' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #4 - MT context lacks at least one remark." + success=false +fi # Make sure safety lines marked as @assafe do not contain any AS-Unsafe # remark, which could be @asu or @mtasu note (with an optional c # between as and u in both cases). +ret=true grep -n '^@safety.*@assafe' "$@" | grep '@\(mt\)\?asc\?u' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #5 - AS context contains remarks when it should not." + success=false +fi # Make sure @asunsafe lines contain at least one @asu remark (which -# could be @ascu, or @mtasu or even @mtascu). +# could be @ascu, or @mtasu or even @mtascu). We allow the AS safety +# remark from an earlier MT-unsafe to count towards such a remark +# e.g. @mtunsafe{@mtasurace{:LogMask}}@asunsafe{}@acsafe{} is allowed. +ret=true grep -n '^@safety.*@asunsafe' "$@" | grep -v '@mtasc\?u.*@asunsafe\|@asunsafe{.*@asc\?u' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #6 - AS unsafe context lacks at least one remark." + success=false +fi # Make sure safety lines marked as @acsafe do not contain any # AC-Unsafe remark, which could be @acu, @ascu or even @mtacu or # @mtascu. +ret=true grep -n '^@safety.*@acsafe' "$@" | grep '@\(mt\)\?as\?cu' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #7 - AC context contains remarks when it should not." + success=false +fi # Make sure @acunsafe lines contain at least one @acu remark (possibly # implied by @ascu, @mtacu or @mtascu). +ret=true grep -n '^@safety.*@acunsafe' "$@" | grep -v '@\(mtas\?\|as\)cu.*@acunsafe\|@acunsafe{.*@acu' && -success=false - -# Make sure there aren't duplicate remarks in the same safety note. -grep -n '^@safety' "$@" | -grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #8 - AC unsafe context lacks at least one remark." + success=false +fi # Check that comments containing safety remarks do not contain {}s, # that all @mt remarks appear before @as remarks, that in turn appear # before @ac remarks, all properly blank-separated, and that an # optional comment about exclusions is between []s at the end of the # line. +ret=true grep -n '^@c \+[^@ ]\+\( dup\)\?'\ '\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*]\)\?$' "$@" | grep -v ':@c *[^@{}]*\( @mt[^ {}]*\)*'\ '\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*]\)\?$' && -success=false - -# Check that comments containing safety remarks do not contain -# duplicate remarks. -grep -n '^@c \+[^@ ]\+\( dup\)\?'\ -'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*]\)\?$' "$@" | -grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' && -success=false +ret=false +if ! $ret; then + echo "FAIL: #9 - Comment safety note ordering, brackets, or"\ + "exclusions are incorrect." + success=false +fi $success diff --git a/manual/contrib.texi b/manual/contrib.texi index d947166..3d1b170 100644 --- a/manual/contrib.texi +++ b/manual/contrib.texi @@ -16,10 +16,14 @@ Nick Alcock for contributing fixes to allow @theglibc{} to be built with the stack smashing protector enabled. @item +Rogerio Alves Cardoso for various fixes to PowerPC. + +@item Amrita H. S. for contributions to the PowerPC port. @item -John David Anglin for various fixes to the hppa port. +John David Anglin for various fixes and co-maintainership of the HPPA +port. @item Albert ARIBAUD for Y2038 related fixes. @@ -44,12 +48,19 @@ under the @file{sysdeps/mips} directory. Jeff Bailey for his maintainership of the HPPA architecture. @item +Frank Barrus for work on the threading library. + +@item Petr Baudis for bug fixes and testing. @item Fr@'ed@'eric B@'erat for numerous fixes and contributions. @item +Peter Bergner for contributions to and maintainership of the PowerPC +port. + +@item Indu Bhagat for various fixes. @item @@ -68,13 +79,17 @@ Eric Blake for adding O(n) implementations of @code{memmem}, @code{strstr} and @code{strcasestr}. @item +Pierre Blanchard for contributing to the AArch64 port. + +@item Philip Blundell for the ports to Linux/ARM (@code{arm-@var{ANYTHING}-linuxaout}) and ARM standalone (@code{arm-@var{ANYTHING}-none}), as well as for parts of the IPv6 support code. @item -Mahesh Bodapati for various fixes. +Mahesh Bodapati for various fixes and optimizations for the Power +architecture. @item Per Bothner for the implementation of the @code{libio} library which @@ -97,9 +112,6 @@ Thomas Bushnell for his contributions to Hurd. Yinyu Cai for their maintainership of the LoongArch port. @item -Rogerio Alves Cardoso for various fixes to PowerPC. - -@item Daniel Cederman for fixes to the Sparc port. @item @@ -121,16 +133,20 @@ Mike Crowe for various fixes. Flavio Cruz for contributions to Hurd. @item +Joana Cruz for contributions to the AArch64 port. + +@item Palmer Dabbelt for contributing the port to Linux/RISC-V. @item -DJ Delorie for maintenance of Linux/RISC-V, and various fixes. +DJ Delorie for maintenance of Linux/RISC-V, and numerous fixes. @item Jianbo Deng for the work on the Loongson port. @item -Wilco Dijkstra for various fixes and work on the AArch64 port. +Wilco Dijkstra for various fixes and many improvements of the AArch64 +port. @item Liubov Dmitrieva for optimized string and math functions on x86-64 and @@ -186,12 +202,6 @@ locale updates and fixes. Gabi Falk for various fixes. @item -Tulio Magno Quites Machado Filho for adding a new class of installed -headers for low-level platform-specific functionality, including the -low-level platform-specific headers for PowerPC, for their maintainership -of the PowerPC port and various fixes. - -@item Olaf Flebbe and Ralf B@"achle for contributing @file{sysdeps/mips/fpu_control.h}. @@ -233,6 +243,9 @@ functions (@code{memcpy}, @code{strlen}, etc.). Evan Green for work on the RISC-V port. @item +Wangyang Guo for various contributions. + +@item Vineet Gupta for their maintainership of the ARC port. @item @@ -263,7 +276,7 @@ Stafford Horne for maintainership of the OpenRISC port. Ying Huang for work on the MIPS port. @item -Guy-Fleury Iteriteka for contributions to Hurd support. +Guy-Fleury Iteriteka for many contributions to Hurd support. @item Daniel Jacobowitz for various fixes and enhancements. @@ -285,6 +298,9 @@ Aurelien Jarno for various fixes. Rical Jasan for contributing various fixes in @theglibc{} manual. @item +Michael Jeanson for the restartable sequences support. + +@item Jakub Jelinek for implementing a number of checking functions, software floating-point support and for his direction as part of @theglibc{} steering committee. @@ -306,6 +322,9 @@ 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. + +@item Simon Kissane for gmon improvements. @item @@ -334,6 +353,9 @@ for NSS (@file{nscd}). Akhilesh Kumar for various fixes to locales. @item +Luna Lamb for contributions to the AArch64 port. + +@item Jeff Law for various fixes. @item @@ -351,7 +373,8 @@ Ilya Leoshkevich for various fixes. Dmitry V. Levin for various fixes. @item -Stefan Liebler for numerous fixes and the work on the S390 port. +Stefan Liebler for numerous fixes and the maintainership of the S390 +port. @item Hongjiu Lu for providing the support for a Linux 32-bit runtime @@ -379,6 +402,9 @@ function and writing the @file{tar.h} header. Lukasz Majewski for Y2038 related fixes. @item +Miguel Mart@'in for contributed tests. + +@item Manjunath Matti for contributions to the PowerPC port. @item @@ -397,6 +423,9 @@ Allan McRae for various fixes. Meng Qinggang for contributions to the LoongArch port. @item +Aaron Merey for contributed tests. + +@item Jason Merrill for the port to the Sequent Symmetry running Dynix version 3 (@code{i386-sequent-bsd}). @@ -420,7 +449,7 @@ Cupertino Miranda for various fixes. Alan Modra for his improvements for Linux on PowerPC. @item -Sachin Monga for various fixes. +Sachin Monga for various fixes and contributions to the PowerPC port. @item David Mosberger-Tang for contributing the port to Linux/Alpha @@ -454,7 +483,8 @@ and his direction as FSF Project Steward for @theglibc{}. Marko Myllynen for various fixes. @item -Szabolcs Nagy for many fixes and contributions to AArch64. +Szabolcs Nagy for many fixes, contributions, and maintainership of +AArch64. @item Nab for various fixes. @@ -491,6 +521,9 @@ Paul Pluzhnikov for various fixes. Marek Polacek for various fixes. @item +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. @@ -501,6 +534,12 @@ libraries and the port to SGI machines running Irix 4 (@code{mips-sgi-irix4}). @item +Tulio Magno Quites Machado Filho for adding a new class of installed +headers for low-level platform-specific functionality, including the +low-level platform-specific headers for PowerPC, for their +maintainership of the PowerPC port and various fixes. + +@item Joe Ramsay for contributing to the AArch64 port, in particular the vector library. @@ -510,7 +549,7 @@ pthread_rwlock and condition variables. @item Maciej W. Rozycki for MIPS fixes, support for ABSOLUTE symbols, -and various fixes. +various fixes and many contributions to the test suite. @item Leonardo Sandoval for various fixes. @@ -548,7 +587,7 @@ Andrew Senkevich for contributing vector math function implementations for x86. Carlos Eduardo Seo for optimized functions on PowerPC. @item -Arjun Shankar for testing and bug fixing. +Arjun Shankar for testing, bug fixing, and handbook contributions. @item Marcus Shawcroft for contributing the AArch64 port. @@ -563,6 +602,9 @@ Joe Simmons-Talbott for various fixes. Franz Sirl for various fixes. @item +Malte Skarupke for work on the threading library. + +@item Gavin Smith for various fixes. @item @@ -590,7 +632,8 @@ Ian Lance Taylor for contributing the port to the MIPS DECStation running Ultrix 4 (@code{mips-dec-ultrix4}). @item -Samuel Thibault for numerous improvements to the Hurd port. +Samuel Thibault for maintainership of and numerous improvements to the +Hurd port. @item Pino Toscano for various fixes. @@ -602,6 +645,9 @@ Matt Turner for various fixes to the Alpha port. Valery Ushakov for locale fixes. @item +Feifei Wang for Hygon-related contributions. + +@item Hsiangkai Wang for various fixes. @item @@ -639,13 +685,18 @@ 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, and numerous contributions and fixes. +the work on tunables, fortify improvements, the CORE-MATH integration, +thread safety, and numerous further contributions and fixes. @item Xuelei Zhang for optimized functions on AArch64. @item -Junxian Zhu for work on the MIPS port. +Junxian Zhu for work on the MIPS and RISC-V port. + +@item +Paul Zimmermann for the work on mathematical functions and their +testsuite. @end itemize @@ -709,4 +760,10 @@ Many of the IA64 math functions are taken from a collection of makes available under a free license; see the file @file{LICENSES} for details. +@item +Code for trigonometric, exponential and related functions in the +@file{sysdeps/ieee754/flt-32} subdirectory is shared with the +@code{CORE-MATH} project with main developers Paul Zimmermann and +Alexei Sibidanov, see again the file @file{LICENSES}. + @end itemize diff --git a/manual/creature.texi b/manual/creature.texi index be0a5ac..59a6108 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -194,9 +194,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 @@ -233,6 +233,13 @@ Only some features from this draft standard are supported by @theglibc{}. The older name @code{_ISOC2X_SOURCE} is also supported. @end defvr +@defvr Macro _ISOC2Y_SOURCE +@standards{C2Y, (none)} +If this macro is defined, ISO C2Y extensions to ISO C23 are included. +Only some features from this draft standard are supported by +@theglibc{}. +@end defvr + @defvr Macro __STDC_WANT_LIB_EXT2__ @standards{ISO, (none)} If you define this macro to the value @code{1}, features from ISO/IEC diff --git a/manual/dynlink.texi b/manual/dynlink.texi index 1500a53..3a4864f 100644 --- a/manual/dynlink.texi +++ b/manual/dynlink.texi @@ -352,16 +352,119 @@ support the XGETBV instruction. @node Dynamic Linker Introspection @section Dynamic Linker Introspection -@Theglibc{} provides various functions for querying information from the +@Theglibc{} provides various facilities for querying information from the dynamic linker. +@deftp {Data Type} {struct link_map} + +@cindex link map +A @dfn{link map} is associated with the main executable and each shared +object. Some fields of the link map are accessible to applications and +exposed through the @code{struct link_map}. Applications must not modify +the link map directly. + +Pointers to link maps can be obtained from the @code{_r_debug} variable, +from the @code{RTLD_DI_LINKMAP} request for @code{dlinfo}, and from the +@code{_dl_find_object} function. See below for details. + +@table @code +@item l_addr +@cindex load address +This field contains the @dfn{load address} of the object. This is the +offset that needs to be applied to unrelocated addresses in the object +image (as stored on disk) to form an address that can be used at run +time for accessing data or running code. For position-dependent +executables, the load address is typically zero, and no adjustment is +required. For position-independent objects, the @code{l_addr} field +usually contains the address of the object's ELF header in the process +image. However, this correspondence is not guaranteed because the ELF +header might not be mapped at all, and the ELF file as stored on disk +might use zero as the lowest virtual address. Due to the second +variable, values of the @code{l_addr} field do not necessarily uniquely +identify a shared object. + +On Linux, to obtain the lowest loaded address of the main program, use +@code{getauxval} to obtain the @code{AT_PHDR} and @code{AT_PHNUM} values +for the current process. Alternatively, call +@samp{dlinfo (_r_debug.r_map, &@var{phdr})} +to obtain the number of program headers, and the address of the program +header array will be stored in @var{phdr} +(of type @code{const ElfW(Phdr) *}, as explained below). +These values allow processing the array of program headers and the +address information in the @code{PT_LOAD} entries among them. +This works even when the program was started with an explicit loader +invocation. + +@item l_name +For a shared object, this field contains the file name that the +@theglibc{} dynamic loader used when opening the object. This can be +a relative path (relative to the current directory at process start, +or if the object was loaded later, via @code{dlopen} or +@code{dlmopen}). Symbolic links are not necessarily resolved. + +For the main executable, @code{l_name} is @samp{""} (the empty string). +(The main executable is not loaded by @theglibc{}, so its file name is +not available.) On Linux, the main executable is available as +@file{/proc/self/exe} (unless an explicit loader invocation was used to +start the program). The file name @file{/proc/self/exe} continues to +resolve to the same file even if it is moved within or deleted from the +file system. Its current location can be read using @code{readlink}. +@xref{Symbolic Links}. (Although @file{/proc/self/exe} is not actually +a symbol link, it is only presented as one.) Note that @file{/proc} may +not be mounted, in which case @file{/proc/self/exe} is not available. + +If an explicit loader invocation is used (such as @samp{ld.so +/usr/bin/emacs}), the @file{/proc/self/exe} approach does not work +because the file name refers to the dynamic linker @code{ld.so}, and not +the @code{/usr/bin/emacs} program. An approximation to the executable +path is still available in the @code{@var{info}.dli_fname} member after +calling @samp{dladdr (_r_debug.r_map->l_ld, &@var{info})}. Note that +this could be a relative path, and it is supplied by the process that +created the current process, not the kernel, so it could be inaccurate. + +@item l_ld +This is a pointer to the ELF dynamic segment, an array of tag/value +pairs that provide various pieces of information that the dynamic +linking process uses. On most architectures, addresses in the dynamic +segment are relocated at run time, but on some architectures and in some +run-time configurations, it is necessary to add the @code{l_addr} field +value to obtain a proper address. + +@item l_prev +@itemx l_next +These fields are used to maintain a double-linked linked list of all +link maps within one @code{dlmopen} namespace. Note that there is +currently no thread-safe way to iterate over this list. The +callback-based @code{dl_iterate_phdr} interface can be used instead. +@end table +@end deftp + +@strong{Portability note:} It is not possible to create a @code{struct +link_map} object and pass a pointer to a function that expects a +@code{struct link_map *} argument. Only link map pointers initially +supplied by @theglibc{} are permitted as arguments. In current versions +of @theglibc{}, handles returned by @code{dlopen} and @code{dlmopen} are +pointers to link maps. However, this is not a portable assumption, and +may even change in future versions of @theglibc{}. To obtain the link +map associated with a handle, see @code{dlinfo} and +@code{RTLD_DI_LINKMAP} below. If a function accepts both +@code{dlopen}/@code{dlmopen} handles and @code{struct link_map} pointers +in its @code{void *} argument, that is documented explicitly. + +@subsection Querying information for loaded objects + +The @code{dlinfo} function provides access to internal information +associated with @code{dlopen}/@code{dlmopen} handles and link maps. + @deftypefun {int} dlinfo (void *@var{handle}, int @var{request}, void *@var{arg}) @safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} @standards{GNU, dlfcn.h} This function returns information about @var{handle} in the memory location @var{arg}, based on @var{request}. The @var{handle} argument must be a pointer returned by @code{dlopen} or @code{dlmopen}; it must -not have been closed by @code{dlclose}. +not have been closed by @code{dlclose}. Alternatively, @var{handle} +can be a @code{struct link_map *} value for a link map of an object +that has not been closed. On success, @code{dlinfo} returns 0 for most request types; exceptions are noted below. If there is an error, the function returns @math{-1}, diff --git a/manual/errno.texi b/manual/errno.texi index ce07806..bb8a6cb 100644 --- a/manual/errno.texi +++ b/manual/errno.texi @@ -1256,7 +1256,7 @@ It is a POSIX extension. @deftypefun void perror (const char *@var{message}) @standards{ISO, stdio.h} -@safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} +@safety{@prelim{}@mtunsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Besides strerror_r's and some of fprintf's issues, if stderr is not @c oriented yet, create a new stream with a dup of stderr's fd and write @c to that instead of stderr, to avoid orienting it. diff --git a/manual/examples/add.c b/manual/examples/add.c index 2cf55b4..edeecfc 100644 --- a/manual/examples/add.c +++ b/manual/examples/add.c @@ -1,5 +1,5 @@ /* Example of a Variadic Function - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex1.c b/manual/examples/argp-ex1.c index 48bb1db..a908065 100644 --- a/manual/examples/argp-ex1.c +++ b/manual/examples/argp-ex1.c @@ -1,5 +1,5 @@ /* Argp example #1 -- a minimal program using argp - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex2.c b/manual/examples/argp-ex2.c index ac7f4f9..8e67a6a 100644 --- a/manual/examples/argp-ex2.c +++ b/manual/examples/argp-ex2.c @@ -1,5 +1,5 @@ /* Argp example #2 -- a pretty minimal program using argp - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex3.c b/manual/examples/argp-ex3.c index 022e35d..4d9b501 100644 --- a/manual/examples/argp-ex3.c +++ b/manual/examples/argp-ex3.c @@ -1,5 +1,5 @@ /* Argp example #3 -- a program with options and arguments using argp - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex4.c b/manual/examples/argp-ex4.c index 9847384..9d95807 100644 --- a/manual/examples/argp-ex4.c +++ b/manual/examples/argp-ex4.c @@ -1,5 +1,5 @@ /* Argp example #4 -- a program with somewhat more complicated options - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/atexit.c b/manual/examples/atexit.c index ef62520..6e7ede9 100644 --- a/manual/examples/atexit.c +++ b/manual/examples/atexit.c @@ -1,5 +1,5 @@ /* Cleanups on Exit - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/db.c b/manual/examples/db.c index e3eebd4..7befca7 100644 --- a/manual/examples/db.c +++ b/manual/examples/db.c @@ -1,5 +1,5 @@ /* User and Group Database Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/dir.c b/manual/examples/dir.c index 4232249..b3b6c2b 100644 --- a/manual/examples/dir.c +++ b/manual/examples/dir.c @@ -1,5 +1,5 @@ /* Simple Program to List a Directory - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/dir2.c b/manual/examples/dir2.c index 9473fd4..d692a9c 100644 --- a/manual/examples/dir2.c +++ b/manual/examples/dir2.c @@ -1,5 +1,5 @@ /* Simple Program to List a Directory, Mark II - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/execinfo.c b/manual/examples/execinfo.c index b26d5f3..5e71351 100644 --- a/manual/examples/execinfo.c +++ b/manual/examples/execinfo.c @@ -1,5 +1,5 @@ /* Obtain a backtrace and print it. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/filecli.c b/manual/examples/filecli.c index 9ee20d1..f6ce117 100644 --- a/manual/examples/filecli.c +++ b/manual/examples/filecli.c @@ -1,5 +1,5 @@ /* Example of Reading Datagrams - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/filesrv.c b/manual/examples/filesrv.c index 2a5bbc1..09c80c5 100644 --- a/manual/examples/filesrv.c +++ b/manual/examples/filesrv.c @@ -1,5 +1,5 @@ /* Datagram Socket Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/fmtmsgexpl.c b/manual/examples/fmtmsgexpl.c index 9b8aeff..bd88a62 100644 --- a/manual/examples/fmtmsgexpl.c +++ b/manual/examples/fmtmsgexpl.c @@ -1,5 +1,5 @@ /* How to use fmtmsg and addseverity. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/inetcli.c b/manual/examples/inetcli.c index 1d46be8..657dcdb 100644 --- a/manual/examples/inetcli.c +++ b/manual/examples/inetcli.c @@ -1,5 +1,5 @@ /* Byte Stream Socket Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/inetsrv.c b/manual/examples/inetsrv.c index dc77f61..003a951 100644 --- a/manual/examples/inetsrv.c +++ b/manual/examples/inetsrv.c @@ -1,5 +1,5 @@ /* Byte Stream Connection Server Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/isockad.c b/manual/examples/isockad.c index 4308e6e..7125374 100644 --- a/manual/examples/isockad.c +++ b/manual/examples/isockad.c @@ -1,5 +1,5 @@ /* Internet Socket Example using sockaddr_in. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/longopt.c b/manual/examples/longopt.c index b0cc64a..bf3857b 100644 --- a/manual/examples/longopt.c +++ b/manual/examples/longopt.c @@ -1,5 +1,5 @@ /* Example of Parsing Long Options with getopt_long. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License @@ -66,23 +66,23 @@ main (int argc, char **argv) break; case 'a': - puts ("option -a\n"); + puts ("option -a"); break; case 'b': - puts ("option -b\n"); + puts ("option -b"); break; case 'c': - printf ("option -c with value `%s'\n", optarg); + printf ("option -c with value '%s'\n", optarg); break; case 'd': - printf ("option -d with value `%s'\n", optarg); + printf ("option -d with value '%s'\n", optarg); break; case 'f': - printf ("option -f with value `%s'\n", optarg); + printf ("option -f with value '%s'\n", optarg); break; case '?': diff --git a/manual/examples/memopen.c b/manual/examples/memopen.c index 4d3f8ff..e87006d 100644 --- a/manual/examples/memopen.c +++ b/manual/examples/memopen.c @@ -1,5 +1,5 @@ /* String Streams - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/memstrm.c b/manual/examples/memstrm.c index baf2f3d..28be892 100644 --- a/manual/examples/memstrm.c +++ b/manual/examples/memstrm.c @@ -1,5 +1,5 @@ /* open_memstream example. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License @@ -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/mkdirent.c b/manual/examples/mkdirent.c index f42b137..382185f 100644 --- a/manual/examples/mkdirent.c +++ b/manual/examples/mkdirent.c @@ -1,5 +1,5 @@ /* Example for creating a struct dirent object for use with glob. - Copyright (C) 2016-2024 Free Software Foundation, Inc. + Copyright (C) 2016-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/mkfsock.c b/manual/examples/mkfsock.c index 4810b9c..9cc992b 100644 --- a/manual/examples/mkfsock.c +++ b/manual/examples/mkfsock.c @@ -1,5 +1,5 @@ /* Example of Local-Namespace Sockets - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/mkisock.c b/manual/examples/mkisock.c index e273038..926bb3b 100644 --- a/manual/examples/mkisock.c +++ b/manual/examples/mkisock.c @@ -1,5 +1,5 @@ /* Internet Socket Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/mygetpass.c b/manual/examples/mygetpass.c index 8bb943a..067cb8a 100644 --- a/manual/examples/mygetpass.c +++ b/manual/examples/mygetpass.c @@ -1,5 +1,5 @@ /* Reading passphrases manually. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/ofdlocks.c b/manual/examples/ofdlocks.c index f1339b5..08a978a 100644 --- a/manual/examples/ofdlocks.c +++ b/manual/examples/ofdlocks.c @@ -1,5 +1,5 @@ /* Open File Description Locks Usage Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/pipe.c b/manual/examples/pipe.c index 5dc4dc7..74c8015 100644 --- a/manual/examples/pipe.c +++ b/manual/examples/pipe.c @@ -1,5 +1,5 @@ /* Creating a Pipe - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/popen.c b/manual/examples/popen.c index da76280..18156a9 100644 --- a/manual/examples/popen.c +++ b/manual/examples/popen.c @@ -1,5 +1,5 @@ /* Pipe to a Subprocess - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/rprintf.c b/manual/examples/rprintf.c index 2e76c68..fb774b8 100644 --- a/manual/examples/rprintf.c +++ b/manual/examples/rprintf.c @@ -1,5 +1,5 @@ /* Printf Extension Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/search.c b/manual/examples/search.c index ff8cf6a..0d2b690 100644 --- a/manual/examples/search.c +++ b/manual/examples/search.c @@ -1,5 +1,5 @@ /* Searching and Sorting Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/select.c b/manual/examples/select.c index e1132eb..1398c7f 100644 --- a/manual/examples/select.c +++ b/manual/examples/select.c @@ -1,5 +1,5 @@ /* Waiting for Input or Output - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/setjmp.c b/manual/examples/setjmp.c index afc41ef..95e328d 100644 --- a/manual/examples/setjmp.c +++ b/manual/examples/setjmp.c @@ -1,5 +1,5 @@ /* Introduction to Non-Local Exits - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/sigh1.c b/manual/examples/sigh1.c index 58f3cee..a540651 100644 --- a/manual/examples/sigh1.c +++ b/manual/examples/sigh1.c @@ -1,5 +1,5 @@ /* Signal Handlers that Return - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/sigusr.c b/manual/examples/sigusr.c index cdfef7b..13874fd 100644 --- a/manual/examples/sigusr.c +++ b/manual/examples/sigusr.c @@ -1,5 +1,5 @@ /* Using kill for Communication - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/stpcpy.c b/manual/examples/stpcpy.c index f0f45a4..a64714c 100644 --- a/manual/examples/stpcpy.c +++ b/manual/examples/stpcpy.c @@ -1,5 +1,5 @@ /* stpcpy example. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/strdupa.c b/manual/examples/strdupa.c index 54163ce..7fd2293 100644 --- a/manual/examples/strdupa.c +++ b/manual/examples/strdupa.c @@ -1,5 +1,5 @@ /* strdupa example. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/strftim.c b/manual/examples/strftim.c index 6e1e047..d2da14c 100644 --- a/manual/examples/strftim.c +++ b/manual/examples/strftim.c @@ -1,5 +1,5 @@ /* Time Functions Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/subopt.c b/manual/examples/subopt.c index 1bbb541..e7a0730 100644 --- a/manual/examples/subopt.c +++ b/manual/examples/subopt.c @@ -1,5 +1,5 @@ /* Parsing of Suboptions Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/swapcontext.c b/manual/examples/swapcontext.c index c07e19b..9310558 100644 --- a/manual/examples/swapcontext.c +++ b/manual/examples/swapcontext.c @@ -1,5 +1,5 @@ /* Complete Context Control - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/termios.c b/manual/examples/termios.c index ba70a01..c2b40e7 100644 --- a/manual/examples/termios.c +++ b/manual/examples/termios.c @@ -1,5 +1,5 @@ /* Noncanonical Mode Example - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/testopt.c b/manual/examples/testopt.c index 1452c47..57e7128 100644 --- a/manual/examples/testopt.c +++ b/manual/examples/testopt.c @@ -1,5 +1,5 @@ /* Example of Parsing Arguments with getopt. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/timespec_subtract.c b/manual/examples/timespec_subtract.c index 2660740..9cbd2d7 100644 --- a/manual/examples/timespec_subtract.c +++ b/manual/examples/timespec_subtract.c @@ -1,5 +1,5 @@ /* struct timespec subtraction. - Copyright (C) 1991-2024 Free Software Foundation, Inc. + Copyright (C) 1991-2025 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/twalk.c b/manual/examples/twalk.c index 88a1572..e9aa13d 100644 --- a/manual/examples/twalk.c +++ b/manual/examples/twalk.c @@ -1,5 +1,5 @@ /* Implement twalk using twalk_r. - Copyright (C) 2019-2024 Free Software Foundation, Inc. + Copyright (C) 2019-2025 Free Software Foundation, Inc. The GNU C Library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public diff --git a/manual/filesys.texi b/manual/filesys.texi index 47d9297..e1c7be8 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -15,6 +15,7 @@ access permissions and modification times. @menu * Working Directory:: This is used to resolve relative file names. +* Descriptor-Relative Access:: Ways to control file name lookup. * Accessing Directories:: Finding out what files a directory contains. * Working with Directory Trees:: Apply actions to all files or a selectable @@ -206,6 +207,178 @@ An I/O error occurred. @end table @end deftypefun +@node Descriptor-Relative Access +@section Descriptor-Relative Access +@cindex file name resolution based on descriptors +@cindex descriptor-based file name resolution +@cindex @code{@dots{}at} functions + +Many functions that accept file names have @code{@dots{}at} variants +which accept a file descriptor and a file name argument instead of just +a file name argument. For example, @code{fstatat} is the +descriptor-based variant of the @code{fstat} function. Most such +functions also accept an additional flags argument which changes the +behavior of the file name lookup based on the passed @code{AT_@dots{}} +flags. + +There are several reasons to use descriptor-relative access: + +@itemize @bullet +@item +The working directory is a process-wide resource, so individual threads +cannot change it without affecting other threads in the process. +Explicitly specifying the directory against which relative paths are +resolved can be a thread-safe alternative to changing the working +directory. + +@item +If a program wishes to access a directory tree which is being modified +concurrently, perhaps even by a different user on the system, the +program must avoid looking up file names with multiple components, in +order to detect symbolic links, using the @code{O_NOFOLLOW} flag +(@pxref{Open-time Flags}) or the @code{AT_SYMLINK_FOLLOW} flag +(described below). Without directory-relative access, it is necessary +to use the @code{fchdir} function to change the working directory +(@pxref{Working Directory}), which is not thread-safe. + +@item +Listing directory contents using the @code{readdir} or @code{readdir64} +functions (@pxref{Reading/Closing Directory}) does not provide full file +name paths. Using @code{@dots{}at} functions, it is possible to use the +file names directly, without having to construct such full paths. + +@item +Additional flags available with some of the @code{@dots{}at} functions +provide access to functionality which is not available otherwise. +@end itemize + +The file descriptor used by these @code{@dots{}at} functions has the +following uses: + +@itemize @bullet +@item +It can be a file descriptor referring to a directory. Such a descriptor +can be created explicitly using the @code{open} function and the +@code{O_RDONLY} file access mode, with or without the @code{O_DIRECTORY} +flag. @xref{Opening and Closing Files}. Or it can be created +implicitly by @code{opendir} and retrieved using the @code{dirfd} +function. @xref{Opening a Directory}. + +If a directory descriptor is used with one of the @code{@dots{}at} +functions, a relative file name argument is resolved relative to +directory referred to by the file descriptor, just as if that directory +were the current working directory. Absolute file name arguments +(starting with @samp{/}) are resolved against the file system root, and +the descriptor argument is effectively ignored. + +This means that file name lookup is not constrained to the directory of +the descriptor. For example, it is possible to access a file +@file{example} in the descriptor's parent directory using a file name +argument @code{"../example"}, or in the root directory using +@code{"/example"}. + +If the file descriptor refers to a directory, the empty string @code{""} +is not a valid file name argument. It is possible to use @code{"."} to +refer to the directory itself. Also see @code{AT_EMPTY_PATH} below. + +@item +@vindex @code{AT_FDCWD} +The special value @code{AT_FDCWD}. This means that the current working +directory is used for the lookup if the file name is a relative. For +@code{@dots{}at} functions with an @code{AT_@dots{}} flags argument, +this provides a shortcut to use those flags with regular (not +descriptor-based) file name lookups. + +If @code{AT_FDCWD} is used, the empty string @code{""} is not a valid +file name argument. + +@item +An arbitrary file descriptor, along with an empty string @code{""} as +the file name argument, and the @code{AT_EMPTY_PATH} flag. In this +case, the operation uses the file descriptor directly, without further +file name resolution. On Linux, this allows operations on descriptors +opened with the @code{O_PATH} flag. For regular descriptors (opened +without @code{O_PATH}), the same functionality is also available through +the plain descriptor-based functions (for example, @code{fstat} instead +of @code{fstatat}). + +This is a GNU extension. +@end itemize + +@cindex file name resolution flags +@cindex @code{AT_*} file name resolution flags +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. 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 +This flag is used with an empty file name @code{""} and a descriptor +which does not necessarily refer to a directory. It is most useful with +@code{O_PATH} descriptors, as described above. This flag is a GNU +extension. + +@item AT_NO_AUTOMOUNT +If the effective final path component refers to a potential file system +mount point controlled by an auto-mounting service, the operation does +not trigger auto-mounting and refers to the unmounted mount point +instead. @xref{Mount-Unmount-Remount}. If a file system has already +been mounted at the effective final path component, the operation +applies to the file or directory in the mounted file system, not the +underlying file system that was mounted over. This flag is a GNU +extension. + +@item AT_SYMLINK_FOLLOW +If the effective final path component is a symbolic link, the +operation follows the symbolic link and operates on its target. (For +most functions, this is the default behavior.) + +@item AT_SYMLINK_NOFOLLOW +If the effective final path component is a symbolic link, the +operation operates on the symbolic link, without following it. The +difference in behavior enabled by this flag is similar to the difference +between the @code{lstat} and @code{stat} functions, or the behavior +activated by the @code{O_NOFOLLOW} argument to the @code{open} function. +Even with the @code{AT_SYMLINK_NOFOLLOW} flag present, symbolic links in +a non-final component of the file name are still followed. +@end vtable + +@strong{Note:} There is no relationship between these flags and the type +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 @@ -263,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 @@ -311,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}) @@ -486,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: @@ -666,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}) @@ -677,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}) @@ -690,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 @@ -861,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 @@ -1250,10 +1485,11 @@ A hardware error occurred while trying to read or write the to filesystem. The @code{linkat} function is analogous to the @code{link} function, except that it identifies its source and target using a combination of a -file descriptor (referring to a directory) and a pathname. If a -pathnames is not absolute, it is resolved relative to the corresponding -file descriptor. The special file descriptor @code{AT_FDCWD} denotes -the current directory. +file descriptor (referring to a directory) and a file name. +@xref{Descriptor-Relative Access}. For @code{linkat}, if a file name is +not absolute, it is resolved relative to the corresponding file +descriptor. As usual, the special value @code{AT_FDCWD} denotes the +current directory. The @var{flags} argument is a combination of the following flags: @@ -1543,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{}} @@ -1674,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 @@ -1728,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 @@ -2091,9 +2377,44 @@ function is available under the name @code{fstat} and so transparently replaces the interface for small files on 32-bit machines. @end deftypefun -@c fstatat will call alloca and snprintf if the syscall is not -@c available. -@c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@deftypefun int fstatat (int @var{filedes}, const char *@var{filename}, struct stat *@var{buf}, int @var{flags}) +@standards{POSIX.1, sys/stat.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function is a descriptor-relative version of the @code{fstat} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument can contain a combination of the flags @code{AT_EMPTY_PATH}, +@code{AT_NO_AUTOMOUNT}, @code{AT_SYMLINK_NOFOLLOW}. + +Compared to @code{fstat}, the following additional error conditions can +occur: + +@table @code +@item EBADF +The @var{filedes} argument is not a valid file descriptor. + +@item EINVAL +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. +@end table + +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this +function is in fact @code{fstatat64} since the LFS interface transparently +replaces the normal implementation. +@end deftypefun + +@deftypefun int fstatat64 (int @var{filedes}, const char *@var{filename}, struct stat64 *@var{buf}, int @var{flags}) +@standards{GNU, sys/stat.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function is the large-file variant of @code{fstatat}, similar to +how @code{fstat64} is the variant of @code{fstat}. + +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this +function is available under the name @code{fstatat} and so transparently +replaces the interface for small files on 32-bit machines. +@end deftypefun @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf}) @standards{BSD, sys/stat.h} @@ -2798,6 +3119,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 @@ -2966,6 +3310,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. @@ -2975,6 +3323,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 @@ -3578,22 +3984,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 3e68a3d..006f93b 100644 --- a/manual/install.texi +++ b/manual/install.texi @@ -75,6 +75,14 @@ and @theglibc{} cannot be compiled without optimization, so if $ ../glibc-@var{version}/configure CC="gcc -m32" CFLAGS="-O3" @end smallexample +To test @theglibc{} with a different set of C and C++ compilers, +@samp{TEST_CC=@var{compiler}} and @samp{TEST_CXX=@var{compiler}} +arguments can be passed to @code{configure}. For example: + +@smallexample +$ ../glibc-@var{version}/configure TEST_CC="gcc-6.4.1" TEST_CXX="g++-6.4.1" +@end smallexample + The following list describes all of the available options for @code{configure}: @@ -522,32 +530,14 @@ As of release time, GNU @code{make} 4.4.1 is the newest verified to work to build @theglibc{}. @item -GCC 6.2 or newer +GCC 12.1 or newer -GCC 6.2 or higher is required. In general it is recommended to use +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.1 is the newest compiler verified to work to build +release time, GCC 14.2.1 is the newest compiler verified to work to build @theglibc{}. -For PowerPC 64-bits little-endian (powerpc64le), a GCC version with support -for @option{-mno-gnu-attribute}, @option{-mabi=ieeelongdouble}, and -@option{-mabi=ibmlongdouble} is required. Likewise, the compiler must also -support passing @option{-mlong-double-128} with the preceding options. As -of release, this implies GCC 7.4 and newer (excepting GCC 7.5.0, see GCC -PR94200). These additional features are required for building the GNU C -Library with support for IEEE long double. - -@c powerpc64le performs an autoconf test to verify the compiler compiles with -@c commands like "$CC -c foo.c -mabi=ibmlongdouble -mlong-double-128". - -For ARC architecture builds, GCC 8.3 or higher is needed. - -For s390x architecture builds, GCC 7.1 or higher is needed (See gcc Bug 98269). - -For AArch64 architecture builds with mathvec enabled, GCC 10 or higher is needed -due to dependency on arm_sve.h. - For multi-arch support it is recommended to use a GCC which has been built with support for GNU indirect functions. This ensures that correct debugging information is generated for functions selected by IFUNC resolvers. This @@ -562,19 +552,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.42 is the newest +moment. As of release time, GNU @code{binutils} 2.43.1 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 @@ -582,7 +566,7 @@ To correctly translate and install the Texinfo documentation you need this version of the @code{texinfo} package. Earlier versions do not understand all the tags used in the document, and the installation mechanism for the info files is not present or works differently. -As of release time, @code{texinfo} 7.1 is the newest verified to work +As of release time, @code{texinfo} 7.2 is the newest verified to work to build @theglibc{}. @item @@ -591,9 +575,13 @@ 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.0 is the newest verified +As of release time, @code{gawk} version 5.3.1 is the newest verified to work to build @theglibc{}. +Testing the GNU C Library requires @code{gawk} to be compiled with +support for high precision arithmetic via the @code{MPFR} +multiple-precision floating-point computation library. + @item GNU @code{bison} 2.7 or later @@ -620,7 +608,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 is the newest verified to work for building and testing +3.12.8 is the newest verified to work for building and testing @theglibc{}. @item PExpect 4.0 @@ -669,7 +657,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.22.4 is the newest +As of release time, GNU @code{gettext} version 0.23 is the newest version verified to work to build @theglibc{}. @end itemize @@ -721,7 +709,7 @@ if you configure @theglibc{} with @samp{--prefix=/usr}. If you set some other prefix or allow it to default to @file{/usr/local}, then all the components are installed there. -As of release time, Linux version 6.6 is the newest stable version verified +As of release time, Linux version 6.12 is the newest stable version verified to work to build @theglibc{}. @node Reporting Bugs diff --git a/manual/intro.texi b/manual/intro.texi index 879c1b3..d956484 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -966,13 +966,25 @@ functionality is available on commercial systems. @Theglibc{} includes by reference the Linux man-pages @value{man_pages_version} documentation to document the listed -syscalls for the Linux kernel. For reference purposes only the latest +syscalls for the Linux kernel. For reference purposes only, the latest @uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project} documentation can be accessed from the @uref{https://www.kernel.org,Linux kernel} website. Where the syscall has more specific documentation in this manual that more specific documentation is considered authoritative. +Throughout this manual, when we refer to a man page, for example: +@quotation +@manpageurl{sendmsg,2} +@end quotation +@noindent +we are referring primarily to the specific version noted above (the +``normative'' version), typically accessed by running (for example) +@code{man 2 sendmsg} on a system with that version installed. For +convenience, we will also link to the online latest copy of the man +pages, but keep in mind that version will almost always be newer than, +and thus different than, the normative version noted above. + Additional details on the Linux system call interface can be found in @xref{System Calls}. diff --git a/manual/ipc.texi b/manual/ipc.texi index 6a6e5ad..f9c7638 100644 --- a/manual/ipc.texi +++ b/manual/ipc.texi @@ -20,7 +20,7 @@ by @theglibc{}. @c Need descriptions for all of these functions. @subsection System V Semaphores -@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd}); +@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd}) @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}} @c syscall(ipc) ok @c @@ -30,87 +30,22 @@ by @theglibc{}. @c semid_ds. @end deftypefun -@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg}); +@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c syscall(ipc) ok @end deftypefun -@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}); +@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c syscall(ipc) ok @end deftypefun -@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout}); +@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c syscall(ipc) ok @end deftypefun @subsection POSIX Semaphores - -@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}); -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} -@c Does not atomically update sem_t therefore AC-unsafe -@c because it can leave sem_t partially initialized. -@end deftypefun - -@deftypefun int sem_destroy (sem_t *@var{sem}); -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Function does nothing and is therefore always safe. -@end deftypefun - -@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...); -@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} -@c pthread_once asuinit -@c -@c We are AC-Unsafe because we use pthread_once to initialize -@c a global variable that holds the location of the mounted -@c shmfs on Linux. -@end deftypefun - -@deftypefun int sem_close (sem_t *@var{sem}); -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c lll_lock asulock aculock -@c twalk mtsrace{:root} -@c -@c We are AS-unsafe because we take a non-recursive lock. -@c We are AC-unsafe because several internal data structures -@c are not updated atomically. -@end deftypefun - -@deftypefun int sem_unlink (const char *@var{name}); -@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} -@c pthread_once asuinit acucorrupt aculock -@c mempcpy acucorrupt -@end deftypefun - -@deftypefun int sem_wait (sem_t *@var{sem}); -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} -@c atomic_fetch_add_relaxed (nwaiters) acucorrupt -@c -@c Given the use atomic operations this function seems -@c to be AS-safe. It is AC-unsafe because there is still -@c a window between atomic_fetch_add_relaxed and the pthread_push -@c of the handler that undoes that operation. A cancellation -@c at that point would fail to remove the process from the -@c waiters count. -@end deftypefun - -@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}); -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} -@c Same safety issues as sem_wait. -@end deftypefun - -@deftypefun int sem_trywait (sem_t *@var{sem}); -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c All atomic operations are safe in all contexts. -@end deftypefun - -@deftypefun int sem_post (sem_t *@var{sem}); -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Same safety as sem_trywait. -@end deftypefun - -@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}); -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Atomic write of a value is safe in all contexts. -@end deftypefun +@Theglibc{} provides POSIX semaphores as well. These functions' names begin +with @code{sem_} and they are declared in @file{semaphore.h}. @xref{POSIX +Semaphores}. diff --git a/manual/libc.texinfo b/manual/libc.texinfo index 43c9137..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 @@ -51,7 +51,7 @@ This is @value{VERSION} @value{PKGVERSION}. @end ifclear -Copyright @copyright{} 1993--2024 Free Software Foundation, Inc. +Copyright @copyright{} 1993--2025 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version diff --git a/manual/llio.texi b/manual/llio.texi index ea84196..7b5f77b 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -181,6 +181,43 @@ new, extended API using 64 bit file sizes and offsets transparently replaces the old API. @end deftypefun +@deftypefun int openat (int @var{filedes}, const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) +@standards{POSIX.1, fcntl.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} +This function is the descriptor-relative variant of the @code{open} +function. @xref{Descriptor-Relative Access}. + +Note that the @var{flags} argument of @code{openat} does not accept +@code{AT_@dots{}} flags, only the flags described for the @code{open} +function above. + +The @code{openat} function can fail for additional reasons: + +@table @code +@item EBADF +The @var{filedes} argument is not a valid file descriptor. + +@item ENOTDIR +The descriptor @var{filedes} is not associated with a directory, and +@var{filename} is a relative file name. +@end table + +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this +function is in fact @code{openat64} since the LFS interface transparently +replaces the normal implementation. +@end deftypefun + +@deftypefun int openat64 (int @var{filedes}, const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) +@standards{GNU, fcntl.h} +The large-file variant of the @code{openat}, similar to how +@code{open64} is the large-file variant of @code{open}. + +When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this +function is actually available under the name @code{openat}. I.e., the +new, extended API using 64 bit file sizes and offsets transparently +replaces the old API. +@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{}}} @@ -1060,6 +1097,27 @@ streams persist in other processes, their file positions become undefined as a result. To prevent this, you must clean up the streams before destroying them. +In addition to cleaning up a stream before doing I/O using another +linked channel, additional precautions are needed to ensure a +well-defined file position indicator in some cases. If both the +following conditions hold, you must set the file position indicator on +the new channel (a stream) using a function such as @code{fseek}. + +@itemize @bullet +@item +The new linked channel is a stream that was previously active. + +@item +The file position indicator was previously set on that channel (while +it was previously active) with a function such as @code{fseek}. +@end itemize + +POSIX requires such precautions in more cases: if either the old or +the new linked channel is a stream (whether or not previously active) +and the file position indicator was previously set on any channel +linked to those channels with a function such as @code{fseek} or +@code{lseek}. + @node Independent Channels @subsection Independent Channels @cindex independent channels @@ -1344,6 +1402,19 @@ Per-IO synchronization as if the file was opened with @code{O_APPEND} flag. @item RWF_NOAPPEND This flag allows an offset to be honored, even if the file was opened with @code{O_APPEND} flag. + +@item RWF_ATOMIC +Indicate that the write is to be issued with torn-write prevention. The +input buffer should follow some contraints: the total length should be +power-of-2 in size and also sizes between @code{atomic_write_unit_min} +and @code{atomic_write_unit_max}, the @code{struct iovec} count should be +up to @code{atomic_write_segments_max}, and the offset should be +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. + +This is a Linux-specific extension. @end vtable When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the @@ -1622,6 +1693,8 @@ existing map is unmapped. @c Which is which? @item MAP_ANONYMOUS @itemx MAP_ANON +@standards{POSIX.1-2024, sys/mman.h} +@standardsx{MAP_ANON, POSIX.1-2024, sys/mman.h} This flag tells the system to create an anonymous mapping, not connected to a file. @var{filedes} and @var{offset} are ignored, and the region is initialized with zeros. @@ -1725,6 +1798,15 @@ write dirty metadata out whenever dirty data is written out. Unlike most other flags, this one will fail unless @code{MAP_SHARED_VALIDATE} is also given. +@item MAP_DROPPABLE +Request the page to be never written out to swap, it will be zeroed +under memory pressure (so kernel can just drop the page), it is inherited +by fork, it is not counted against @code{mlock} budget, and if there is +not enough memory to service a page fault there is no fatal error (so no +signal is sent). + +The @code{MAP_DROPPABLE} flag is specific to Linux. + @end vtable @code{mmap} returns the address of the new mapping, or @@ -3559,11 +3641,14 @@ duplicate of @var{old}. @end deftypefun @deftypefun int dup3 (int @var{old}, int @var{new}, int @var{flags}) -@standards{Linux, unistd.h} +@standards{POSIX.1-2024, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is the same as @code{dup2} but creates the new descriptor as if it had been opened with flags @var{flags}. The only allowed flag is @code{O_CLOEXEC}. + +This function was originally a Linux extension, but was added in +POSIX.1-2024. @end deftypefun @deftypevr Macro int F_DUPFD @@ -3807,7 +3892,9 @@ contains it is still needed), and permissions are checked when the descriptor is used later on. For example, such descriptors can be used with the @code{fexecve} -function (@pxref{Executing a File}). +function (@pxref{Executing a File}). Other applications involve the +@samp{*at} function variants, along with the @code{AT_EMPTY_PATH} flag. +@xref{Descriptor-Relative Access}. This access mode is specific to Linux. On @gnuhurdsystems{}, it is possible to use @code{O_EXEC} explicitly, or specify no access modes @@ -4792,12 +4879,12 @@ of an IOCTL, see @ref{Out-of-Band Data}. @manpagefunctionstub{poll,2} @end deftypefun -@deftypefun int epoll_create(int @var{size}) +@deftypefun int epoll_create (int @var{size}) @manpagefunctionstub{epoll_create,2} @end deftypefun -@deftypefun int epoll_wait(int @var{epfd}, struct epoll_event *@var{events}, int @var{maxevents}, int @var{timeout}) +@deftypefun int epoll_wait (int @var{epfd}, struct epoll_event *@var{events}, int @var{maxevents}, int @var{timeout}) @manpagefunctionstub{epoll_wait,2} @end deftypefun diff --git a/manual/macros.texi b/manual/macros.texi index 579da3f..2003ce2 100644 --- a/manual/macros.texi +++ b/manual/macros.texi @@ -282,11 +282,22 @@ cwd\comments\ @macro standardsx {element, standard, header} @end macro +@ifhtml +@macro manpageurl {func, sec} +@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html,,\func\(\sec\)} +@xref{Linux Kernel} +@end macro +@end ifhtml +@ifnothtml +@macro manpageurl {func, sec} +\func\(\sec\) (Latest, online: @url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}) +@xref{Linux Kernel} +@end macro +@end ifnothtml + @macro manpagefunctionstub {func,sec} This documentation is a stub. For additional information on this -function, consult the manual page -@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}. -@xref{Linux Kernel}. +function, consult the manual page @manpageurl{\func\,\sec\}. @end macro @end ifclear diff --git a/manual/maint.texi b/manual/maint.texi index 04faa22..3176546 100644 --- a/manual/maint.texi +++ b/manual/maint.texi @@ -303,6 +303,10 @@ The following functions and macros are fortified in @theglibc{}: @item @code{getwd} +@item @code{inet_ntop} + +@item @code{inet_pton} + @item @code{longjmp} @item @code{mbsnrtowcs} @@ -492,7 +496,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 diff --git a/manual/math.texi b/manual/math.texi index e4f9122..fbabf37 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -80,7 +80,7 @@ aarch64, alpha, loongarch, mips64, riscv, s390 and sparc. * Exponents and Logarithms:: Also pow and sqrt. * Hyperbolic Functions:: sinh, cosh, tanh, etc. * Special Functions:: Bessel, gamma, erf. -* Errors in Math Functions:: Known Maximum Errors in Math Functions. +* Errors in Math Functions:: Remarks in Errors in Math Functions. * Pseudo-Random Numbers:: Functions for generating pseudo-random numbers. * FP Function Optimizations:: Fast code or small code. @@ -240,6 +240,44 @@ All these functions, including the @code{_Float@var{N}} and should be prepared to cope with their absence. @end deftypefun +@deftypefun double sinpi (double @var{x}) +@deftypefunx float sinpif (float @var{x}) +@deftypefunx {long double} sinpil (long double @var{x}) +@deftypefunx _FloatN sinpifN (_Float@var{N} @var{x}) +@deftypefunx _FloatNx sinpifNx (_Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These functions return the sine of pi multiplied by @var{x}. The +return value is in the range @code{-1} to @code{1}. + +The @code{sinpi} functions are from TS 18661-4:2015. +@end deftypefun + +@deftypefun double cospi (double @var{x}) +@deftypefunx float cospif (float @var{x}) +@deftypefunx {long double} cospil (long double @var{x}) +@deftypefunx _FloatN cospifN (_Float@var{N} @var{x}) +@deftypefunx _FloatNx cospifNx (_Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These functions return the cosine of pi multiplied by @var{x}. The +return value is in the range @code{-1} to @code{1}. + +The @code{cospi} functions are from TS 18661-4:2015. +@end deftypefun + +@deftypefun double tanpi (double @var{x}) +@deftypefunx float tanpif (float @var{x}) +@deftypefunx {long double} tanpil (long double @var{x}) +@deftypefunx _FloatN tanpifN (_Float@var{N} @var{x}) +@deftypefunx _FloatNx tanpifNx (_Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These functions return the tangent of pi multiplied by @var{x}. + +The @code{tanpi} functions are from TS 18661-4:2015. +@end deftypefun + @cindex complex trigonometric functions @w{ISO C99} defines variants of the trig functions which work on @@ -404,6 +442,68 @@ Logarithms}.) If both @var{x} and @var{y} are zero, @code{atan2} returns zero. @end deftypefun +@deftypefun double asinpi (double @var{x}) +@deftypefunx float asinpif (float @var{x}) +@deftypefunx {long double} asinpil (long double @var{x}) +@deftypefunx _FloatN asinpifN (_Float@var{N} @var{x}) +@deftypefunx _FloatNx asinpifNx (_Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These functions compute the arcsine of @var{x}, divided by pi. The +result is in the interval between @code{-0.5} and @code{0.5} (inclusive). + +The arcsine function is defined mathematically only over the domain +@code{-1} to @code{1}. If @var{x} is outside the domain, +@code{asinpi} signals a domain error. + +The @code{asinpi} functions are from TS 18661-4:2015. +@end deftypefun + +@deftypefun double acospi (double @var{x}) +@deftypefunx float acospif (float @var{x}) +@deftypefunx {long double} acospil (long double @var{x}) +@deftypefunx _FloatN acospifN (_Float@var{N} @var{x}) +@deftypefunx _FloatNx acospifNx (_Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These functions compute the arccosine of @var{x}, divided by pi. The +result is in the interval between @code{0} and @code{1} (inclusive). + +The arccosine function is defined mathematically only +over the domain @code{-1} to @code{1}. If @var{x} is outside the +domain, @code{acospi} signals a domain error. + +The @code{acospi} functions are from TS 18661-4:2015. +@end deftypefun + +@deftypefun double atanpi (double @var{x}) +@deftypefunx float atanpif (float @var{x}) +@deftypefunx {long double} atanpil (long double @var{x}) +@deftypefunx _FloatN atanpifN (_Float@var{N} @var{x}) +@deftypefunx _FloatNx atanpifNx (_Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These functions compute the arctangent of @var{x}, divided by pi. The +result is in the interval between @code{-0.5} and @code{0.5} +(inclusive). + +The @code{atanpi} functions are from TS 18661-4:2015. +@end deftypefun + +@deftypefun double atan2pi (double @var{y}, double @var{x}) +@deftypefunx float atan2pif (float @var{y}, float @var{x}) +@deftypefunx {long double} atan2pil (long double @var{y}, long double @var{x}) +@deftypefunx _FloatN atan2pifN (_Float@var{N} @var{y}, _Float@var{N} @var{x}) +@deftypefunx _FloatNx atan2pifNx (_Float@var{N}x @var{y}, _Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These function computes the arctangent of @var{y}/@var{x}, divided by +pi, with the signs of both arguments used to determine the quadrant of +the result, as for @code{atan2}. + +The @code{atan2pi} functions are from TS 18661-4:2015. +@end deftypefun + @cindex inverse complex trigonometric functions @w{ISO C99} defines complex versions of the inverse trig functions. @@ -674,6 +774,51 @@ do that, so instead it signals a domain error. @code{pow} may also underflow or overflow the destination type. @end deftypefun +@deftypefun double powr (double @var{base}, double @var{power}) +@deftypefunx float powrf (float @var{base}, float @var{power}) +@deftypefunx {long double} powrl (long double @var{base}, long double @var{power}) +@deftypefunx _FloatN powrfN (_Float@var{N} @var{base}, _Float@var{N} @var{power}) +@deftypefunx _FloatNx powrfNx (_Float@var{N}x @var{base}, _Float@var{N}x @var{power}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These return @var{base} raised to @var{power}, but with special cases +based on @code{exp (power * log (base))}. For example, if @var{base} +is negative, the @code{powr} functions always signal a domain error, +but this is valid for @code{pow} if @var{power} is an integer. + +The @code{powr} functions are from TS 18661-4:2015. +@end deftypefun + +@deftypefun double pown (double @var{base}, long long int @var{power}) +@deftypefunx float pownf (float @var{base}, long long int @var{power}) +@deftypefunx {long double} pownl (long double @var{base}, long long int @var{power}) +@deftypefunx _FloatN pownfN (_Float@var{N} @var{base}, long long int @var{power}) +@deftypefunx _FloatNx pownfNx (_Float@var{N}x @var{base}, long long int @var{power}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These return @var{base} raised to @var{power} (an integer). + +The @code{pown} 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 + +@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}) @@ -690,6 +835,19 @@ If @var{x} is negative, @code{sqrt} signals a domain error. Mathematically, it should return a complex number. @end deftypefun +@deftypefun double rsqrt (double @var{x}) +@deftypefunx float rsqrtf (float @var{x}) +@deftypefunx {long double} rsqrtl (long double @var{x}) +@deftypefunx _FloatN rsqrtfN (_Float@var{N} @var{x}) +@deftypefunx _FloatNx rsqrtfNx (_Float@var{N}x @var{x}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These functions return the reciprocal of the nonnegative square root of @var{x}. +If @var{x} is negative, @code{rsqrt} signals a domain error. + +The @code{rsqrt} functions are from TS 18661-4:2015. +@end deftypefun + @cindex cube root function @deftypefun double cbrt (double @var{x}) @deftypefunx float cbrtf (float @var{x}) @@ -725,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}) @@ -1348,12 +1522,11 @@ extensions. @end deftypefun @node Errors in Math Functions -@section Known Maximum Errors in Math Functions +@section Errors in Math Functions @cindex math errors @cindex ulps -This section lists the known errors of the functions in the math -library. Errors are measured in ``units of the last place''. This is a +Errors are measured in ``units of the last place''. This is a measure for the relative error. For a number @math{z} with the representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE floating-point numbers with base 2) the ULP is represented by @@ -1463,22 +1636,25 @@ functions. @end itemize Therefore many of the functions in the math library have errors. The -table lists the maximum error for each function which is exposed by one -of the existing tests in the test suite. The table tries to cover as much -as possible and list the actual maximum error (or at least a ballpark -figure) but this is often not achieved due to the large search space. - -The table lists the ULP values for different architectures. Different -architectures have different results since their hardware support for -floating-point operations varies and also the existing hardware support -is different. Only the round-to-nearest rounding mode is covered by -this table. Functions not listed do not have known errors. Vector -versions of functions in the x86_64 libmvec library have a maximum error -of 4 ulps. - -@page -@c This multitable does not fit on a single page -@include libm-err.texi +math testsuite only flags results larger than 9ulp (or 16 for IBM +@code{long double} format) as errors; although most of the implementations +show errors smaller than the limit. + +A more comprehensive analysis of @theglibc{} math functions precision could +be found in 'Accuracy of Mathematical Functions in Single, Double, Double +Extended, and Quadruple Precision'; Brian Gladman, Vincenzo Innocente, +John Mather, and Paul Zimmermann at +@url{<https://inria.hal.science/hal-03141101>}. It does not cover complex +functions, nor @code{jn}/@code{yn}, and it is only for x86_64, and for +rounding to nearest, and does not cover any architecture variations (in +particular IBM @code{long double} is out of scope). + +For complex functions, some analysis of @theglibc{} math functions can be +found in 'Accuracy of Complex Mathematical Operations and Functions in Single +and Double Precision'; Paul Caprioli, Vincenzo Innocente, Paul Zimmermann +at @url{https://inria.hal.science/hal-04714173}. It only covers @code{float} +and @code{double}, only for x86_64, and for rounding to nearest, and does not +cover any architecture variations. @node Pseudo-Random Numbers @section Pseudo-Random Numbers diff --git a/manual/memory.texi b/manual/memory.texi index 3710d7e..46f76c1 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -842,8 +842,8 @@ is left undisturbed. @end deftypefun @deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size}) -@standards{BSD, malloc.h} -@standards{BSD, stdlib.h} +@standards{POSIX.1-2024, malloc.h} +@standards{POSIX.1-2024, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} The @code{reallocarray} function changes the size of the block whose address @@ -856,8 +856,8 @@ returning a null pointer, and leaving the original block unchanged. @code{reallocarray} should be used instead of @code{realloc} when the new size of the allocated block is the result of a multiplication that might overflow. -@strong{Portability Note:} This function is not part of any standard. It was -first introduced in OpenBSD 5.6. +This function was originally derived from OpenBSD 5.6, but was added in +POSIX.1-2024. @end deftypefun Like @code{malloc}, @code{realloc} and @code{reallocarray} may return a null @@ -1413,7 +1413,7 @@ This is the total size of memory allocated with @code{sbrk} by @item size_t ordblks This is the number of chunks not in use. (The memory allocator -size_ternally gets chunks of memory from the operating system, and then +internally gets chunks of memory from the operating system, and then carves them up to satisfy individual @code{malloc} requests; @pxref{The GNU Allocator}.) @@ -2935,7 +2935,7 @@ exceed the process' data storage limit. @end deftypefun -@deftypefun void *sbrk (ptrdiff_t @var{delta}) +@deftypefun {void *} sbrk (ptrdiff_t @var{delta}) @standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @@ -3077,7 +3077,7 @@ returned by @code{mmap} or @code{mmap64}. @cindex memory protection key @cindex protection key @cindex MPK -On some systems, further restrictions can be added to specific pages +On some systems, further access restrictions can be added to specific pages using @dfn{memory protection keys}. These restrictions work as follows: @itemize @bullet @@ -3089,27 +3089,27 @@ during memory accesses. New keys can be allocated with the @code{pkey_mprotect}. @item -Each thread has a set of separate access right restriction for each -protection key. These access rights can be manipulated using the +Each thread has a set of separate access restrictions for each +protection key. These access restrictions can be manipulated using the @code{pkey_set} and @code{pkey_get} functions. @item During a memory access, the system obtains the protection key for the -accessed page and uses that to determine the applicable access rights, +accessed page and uses that to determine the applicable access restrictions, as configured for the current thread. If the access is restricted, a segmentation fault is the result ((@pxref{Program Error Signals}). These checks happen in addition to the @code{PROT_}* protection flags set by @code{mprotect} or @code{pkey_mprotect}. @end itemize -New threads and subprocesses inherit the access rights of the current +New threads and subprocesses inherit the access restrictions of the current thread. If a protection key is allocated subsequently, existing threads (except the current) will use an unspecified system default for the -access rights associated with newly allocated keys. +access restrictions associated with newly allocated keys. -Upon entering a signal handler, the system resets the access rights of +Upon entering a signal handler, the system resets the access restrictions of the current thread so that pages with the default key can be accessed, -but the access rights for other protection keys are unspecified. +but the access restrictions for other protection keys are unspecified. Applications are expected to allocate a key once using @code{pkey_alloc}, and apply the key to memory regions which need @@ -3139,7 +3139,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. */ @@ -3151,24 +3151,24 @@ it again: In this example, a negative key value indicates that no key had been allocated, which means that the system lacks support for memory -protection keys and it is not necessary to change the the access rights +protection keys and it is not necessary to change the the access restrictions of the current thread (because it always has access). Compared to using @code{mprotect} to change the page protection flags, this approach has two advantages: It is thread-safe in the sense that -the access rights are only changed for the current thread, so another -thread which changes its own access rights concurrently to gain access -to the mapping will not suddenly see its access rights revoked. And +the access restrictions are only changed for the current thread, so another +thread which changes its own access restrictions concurrently to gain access +to the mapping will not suddenly see its access restrictions updated. And @code{pkey_set} typically does not involve a call into the kernel and a context switch, so it is more efficient. -@deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{restrictions}) +@deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{access_restrictions}) @standards{Linux, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} Allocate a new protection key. The @var{flags} argument is reserved and -must be zero. The @var{restrictions} argument specifies access rights +must be zero. The @var{access_restrictions} argument specifies access restrictions which are applied to the current thread (as if with @code{pkey_set} -below). Access rights of other threads are not changed. +below). Access restrictions of other threads are not changed. The function returns the new protection key, a non-negative number, or @math{-1} on error. @@ -3183,7 +3183,7 @@ The system does not implement memory protection keys. @item EINVAL The @var{flags} argument is not zero. -The @var{restrictions} argument is invalid. +The @var{access_restrictions} argument is invalid. The system does not implement memory protection keys or runs in a mode in which memory protection keys are disabled. @@ -3203,7 +3203,7 @@ in which memory protection keys are disabled. Deallocate the protection key, so that it can be reused by @code{pkey_alloc}. -Calling this function does not change the access rights of the freed +Calling this function does not change the access restrictions of the freed protection key. The calling thread and other threads may retain access to it, even if it is subsequently allocated again. For this reason, it is not recommended to call the @code{pkey_free} function. @@ -3251,16 +3251,22 @@ not @math{-1}. @end table @end deftypefun -@deftypefun int pkey_set (int @var{key}, unsigned int @var{rights}) +@deftypefun int pkey_set (int @var{key}, unsigned int @var{access_restrictions}) @standards{Linux, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -Change the access rights of the current thread for memory pages with the -protection key @var{key} to @var{rights}. If @var{rights} is zero, no -additional access restrictions on top of the page protection flags are -applied. Otherwise, @var{rights} is a combination of the following -flags: +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 @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 +@standards{Linux, sys/mman.h} +Subsequent attempts to read from memory with the specified protection +key will fault. At present only AArch64 platforms with enabled Stage 1 +permission overlays feature support this type of restriction. + @item PKEY_DISABLE_WRITE @standards{Linux, sys/mman.h} Subsequent attempts to write to memory with the specified protection @@ -3269,7 +3275,15 @@ key will fault. @item PKEY_DISABLE_ACCESS @standards{Linux, sys/mman.h} Subsequent attempts to write to or read from memory with the specified -protection key will fault. +protection key will fault. On AArch64 platforms with enabled Stage 1 +permission overlays feature this restriction value has the same effect +as combination of @code{PKEY_DISABLE_READ} and @code{PKEY_DISABLE_WRITE}. + +@item PKEY_DISABLE_EXECUTE +@standards{Linux, sys/mman.h} +Subsequent attempts to execute from memory with the specified protection +key will fault. At present only AArch64 platforms with enabled Stage 1 +permission overlays feature support this type of restriction. @end vtable Operations not specified as flags are not restricted. In particular, @@ -3290,18 +3304,22 @@ function: @table @code @item EINVAL -The system does not support the access rights restrictions expressed in -the @var{rights} argument. +The system does not support the access restrictions expressed in +the @var{access_restrictions} argument. @end table @end deftypefun @deftypefun int pkey_get (int @var{key}) @standards{Linux, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -Return the access rights of the current thread for memory pages with -protection key @var{key}. The return value is zero or a combination of +Return the access restrictions of the current thread for memory pages +with protection key @var{key}. The return value is zero or a combination of the @code{PKEY_DISABLE_}* flags; see the @code{pkey_set} function. +The returned value should be checked for presence or absence of specific flags +using bitwise operations. Comparing the returned value with any of the flags +or their combination using equals will almost certainly fail. + Calling the @code{pkey_get} function with a protection key which was not allocated by @code{pkey_alloc} results in undefined behavior. This means that calling this function on systems which do not support memory diff --git a/manual/message.texi b/manual/message.texi index ef68693..71b56e6 100644 --- a/manual/message.texi +++ b/manual/message.texi @@ -18,11 +18,11 @@ in separate files which are loaded at runtime depending on the language selection of the user. @Theglibc{} provides two different sets of functions to support -message translation. The problem is that neither of the interfaces is -officially defined by the POSIX standard. The @code{catgets} family of -functions is defined in the X/Open standard but this is derived from -industry decisions and therefore not necessarily based on reasonable -decisions. +message translation. The @code{catgets} family of functions were +previously the only family defined in the X/Open standard but they were +derived from industry decisions and therefore not necessarily based on +reasonable decisions. However, the preferable @code{gettext} family of +functions was standardized in POSIX-1.2024. As mentioned above, the message catalog handling provides easy extendability by using external data files which contain the message @@ -830,7 +830,7 @@ not part of the C library they can be found in a separate library named @file{libintl.a} (or accordingly different for shared libraries). @deftypefun {char *} gettext (const char *@var{msgid}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcgettext. The @code{gettext} function searches the currently selected message @@ -878,7 +878,7 @@ currently selected default message catalog it must specify all ambiguous information. @deftypefun {char *} dgettext (const char *@var{domainname}, const char *@var{msgid}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcgettext. The @code{dgettext} function acts just like the @code{gettext} @@ -893,7 +893,7 @@ anachronism. The returned string must never be modified. @end deftypefun @deftypefun {char *} dcgettext (const char *@var{domainname}, const char *@var{msgid}, int @var{category}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c dcgettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem @c dcigettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem @@ -1112,7 +1112,7 @@ exactly one domain is active. This is controlled with the following function. @deftypefun {char *} textdomain (const char *@var{domainname}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c textdomain @asulock @ascuheap @aculock @acsmem @c libc_rwlock_wrlock @asulock @aculock @@ -1149,7 +1149,7 @@ really never should be used. @end deftypefun @deftypefun {char *} bindtextdomain (const char *@var{domainname}, const char *@var{dirname}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c bindtextdomain @ascuheap @acsmem @c set_binding_values @ascuheap @acsmem @@ -1271,7 +1271,7 @@ to be written in English, this solution nevertheless fulfills its purpose. @deftypefun {char *} ngettext (const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcngettext. The @code{ngettext} function is similar to the @code{gettext} function @@ -1295,7 +1295,7 @@ Please note that the numeric value @var{n} has to be passed to the @end deftypefun @deftypefun {char *} dngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcngettext. The @code{dngettext} is similar to the @code{dgettext} function in the @@ -1305,7 +1305,7 @@ parameters are handled in the same way @code{ngettext} handles them. @end deftypefun @deftypefun {char *} dcngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}, int @var{category}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcigettext. The @code{dcngettext} is similar to the @code{dcgettext} function in the @@ -1562,7 +1562,7 @@ independently of the current output character set. It is therefore recommended that all @var{msgid}s be US-ASCII strings. @deftypefun {char *} bind_textdomain_codeset (const char *@var{domainname}, const char *@var{codeset}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c bind_textdomain_codeset @ascuheap @acsmem @c set_binding_values dup @ascuheap @acsmem diff --git a/manual/pattern.texi b/manual/pattern.texi index 250fa1e..f2e8353 100644 --- a/manual/pattern.texi +++ b/manual/pattern.texi @@ -119,9 +119,12 @@ If this flag is set, either @samp{foo*} or @samp{foobar} as a pattern would match the string @samp{foobar/frobozz}. @item FNM_CASEFOLD -@standards{GNU, fnmatch.h} +@standards{POSIX.1-2024, fnmatch.h} Ignore case in comparing @var{string} to @var{pattern}. +This macro was originally a GNU extension, but was added in +POSIX.1-2024. + @item FNM_EXTMATCH @standards{GNU, fnmatch.h} @cindex Korn Shell diff --git a/manual/process.texi b/manual/process.texi index 8254e5e..609c78a 100644 --- a/manual/process.texi +++ b/manual/process.texi @@ -239,6 +239,24 @@ especially regarding reuse of the IDs of threads which have exited. This function is specific to Linux. @end deftypefun +@deftypefun pid_t pthread_gettid_np (pthread_t @var{thread}) +@standards{Linux, pthread.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function returns the same value that @code{gettid} would return if +executed on the running thread @var{thread}. + +If @var{thread} is no longer running but it is joinable, it is +unspecified whether this function returns @minus{}1, or if it returns +the thread ID of the thread while it was running. If @var{thread} is +not running and is not joinable, the behavior is undefined. + +@strong{Portability Note:} Linux thread IDs can be reused rather quickly, +so this function differs from the @code{pthread_getunique_np} function +found on other systems. + +This function is specific to Linux. +@end deftypefun + @node Creating a Process @section Creating a Process @@ -320,7 +338,7 @@ signals and signal actions from the parent process.) @end itemize @deftypefun pid_t _Fork (void) -@standards{GNU, unistd.h} +@standards{POSIX.1-2024, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{_Fork} function is similar to @code{fork}, but it does not invoke any callbacks registered with @code{pthread_atfork}, nor does it reset @@ -329,8 +347,9 @@ new subprocess, only async-signal-safe functions may be called, such as @code{dup2} or @code{execve}. The @code{_Fork} function is an async-signal-safe replacement of @code{fork}. -It is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun pid_t vfork (void) @@ -817,10 +836,13 @@ signal number of the signal that terminated the child process. @end deftypefn @deftypefn Macro int WCOREDUMP (int @var{status}) -@standards{BSD, sys/wait.h} +@standards{POSIX.1-2024, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if the child process terminated and produced a core dump. + +This macro was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefn @deftypefn Macro int WIFSTOPPED (int @var{status}) diff --git a/manual/resource.texi b/manual/resource.texi index 25966bc..1fd0310 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -478,6 +478,7 @@ POSIX syntax had in mind. * Absolute Priority:: The first tier of priority. Posix * Realtime Scheduling:: Scheduling among the process nobility * Basic Scheduling Functions:: Get/set scheduling policy, priority +* Extensible Scheduling:: Parameterized scheduling policies. * Traditional Scheduling:: Scheduling among the vulgar masses * CPU Affinity:: Limiting execution to certain CPUs @end menu @@ -928,18 +929,31 @@ function, so there are no specific @code{errno} values. @c Direct syscall on Linux; alias to swtch on HURD. This function voluntarily gives up the task's claim on the CPU. - -Technically, @code{sched_yield} causes the calling task to be made -immediately ready to run (as opposed to running, which is what it was -before). This means that if it has absolute priority higher than 0, it -gets pushed onto the tail of the queue of tasks that share its +Depending on the scheduling policy in effect and the tasks ready to run +on the system, another task may be scheduled to run instead. + +A call to @code{sched_yield} does not guarantee that a different task +from the calling task is scheduled as a result; it depends on the +scheduling policy used on the target system. It is possible that the +call may not result in any visible effect, i.e., the same task gets +scheduled again. + +For example on Linux systems, when a simple priority-based FIFO +scheduling policy (@code{SCHED_FIFO}) is in effect, the calling task is +made immediately ready to run (as opposed to running, which is what it +was before). This means that if it has absolute priority higher than 0, +it gets pushed onto the tail of the queue of tasks that share its absolute priority and are ready to run, and it will run again when its turn next arrives. If its absolute priority is 0, it is more complicated, but still has the effect of yielding the CPU to other -tasks. +tasks. If there are no other tasks that share the calling task's +absolute priority, it will be scheduled again as if @code{sched_yield} +was never called. -If there are no other tasks that share the calling task's absolute -priority, this function doesn't have any effect. +Another example could be a time slice based preemptive round-robin +policy, such as the @code{SCHED_RR} policy on Linux. It is possible +with this policy that the calling task is scheduled again because it +still has time left in its slice. To the extent that the containing program is oblivious to what other processes in the system are doing and how fast it executes, this @@ -952,6 +966,119 @@ function, so there are no specific @code{errno} values. @end deftypefun +@node Extensible Scheduling +@subsection Extensible Scheduling +@cindex scheduling, extensible + +The type @code{struct sched_attr} and the functions @code{sched_setattr} +and @code{sched_getattr} are used to implement scheduling policies with +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 +the manual pages @manpageurl{sched,7} and @manpageurl{sched_setattr,2}. + +@strong{Note:} Calling the @code{sched_setattr} function is incompatible +with support for @code{PTHREAD_PRIO_PROTECT} mutexes. + +@deftp {Data Type} {struct sched_attr} +@standards{Linux, sched.h} +The @code{sched_attr} structure describes a parameterized scheduling policy. + +@strong{Portability note:} In the future, additional fields can be added +to @code{struct sched_attr} at the end, so that the size of this data +type changes. Do not use it in places where this matters, such as +structure fields in installed header files, where such a change could +impact the application binary interface (ABI). + +The following generic fields are available. + +@table @code +@item size +The actually used size of the data structure. See the description of +the functions @code{sched_setattr} and @code{sched_getattr} below how this +field is used to support extension of @code{struct sched_attr} with +more fields. + +@item sched_policy +The scheduling policy. This field determines which fields in the +structure are used, and how the @code{sched_flags} field is interpreted. + +@item sched_flags +Scheduling flags associated with the scheduling policy. +@end table + +In addition to the generic fields, policy-specific fields are available. +For additional information, consult the manual page +@manpageurl{sched_setattr,2}. +@end deftp + +@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 +@code{*@var{attr}} to the thread @var{tid} (the value zero denotes the +current thread). + +It is recommended to initialize unused fields to zero, either using +@code{memset}, or using a structure initializer. The +@code{@var{attr->size}} field should be set to @code{sizeof (struct +sched_attr)}, to inform the kernel of the structure version in use. + +The @var{flags} argument must be zero. Other values may become +available in the future. + +On failure, @code{sched_setattr} returns @math{-1} and sets +@code{errno}. The following errors are related the way +extensibility is handled. +@table @code +@item E2BIG +A field in @code{*@var{attr}} has a non-zero value, but is unknown to +the kernel. The application could try to apply a modified policy, where +more fields are zero. + +@item EINVAL +The policy in @code{@var{attr}->sched_policy} is unknown to the kernel, +or flags are set in @code{@var{attr}->sched_flags} that the kernel does +not know how to interpret. The application could try with fewer flags +set, or a different scheduling policy. + +This error also occurs if @var{attr} is @code{NULL} or @var{flags} is +not zero. + +@item EPERM +The current thread is not sufficiently privileged to assign the policy, +either because access to the policy is restricted in general, or because +the current thread does not have the rights to change the scheduling +policy of the thread @var{tid}. +@end table + +Other error codes depend on the scheduling policy. +@end deftypefun + +@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} +(zero denotes the current thread) and store it in @code{*@var{attr}}, +which must have space for at least @var{size} bytes. + +The @var{flags} argument must be zero. Other values may become +available in the future. + +Upon success, @code{@var{attr}->size} contains the size of the structure +version used by the kernel. Fields with offsets greater or equal to +@code{@var{attr}->size} may not be overwritten by the kernel. To obtain +predictable values for unknown fields, use @code{memset} to set all +@var{size} bytes to zero prior to calling @code{sched_getattr}. + +On failure, @code{sched_getattr} returns @math{-1} and sets @code{errno}. +If @code{errno} is @code{E2BIG}, this means that the buffer is not large +large enough, and the application could retry with a larger buffer. +@end deftypefun + @node Traditional Scheduling @subsection Traditional Scheduling @cindex scheduling, traditional @@ -1235,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} @@ -1297,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{}} @@ -1313,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. @@ -1398,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/signal.texi b/manual/signal.texi index 5c2ba7d..7e21a93 100644 --- a/manual/signal.texi +++ b/manual/signal.texi @@ -427,9 +427,18 @@ failure to properly emulate them. @deftypevr Macro int SIGSYS @standards{Unix, signal.h} -Bad system call; that is to say, the instruction to trap to the -operating system was executed, but the code number for the system call -to perform was invalid. +System call event. This signal may be generated by a valid system +call which requested an invalid sub-function, and also by the SECCOMP +filter when it filters or traps a system call. + +If the system call itself is invalid or unsupported by the kernel, the +call will not raise this signal, but will return @code{ENOSYS}. +@end deftypevr + +@deftypevr Macro int SIGSTKFLT +Coprocessor stack fault. Obsolete, no longer generated. This signal +may be used by applications in much the way @code{SIGUSR1} and +@code{SIGUSR2} are. @end deftypevr @node Termination Signals @@ -752,12 +761,11 @@ that isn't connected. @xref{Sending Data}. @deftypevr Macro int SIGLOST @standards{GNU, signal.h} @cindex lost resource signal -Resource lost. This signal is generated when you have an advisory lock -on an NFS file, and the NFS server reboots and forgets about your lock. - -On @gnuhurdsystems{}, @code{SIGLOST} is generated when any server program -dies unexpectedly. It is usually fine to ignore the signal; whatever -call was made to the server that died just returns an error. +Resource lost. On @gnuhurdsystems{}, @code{SIGLOST} is generated when +any server program dies unexpectedly. It is usually fine to ignore +the signal; whatever call was made to the server that died just +returns an error. This signal's original purpose of signalling a lost +NFS lock is obsolete. @end deftypevr @deftypevr Macro int SIGXCPU @@ -795,7 +803,7 @@ The default action is to terminate the process. @end deftypevr @deftypevr Macro int SIGWINCH -@standards{BSD, signal.h} +@standards{POSIX.1-2024, signal.h} Window size change. This is generated on some systems (including GNU) when the terminal driver's record of the number of rows and columns on the screen is changed. The default action is to ignore it. @@ -803,6 +811,9 @@ the screen is changed. The default action is to ignore it. If a program does full-screen display, it should handle @code{SIGWINCH}. When the signal arrives, it should fetch the new screen size and reformat its display accordingly. + +This macro was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypevr @deftypevr Macro int SIGINFO @@ -817,6 +828,17 @@ to print some status information about the system and what the process is doing. Otherwise the default is to do nothing. @end deftypevr +@deftypevr Macro int SIGPWR +@cindex power event signal +Power lost or restored. On s390x Linux systems, this signal is +generated when a machine check warning is issued, and is sent to the +process designated to receive ctrl-alt-del notifications. Otherwise, +it is up to userspace applications to generate this signal and manage +notifications as to the type of power event that happened. + +The default action is to terminate the process. +@end deftypevr + @node Signal Messages @subsection Signal Messages @cindex signal messages @@ -1141,6 +1163,15 @@ This is used in the same way as the @var{action} argument to the @code{signal} function. The value can be @code{SIG_DFL}, @code{SIG_IGN}, or a function pointer. @xref{Basic Signal Handling}. +@item void (*sa_sigaction) (int @var{signum}, siginfo_t *@var{info}, void *@var{ucontext}) +This is an alternate to @code{sa_handler} that is used when the +@code{sa_flags} includes the @code{flag SA_SIGINFO}. Note that this +and @code{sa_handler} overlap; only ever set one at a time. + +The contents of the @var{info} and @var{ucontext} structures are +kernel and architecture dependent. Please see +@manpageurl{sigaction,2} for details. + @item sigset_t sa_mask This specifies a set of signals to be blocked while the handler runs. Blocking is explained in @ref{Blocking for Handler}. Note that the @@ -1324,6 +1355,24 @@ delivered for both terminated children and stopped children. Setting this flag for a signal other than @code{SIGCHLD} has no effect. @end deftypevr +@deftypevr Macro int SA_NOCLDWAIT +This flag is meaningful only for the @code{SIGCHLD} signal. When the +flag is set, the terminated child will not wait for the parent to reap +it, or become a zombie if not reaped. The child will instead be +reaped by the kernel immediately on termination, similar to setting +SIGCHLD to SIG_IGN. + +Setting this flag for a signal other than @code{SIGCHLD} has no effect. +@end deftypevr + +@deftypevr Macro int SA_NODEFER +Normally a signal is added to the signal mask while running its own +handler; this negates that, so that the same signal can be received +while it's handler is running. Note that if the signal is included in +@code{sa_mask}, it is masked regardless of this flag. Only useful when +assigning a function as a signal handler. +@end deftypevr + @deftypevr Macro int SA_ONSTACK @standards{BSD, signal.h} If this flag is set for a particular signal number, the system uses the @@ -1332,6 +1381,12 @@ If a signal with this flag arrives and you have not set a signal stack, the normal user stack is used instead, as if the flag had not been set. @end deftypevr +@deftypevr Macro int SA_RESETHAND +Resets the handler for a signal to SIG_DFL, at the moment specified +handler function begins. I.e. the handler is called once, then the +action resets. +@end deftypevr + @deftypevr Macro int SA_RESTART @standards{BSD, signal.h} This flag controls what happens when a signal is delivered during @@ -1347,6 +1402,12 @@ clear, returning from a handler makes the function fail. @xref{Interrupted Primitives}. @end deftypevr +@deftypevr Macro int SA_SIGINFO +Indicates that the @code{sa_sigaction} three-argument form of the +handler should be used in setting up a handler instead of the +one-argument @code{sa_handler} form. +@end deftypevr + @node Initial Signal Actions @subsection Initial Signal Actions @cindex initial signal actions diff --git a/manual/socket.texi b/manual/socket.texi index 8708cbb..d804c7a 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 diff --git a/manual/startup.texi b/manual/startup.texi index 747beed..6f29ddd 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -337,7 +337,7 @@ pointer. @end deftypefun @deftypefun {char *} secure_getenv (const char *@var{name}) -@standards{GNU, stdlib.h} +@standards{POSIX.1-2024, stdlib.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}} @c Calls getenv unless secure mode is enabled. This function is similar to @code{getenv}, but it returns a null @@ -346,7 +346,8 @@ program file has SUID or SGID bits set. General-purpose libraries should always prefer this function over @code{getenv} to avoid vulnerabilities if the library is referenced from a SUID/SGID program. -This function is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun @@ -664,8 +665,12 @@ basis there may be information that is not available any other way. This function is used to inquire about the entries in the auxiliary vector. The @var{type} argument should be one of the @samp{AT_} symbols 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}. +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 +defined in @file{elf.h} and the file name lookup flags in +@file{fcntl.h}. @xref{Descriptor-Relative Access}. @end deftypefun For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire @@ -1010,10 +1015,7 @@ for this function is in @file{stdlib.h}. @deftypefun void abort (void) @standards{ISO, stdlib.h} -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -@c The implementation takes a recursive lock and attempts to support -@c calls from signal handlers, but if we're in the middle of flushing or -@c using streams, we may encounter them in inconsistent states. +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{abort} function causes abnormal program termination. This does not execute cleanup functions registered with @code{atexit} or @code{on_exit}. @@ -1021,6 +1023,10 @@ does not execute cleanup functions registered with @code{atexit} or This function actually terminates the process by raising a @code{SIGABRT} signal, and your program can include a handler to intercept this signal; see @ref{Signal Handling}. + +If either the signal handler does not terminate the process, or if the +signal is blocked, @code{abort} will reset the signal disposition to the +default @code{SIG_DFL} action and raise the signal again. @end deftypefun @node Termination Internals diff --git a/manual/stdio.texi b/manual/stdio.texi index f9529a0..29ed720 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -330,6 +330,14 @@ this ability, so using @code{freopen} is more portable. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine this function is in fact @code{freopen64} since the LFS interface replaces transparently the old interface. + +@Theglibc{} only supports use of @code{freopen} on streams opened with +@code{fopen} or @code{fopen64} and on the original values of the +standard streams @code{stdin}, @code{stdout}, and @code{stderr}; such +a stream may be reopened multiple times with @code{freopen}. If it is +called on another kind of stream (opened with functions such as +@code{popen}, @code{fmemopen}, @code{open_memstream}, and +@code{fopencookie}), @code{freopen} fails and returns a null pointer. @end deftypefun @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) @@ -904,20 +912,16 @@ This function is a GNU extension. @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} This is just like @code{fputc}, except that it may be implemented as -a macro, making it faster. One consequence is that it may evaluate the -@var{stream} argument more than once, which is an exception to the -general rule for macros. Therefore, @var{stream} should never be an -expression with side-effects. +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream}) @standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} This is just like @code{fputwc}, except that it may be implemented as -a macro, making it faster. One consequence is that it may evaluate the -@var{stream} argument more than once, which is an exception to the -general rule for macros. Therefore, @var{stream} should never be an -expression with side-effects. +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream}) @@ -925,6 +929,9 @@ expression with side-effects. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putc_unlocked} function is equivalent to the @code{putc} function except that it does not implicitly lock the stream. +Like @code{putc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) @@ -1110,20 +1117,17 @@ This function is a GNU extension. @deftypefun int getc (FILE *@var{stream}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This is just like @code{fgetc}, except that it is permissible (and -typical) for it to be implemented as a macro that evaluates the -@var{stream} argument more than once. @code{getc} is often highly -optimized, so it is usually the best function to use to read a single -character. +This is just like @code{fgetc}, except that it may be implemented as +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun wint_t getwc (FILE *@var{stream}) @standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This is just like @code{fgetwc}, except that it is permissible for it to -be implemented as a macro that evaluates the @var{stream} argument more -than once. @code{getwc} can be highly optimized, so it is usually the -best function to use to read a single wide character. +This is just like @code{fgetwc}, except that it may be implemented as +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun int getc_unlocked (FILE *@var{stream}) @@ -1131,6 +1135,9 @@ best function to use to read a single wide character. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getc_unlocked} function is equivalent to the @code{getc} function except that it does not implicitly lock the stream. +Like @code{getc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) @@ -1224,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, @@ -1267,15 +1275,15 @@ 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}. @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 @@ -1287,6 +1295,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: @@ -1474,11 +1485,9 @@ program; usually @code{ungetc} is used only to unread a character that was just read from the same stream. @Theglibc{} supports this even on files opened in binary mode, but other systems might not. -@Theglibc{} only supports one character of pushback---in other -words, it does not work to call @code{ungetc} twice without doing input -in between. Other systems might let you push back multiple characters; -then reading from the stream retrieves the characters in the reverse -order that they were pushed. +@Theglibc{} supports pushing back multiple characters; subsequently +reading from the stream retrieves the characters in the reverse order +that they were pushed. Pushing back characters doesn't alter the file; only the internal buffering for the stream is affected. If a file positioning function @@ -1572,6 +1581,9 @@ The @code{fread_unlocked} function is equivalent to the @code{fread} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) @@ -1590,6 +1602,9 @@ The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @node Formatted Output @@ -2363,6 +2378,29 @@ the easiest way to make sure you have all the right prototypes is to just include @file{stdio.h}. @pindex stdio.h +The @code{printf} family shares the error codes listed below. +Individual functions may report additional @code{errno} values if they +fail. + +@table @code +@item EOVERFLOW +The number of written bytes would have exceeded @code{INT_MAX}, and thus +could not be represented in the return type @code{int}. + +@item ENOMEM +The function could not allocate memory during processing. Long argument +lists and certain floating point conversions may require memory +allocation, as does initialization of an output stream upon first use. + +@item EILSEQ +POSIX specifies this error code should be used if a wide character is +encountered that does not have a matching valid character. @Theglibc{} +always performs transliteration, using a replacement character if +necessary, so this error condition cannot occur on output. However, +@theglibc{} uses @code{EILSEQ} to indicate that an input character +sequence (wide or multi-byte) could not be converted successfully. +@end table + @deftypefun int printf (const char *@var{template}, @dots{}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} @@ -2509,6 +2547,26 @@ store the result in which case @code{-1} is returned. This was changed in order to comply with the @w{ISO C99} standard. @end deftypefun +@deftypefun int dprintf (int @var{fd}, @var{template}, ...) +@standards{POSIX, stdio.h} +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +This function formats its arguments according to @var{template} and +writes the result to the file descriptor @var{fd}, using the +@code{write} function. It returns the number of bytes written, or a +negative value if there was an error. In the error case, @code{errno} +is set appropriately. The possible @code{errno} values depend on the +type of the file descriptor @var{fd}, in addition to the general +@code{printf} error codes. + +The number of calls to @code{write} is unspecified, and some @code{write} +calls may have happened even if @code{dprintf} returns with an error. + +@strong{Portability Note:} POSIX does not require that this function is +async-signal-safe, and @theglibc{} implementation is not. However, some +other systems offer this function as an async-signal-safe alternative to +@code{fprintf}. @xref{POSIX Safety Concepts}. +@end deftypefun + @node Dynamic Output @subsection Dynamically Allocating Formatted Output @@ -2524,7 +2582,14 @@ Allocation}) to hold the output, instead of putting the output in a buffer you allocate in advance. The @var{ptr} argument should be the address of a @code{char *} object, and a successful call to @code{asprintf} stores a pointer to the newly allocated string at that -location. +location. Current and future versions of @theglibc{} write a null +pointer to @samp{*@var{ptr}} upon failure. To achieve similar +behavior with previous versions, initialize @samp{*@var{ptr}} to a +null pointer before calling @code{asprintf}. (Specifications for +@code{asprintf} only require a valid pointer value in +@samp{*@var{ptr}} if @code{asprintf} succeeds, but no implementations +are known which overwrite a null pointer with a pointer that cannot be +freed on failure.) The return value is the number of characters allocated for the buffer, or less than zero if an error occurred. Usually this means that the buffer @@ -2722,6 +2787,13 @@ The @code{obstack_vprintf} function is the equivalent of as for @code{vprintf}. @end deftypefun +@deftypefun int vdprintf (int @var{fd}, const char *@var{template}, va_list @var{ap}) +@standards{POSIX, stdio.h} +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +The @code{vdprintf} is the equivalent of @code{dprintf}, but processes +an argument list. +@end deftypefun + Here's an example showing how you might use @code{vfprintf}. This is a function that prints error messages to the stream @code{stderr}, along with a prefix indicating the name of the program @@ -4119,6 +4191,15 @@ check indicators that are part of the internal state of the stream object, indicators set if the appropriate condition was detected by a previous I/O operation on that stream. +The end of file and error conditions are mutually exclusive. For a +narrow oriented stream, end of file is not considered an error. For +wide oriented streams, reaching the end of the underlying file can +result an error if the underlying file ends with an incomplete multibyte +sequence. This is reported as an error by @code{ferror}, and not as an +end of file by @code{feof}. End of file on wide oriented streams that +does not fall into the middle of a multibyte sequence is reported via +@code{feof}. + @deftypevr Macro int EOF @standards{ISO, stdio.h} This macro is an integer value that is returned by a number of narrow @@ -4270,6 +4351,18 @@ terminating newline character). @cindex lines (in a text file) @item +If the system does not use POSIX-style in-band signalling to indicate +line termination, it can be impossibe to write anything to a text stream +without adding a line terminator. As a result, flushing a text stream +(by calling @code{fflush}, for example) may produce a logical line +terminator even if no @code{'\n'} character was written by the program. + +@item +Text files may contain lines that embed @code{'\n'} characters that are +not treated as line terminators by the system. C programs cannot read +such text files reliably using the @file{stdio.h} facilities. + +@item On some systems, text files can contain only printing characters, horizontal tab characters, and newlines, and so text streams may not support other characters. However, binary streams can handle any @@ -4761,12 +4854,6 @@ currently opened. This function is declared in the @file{stdio_ext.h} header. @end deftypefun -@strong{Compatibility Note:} Some brain-damaged operating systems have -been known to be so thoroughly fixated on line-oriented input and output -that flushing a line buffered stream causes a newline to be written! -Fortunately, this ``feature'' seems to be becoming less common. You do -not need to worry about this with @theglibc{}. - In some situations it might be useful to not flush the output pending for a stream but instead simply forget it. If transmission is costly and the output is not needed anymore this is valid reasoning. In this diff --git a/manual/string.texi b/manual/string.texi index 0b667bd..feba0b7 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -1081,7 +1081,7 @@ issues. @xref{Concatenating Strings}. @end deftypefun @deftypefun size_t strlcpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX-1.2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the string @var{from} to the destination array @var{to}, limiting the result's size (including the null terminator) @@ -1114,21 +1114,23 @@ processing strings. Also, this function has a performance issue, as its time cost is proportional to the length of @var{from} even when @var{size} is small. -This function is derived from OpenBSD 2.4. +This function was originally derived from OpenBSD 2.4, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t wcslcpy (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is a variant of @code{strlcpy} for wide strings. The @var{size} argument counts the length of the destination buffer in wide characters (and not bytes). -This function is derived from BSD. +This function was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t strlcat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX-1.2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function appends the string @var{from} to the string @var{to}, limiting the result's total size (including the null @@ -1156,17 +1158,19 @@ As noted below, this function is generally a poor choice for processing strings. Also, this function has significant performance issues. @xref{Concatenating Strings}. -This function is derived from OpenBSD 2.4. +This function was originally derived from OpenBSD 2.4, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t wcslcat (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is a variant of @code{strlcat} for wide strings. The @var{size} argument counts the length of the destination buffer in wide characters (and not bytes). -This function is derived from BSD. +This function was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefun Because these functions can abruptly truncate strings or wide strings, @@ -2008,14 +2012,15 @@ strcasestr ("hello, World", "wo") @deftypefun {void *} memmem (const void *@var{haystack}, size_t @var{haystack-len},@*const void *@var{needle}, size_t @var{needle-len}) -@standards{GNU, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{strstr}, but @var{needle} and @var{haystack} are byte arrays rather than strings. @var{needle-len} is the length of @var{needle} and @var{haystack-len} is the length of @var{haystack}. -This function is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t strspn (const char *@var{string}, const char *@var{skipset}) diff --git a/manual/summary.pl b/manual/summary.pl index 864046a..36feb56 100755 --- a/manual/summary.pl +++ b/manual/summary.pl @@ -1,7 +1,7 @@ #!/usr/bin/perl # Generate the Summary of Library Facilities (summary.texi). -# Copyright (C) 2017-2024 Free Software Foundation, Inc. +# Copyright (C) 2017-2025 Free Software Foundation, Inc. # This file is part of the GNU C Library. # The GNU C Library is free software; you can redistribute it and/or diff --git a/manual/syslog.texi b/manual/syslog.texi index 02f84d6..9875793 100644 --- a/manual/syslog.texi +++ b/manual/syslog.texi @@ -498,10 +498,7 @@ The symbols referred to in this section are declared in the file @deftypefun int setlogmask (int @var{mask}) @standards{BSD, syslog.h} -@safety{@prelim{}@mtunsafe{@mtasurace{:LogMask}}@asunsafe{}@acsafe{}} -@c Read and modify are not guarded by syslog_lock, so concurrent changes -@c or even uses are undefined. This should use an atomic swap instead, -@c at least for modifications. +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @code{setlogmask} sets a mask (the ``logmask'') that determines which future @code{syslog} calls shall be ignored. If a program has not diff --git a/manual/terminal.texi b/manual/terminal.texi index bdaee56..de9554d 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -771,11 +771,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{tcsettattr} works.) This bit is never set in the structure filled in by @code{tcgetattr}. @end deftypevr @@ -1047,14 +1047,15 @@ 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}. +@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 @strong{Portability note:} In @theglibc{}, the functions above accept speeds measured in bits per second as input, and return speed @@ -1106,12 +1107,24 @@ the only speeds that typical serial lines can support. @comment POSIX.1 @vindex B4800 @comment termios.h +@comment GNU +@vindex B7200 +@comment termios.h @comment POSIX.1 @vindex B9600 @comment termios.h +@comment GNU +@vindex B14400 +@comment termios.h @comment POSIX.1 @vindex B19200 @comment termios.h +@comment GNU +@vindex B28800 +@comment termios.h +@comment GNU +@vindex B33600 +@comment termios.h @comment POSIX.1 @vindex B38400 @comment termios.h @@ -1119,18 +1132,72 @@ the only speeds that typical serial lines can support. @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 +B0 B50 B75 B110 B134 B150 B200 B300 B600 B1200 +B1800 B2400 B4800 B7200 B9600 B14400 B19200 +B28800 B33600 B38400 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 +1206,69 @@ 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. +@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 baud rate stored in the structure +@code{*@var{termios-p}}. +@end deftypefun + +@deftypefun int cfsetobaud (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 output +baud rate. The normal return value is @math{0}; a value of @math{-1} +indicates an error. If @var{baud} is not a valid baud rate, @code{cfsetobaud} +returns @math{-1}. +@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 +baud rate. The normal return value is @math{0}; a value of @math{-1} +indicates an error. If @var{baud} is not a valid baud rate, @code{cfsetobaud} +returns @math{-1}. +@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 ought to 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 baud rates. The normal return value is @math{0}; a value +of @math{-1} indicates an error. If @var{baud} is not a valid baud rate, +@code{cfsetbaud} returns @math{-1}. +@end deftypefun + +@deftp {Data Type} baud_t +@standards{GNU} +The @code{baud_t} type is a numeric data type used to represent line +baud rates. It will always represent the actual numeric value +representing the baud rate, 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 +may not even necessarily be an integer type. + +@end deftp + +The functions @code{cfsetospeed}, @code{cfsetispeed}, @code{cfsetobaud} +and @code{cfsetibaud} 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, either @code{tcsetattr} +returns @math{-1}, or the value is adjusted to the closest supported +value, depending on the policy of the kernel driver. + @node Special Characters @subsection Special Characters @@ -2107,7 +2237,7 @@ might be overwritten by subsequent calls to @code{ptsname}. @end deftypefun @deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) -@standards{GNU, stdlib.h} +@standards{POSIX.1-2024, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} @c ptsname_r @ascuheap/bsd @acsmem @acsfd @c /hurd @@ -2143,7 +2273,8 @@ The @code{ptsname_r} function is similar to the @code{ptsname} function except that it places its result into the user-specified buffer starting at @var{buf} with length @var{len}. -This function is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun Typical usage of these functions is illustrated by the following example: diff --git a/manual/threads.texi b/manual/threads.texi index 25e99c9..eeefa9b 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -552,12 +552,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 @@ -592,7 +679,7 @@ destructor for the thread-specific data is not called during destruction, nor is it called during thread exit. @end deftypefun -@deftypefun void *pthread_getspecific (pthread_key_t @var{key}) +@deftypefun {void *} pthread_getspecific (pthread_key_t @var{key}) @standards{POSIX, pthread.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c pthread_getspecific ok @@ -615,6 +702,422 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread. @end deftypefun +@node Waiting with Explicit Clocks +@subsection Functions for Waiting According to a Specific Clock + +@Theglibc{} provides several waiting functions that expect an explicit +@code{clockid_t} argument. These functions were all adopted by +POSIX.1-2024. + +@comment pthread.h +@deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@standards{POSIX-1.2024, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c If exactly the same function with arguments is called from a signal +@c handler that interrupts between the mutex unlock and sleep then it +@c will unlock the mutex twice resulting in undefined behaviour. Keep +@c in mind that the unlock and sleep are only atomic with respect to other +@c threads (really a happens-after relationship for pthread_cond_broadcast +@c and pthread_cond_signal). +@c In the AC case we would cancel the thread and the mutex would remain +@c locked and we can't recover from that. +Behaves like @code{pthread_cond_timedwait} except the time @var{abstime} is +measured against the clock specified by @var{clockid} rather than the clock +specified or defaulted when @code{pthread_cond_init} was called. Currently, +@var{clockid} must be either @code{CLOCK_MONOTONIC} or +@code{CLOCK_REALTIME}. +@end deftypefun + +@comment pthread.h +@deftypefun int pthread_rwlock_clockrdlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@standards{POSIX-1.2024, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +Behaves like @code{pthread_rwlock_timedrdlock} except the time +@var{abstime} is measured against the clock specified by @var{clockid} +rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either +@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is +returned. +@end deftypefun + +@comment pthread.h +@deftypefun int pthread_rwlock_clockwrlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@standards{POSIX-1.2024, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +Behaves like @code{pthread_rwlock_timedwrlock} except the time +@var{abstime} is measured against the clock specified by @var{clockid} +rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either +@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is +returned. +@end deftypefun + + +@node POSIX Semaphores +@subsection POSIX Semaphores + +@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@manpagefunctionstub{sem_init,3} +@c Does not atomically update sem_t therefore AC-unsafe +@c because it can leave sem_t partially initialized. +@end deftypefun + +@deftypefun int sem_destroy (sem_t *@var{sem}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@manpagefunctionstub{sem_destroy,3} +@c Function does nothing and is therefore always safe. +@end deftypefun + +@deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} +@manpagefunctionstub{sem_open,3} +@c pthread_once asuinit +@c +@c We are AC-Unsafe because we use pthread_once to initialize +@c a global variable that holds the location of the mounted +@c shmfs on Linux. +@end deftypefun + +@deftypefun int sem_close (sem_t *@var{sem}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@manpagefunctionstub{sem_close,3} +@c lll_lock asulock aculock +@c twalk mtsrace{:root} +@c +@c We are AS-unsafe because we take a non-recursive lock. +@c We are AC-unsafe because several internal data structures +@c are not updated atomically. +@end deftypefun + +@deftypefun int sem_unlink (const char *@var{name}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} +@manpagefunctionstub{sem_unlink,3} +@c pthread_once asuinit acucorrupt aculock +@c mempcpy acucorrupt +@end deftypefun + +@deftypefun int sem_wait (sem_t *@var{sem}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@manpagefunctionstub{sem_wait,3} +@c atomic_fetch_add_relaxed (nwaiters) acucorrupt +@c +@c Given the use atomic operations this function seems +@c to be AS-safe. It is AC-unsafe because there is still +@c a window between atomic_fetch_add_relaxed and the pthread_push +@c of the handler that undoes that operation. A cancellation +@c at that point would fail to remove the process from the +@c waiters count. +@end deftypefun + +@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@manpagefunctionstub{sem_timedwait,3} +@c Same safety issues as sem_wait. +@end deftypefun + +@deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@standards{POSIX.1-2024, semaphore.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +Behaves like @code{sem_timedwait} except the time @var{abstime} is measured +against the clock specified by @var{clockid} rather than +@code{CLOCK_REALTIME}. Currently, @var{clockid} must be either +@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}. +@end deftypefun + +@deftypefun int sem_trywait (sem_t *@var{sem}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@manpagefunctionstub{sem_trywait,3} +@c All atomic operations are safe in all contexts. +@end deftypefun + +@deftypefun int sem_post (sem_t *@var{sem}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@manpagefunctionstub{sem_post,3} +@c Same safety as sem_trywait. +@end deftypefun + +@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}) +@standards{POSIX.1-2008, semaphore.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@manpagefunctionstub{sem_getvalue,3} +@c Atomic write of a value is safe in all contexts. +@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 @@ -626,8 +1129,9 @@ the standard. * Default Thread Attributes:: Setting default attributes for threads in a process. * Initial Thread Signal Mask:: Setting the initial mask of threads. -* Waiting with Explicit Clocks:: Functions for waiting with an - explicit clock specification. +* 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. @@ -746,63 +1250,42 @@ 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 Waiting with Explicit Clocks -@subsubsection Functions for Waiting According to a Specific Clock +@node Thread CPU Affinity +@subsubsection Thread CPU Affinity -@Theglibc{} provides several waiting functions that expect an explicit -@code{clockid_t} argument. +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. -@comment semaphore.h -@comment POSIX-proposed -@deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -Behaves like @code{sem_timedwait} except the time @var{abstime} is measured -against the clock specified by @var{clockid} rather than -@code{CLOCK_REALTIME}. Currently, @var{clockid} must be either -@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}. +@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 -@comment pthread.h -@comment POSIX-proposed -@deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c If exactly the same function with arguments is called from a signal -@c handler that interrupts between the mutex unlock and sleep then it -@c will unlock the mutex twice resulting in undefined behaviour. Keep -@c in mind that the unlock and sleep are only atomic with respect to other -@c threads (really a happens-after relationship for pthread_cond_broadcast -@c and pthread_cond_signal). -@c In the AC case we would cancel the thread and the mutex would remain -@c locked and we can't recover from that. -Behaves like @code{pthread_cond_timedwait} except the time @var{abstime} is -measured against the clock specified by @var{clockid} rather than the clock -specified or defaulted when @code{pthread_cond_init} was called. Currently, -@var{clockid} must be either @code{CLOCK_MONOTONIC} or -@code{CLOCK_REALTIME}. +@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 -@comment pthread.h -@comment POSIX-proposed -@deftypefun int pthread_rwlock_clockrdlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -Behaves like @code{pthread_rwlock_timedrdlock} except the time -@var{abstime} is measured against the clock specified by @var{clockid} -rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either -@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is -returned. +@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 -@comment pthread.h -@comment POSIX-proposed -@deftypefun int pthread_rwlock_clockwrlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -Behaves like @code{pthread_rwlock_timedwrlock} except the time -@var{abstime} is measured against the clock specified by @var{clockid} -rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either -@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is -returned. +@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 + +@Theglibc{} provides several extensions to the @code{pthread_join} +function. + @comment pthread.h @comment GNU extension @deftypefun int pthread_tryjoin_np (pthread_t *@var{thread}, void **@var{thread_return}) @@ -835,6 +1318,24 @@ Currently, @var{clockid} must be either @code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}. @end deftypefun +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 6b1080d..d003ddb 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,10 +529,40 @@ 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} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Get the current time according to the clock identified by @var{clock}, storing it as seconds and nanoseconds in @code{*@var{ts}}. @xref{Time Types}, for a description of @code{struct timespec}. @@ -553,6 +584,7 @@ clock: @deftypefun int clock_getres (clockid_t @var{clock}, struct timespec *@var{res}) @standards{POSIX.1, time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Get the actual resolution of the clock identified by @var{clock}, storing it in @code{*@var{ts}}. @@ -593,6 +625,7 @@ Systems may support more than just this @w{ISO C} clock. @deftypefun int timespec_get (struct timespec *@var{ts}, int @var{base}) @standards{ISO, time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Store into @code{*@var{ts}} the current time according to the @w{ISO C} time @var{base}. @@ -601,6 +634,7 @@ The return value is @var{base} on success and @code{0} on failure. @deftypefun int timespec_getres (struct timespec *@var{res}, int @var{base}) @standards{ISO, time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @var{ts} is non-null, store into @code{*@var{ts}} the resolution of the time provided by @code{timespec_get} function for the @w{ISO C} time @var{base}. @@ -1827,7 +1861,7 @@ can be placed in the buffer @var{s} the return value is zero, with the same problems indicated in the @code{strftime} documentation. @end deftypefun -@deftypefun {Deprecated function} {char *} asctime (const struct tm *@var{brokentime}) +@deftypefn {Deprecated function} {char *} asctime (const struct tm *@var{brokentime}) @standards{ISO, time.h} @safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}} @c asctime @mtasurace:asctime @mtslocale @@ -1861,9 +1895,9 @@ string.) @strong{Portability note:} This obsolescent function is deprecated in C23. Programs should instead use @code{strftime} or even @code{sprintf}. -@end deftypefun +@end deftypefn -@deftypefun {Deprecated function} {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) +@deftypefn {Deprecated function} {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) @standards{???, time.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c asctime_r @mtslocale @@ -1882,9 +1916,9 @@ it returns @code{NULL}. @strong{Portability Note:} POSIX.1-2024 removed this obsolescent function. Programs should instead use @code{strftime} or even @code{sprintf}. -@end deftypefun +@end deftypefn -@deftypefun {Deprecated function} {char *} ctime (const time_t *@var{time}) +@deftypefn {Deprecated function} {char *} ctime (const time_t *@var{time}) @standards{ISO, time.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -1907,9 +1941,9 @@ Calling @code{ctime} also sets the time zone state as if @strong{Portability note:} This obsolescent function is deprecated in C23. Programs should instead use @code{strftime} or even @code{sprintf}. -@end deftypefun +@end deftypefn -@deftypefun {Deprecated function} {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) +@deftypefn {Deprecated function} {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) @standards{???, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -1933,7 +1967,7 @@ it returns @code{NULL}. @strong{Portability Note:} POSIX.1-2024 removed this obsolescent function. Programs should instead use @code{strftime} or even @code{sprintf}. -@end deftypefun +@end deftypefn @node Parsing Date and Time @subsection Convert textual time and date information back @@ -3146,12 +3180,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 @@ -3160,36 +3194,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/tsort.awk b/manual/tsort.awk index 848c7c6..00223a5 100644 --- a/manual/tsort.awk +++ b/manual/tsort.awk @@ -1,6 +1,6 @@ #!/usr/bin/awk -f # Generate topologically sorted list of manual chapters. -# Copyright (C) 1998-2024 Free Software Foundation, Inc. +# Copyright (C) 1998-2025 Free Software Foundation, Inc. BEGIN { cnt = 0 diff --git a/manual/tunables.texi b/manual/tunables.texi index 0b1b2898..d11ca7e 100644 --- a/manual/tunables.texi +++ b/manual/tunables.texi @@ -355,6 +355,38 @@ tests for @code{AT_SECURE} programs and not meant to be a security feature. The default value of this tunable is @samp{0}. @end deftp +@deftp Tunable glibc.rtld.execstack +@Theglibc{} will use either the default architecture ABI flags (that might +contain the executable bit) or the value of @code{PT_GNU_STACK} (if present) +to define whether to mark the stack non-executable and if the program or +any shared library dependency requires an executable stack the loader will +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), @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. + +Some systems do not have separate page protection flags at the hardware +level for read access and execute access (sometimes called read-implies-exec). +This mode can also be enabled on certain systems where the hardware supports +separate protection flags. The @theglibc{} tunable configuration is independent +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 +can be worked around by setting the tunable to @code{2}, where the stack is +always executable. +@end deftp + @node Elision Tunables @section Elision Tunables @cindex elision tunables @@ -641,6 +673,49 @@ This tunable is specific to x86-64 and effective only when the lazy binding is disabled. @end deftp +@deftp Tunable glibc.cpu.aarch64_gcs +This tunable controls Guarded Control Stack (GCS) for the process. + +Accepted values are: + +0 = disabled: do not enable GCS. + +1 = enforced: check markings and fail if any binary is not marked. + +2 = optional: check markings but keep GCS off if any binary is unmarked. + +3 = override: enable GCS, markings are ignored. + +If unmarked binary is loaded via @code{dlopen} when GCS is enabled and +markings are not ignored (@code{aarch64_gcs == 1} or @code{2}), then +the process will be aborted. + +Default is @code{0}, so GCS is disabled by default. + +This tunable is specific to AArch64. On systems that do not support +Guarded Control Stack this tunable has no effect. + +Before enabling GCS for the process the value of this tunable is checked +and depending on it the following outcomes are possible. + +@code{aarch64_gcs == 0}: GCS will not be enabled and GCS markings will not be +checked for any binaries. + +@code{aarch64_gcs == 1}: GCS markings will be checked for all binaries loaded +at startup and, only if all binaries are GCS-marked, GCS will be enabled. If +any of the binaries are not GCS-marked, the process will abort. Subsequent call +to @code{dlopen} for an unmarked binary will also result in abort. + +@code{aarch64_gcs == 2}: GCS markings will be checked for all binaries loaded +at startup and, if any of such binaries are not GCS-marked, GCS will not be +enabled and there will be no more checks for GCS marking. If all binaries +loaded at startup are GCS-marked, then GCS will be enabled, in which case a +call to @code{dlopen} for an unmarked binary will also result in abort. + +@code{aarch64_gcs == 3}: GCS will be enabled and GCS markings will not be +checked for any binaries. +@end deftp + @node Memory Related Tunables @section Memory Related Tunables @cindex memory related tunables |