aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
Diffstat (limited to 'manual')
-rw-r--r--manual/Makefile31
-rw-r--r--manual/charset.texi18
-rw-r--r--manual/check-deftype.sh50
-rw-r--r--manual/creature.texi7
-rw-r--r--manual/filesys.texi196
-rw-r--r--manual/ipc.texi28
-rw-r--r--manual/llio.texi88
-rw-r--r--manual/macros.texi7
-rw-r--r--manual/memory.texi62
-rw-r--r--manual/resource.texi115
-rw-r--r--manual/startup.texi17
-rw-r--r--manual/stdio.texi114
-rw-r--r--manual/threads.texi2
-rw-r--r--manual/time.texi18
14 files changed, 648 insertions, 105 deletions
diff --git a/manual/Makefile b/manual/Makefile
index a6c05db..6a4cfbe 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -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.
@@ -152,10 +166,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/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..395c99a
--- /dev/null
+++ b/manual/check-deftype.sh
@@ -0,0 +1,50 @@
+#!/bin/sh
+
+# Copyright 2024 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/creature.texi b/manual/creature.texi
index be0a5ac..09e1c96 100644
--- a/manual/creature.texi
+++ b/manual/creature.texi
@@ -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/filesys.texi b/manual/filesys.texi
index 47d9297..aabb683 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,151 @@ 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.
+
+In the flag descriptions below, the @dfn{effective final path component}
+refers to the final component (basename) of the full path constructed
+from the descriptor and file name arguments, using file name lookup, as
+described above.
+
+@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}.
@node Accessing Directories
@section Accessing Directories
@@ -1250,10 +1396,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:
@@ -2091,9 +2238,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}
diff --git a/manual/ipc.texi b/manual/ipc.texi
index 6a6e5ad..32c5ac0 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,35 +30,35 @@ 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});
+@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});
+@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}, ...);
+@deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...)
@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
@c pthread_once asuinit
@c
@@ -67,7 +67,7 @@ by @theglibc{}.
@c shmfs on Linux.
@end deftypefun
-@deftypefun int sem_close (sem_t *@var{sem});
+@deftypefun int sem_close (sem_t *@var{sem})
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c lll_lock asulock aculock
@c twalk mtsrace{:root}
@@ -77,13 +77,13 @@ by @theglibc{}.
@c are not updated atomically.
@end deftypefun
-@deftypefun int sem_unlink (const char *@var{name});
+@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});
+@deftypefun int sem_wait (sem_t *@var{sem})
@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
@c atomic_fetch_add_relaxed (nwaiters) acucorrupt
@c
@@ -95,22 +95,22 @@ by @theglibc{}.
@c waiters count.
@end deftypefun
-@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime});
+@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});
+@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});
+@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});
+@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
diff --git a/manual/llio.texi b/manual/llio.texi
index ea84196..b6bc7f2 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
@@ -1725,6 +1796,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
@@ -3807,7 +3887,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 +4874,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..f48dd4e 100644
--- a/manual/macros.texi
+++ b/manual/macros.texi
@@ -282,10 +282,13 @@ cwd\comments\
@macro standardsx {element, standard, header}
@end macro
+@macro manpageurl {func, sec}
+@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}
+@end macro
+
@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}.
+function, consult the manual page @manpageurl{\func\,\sec\}.
@xref{Linux Kernel}.
@end macro
diff --git a/manual/memory.texi b/manual/memory.texi
index 3710d7e..324c120 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -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
@@ -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,14 +3251,14 @@ 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 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_WRITE
@@ -3290,18 +3290,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/resource.texi b/manual/resource.texi
index 25966bc..612520d 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
@@ -952,6 +953,120 @@ 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 consult
+the manual pages @manpageurl{sched,7} and @manpageurl{sched_setattr,2}.
+@xref{Linux Kernel}.
+
+@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}. @xref{Linux Kernel}.
+@end deftp
+
+@deftypefun int sched_setaddr (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_getaddr (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} are not updated 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
diff --git a/manual/startup.texi b/manual/startup.texi
index 747beed..95b0ed8 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -664,8 +664,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 +1014,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 +1022,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..83f4f92 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})
@@ -1474,11 +1481,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 +1577,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 +1598,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 +2374,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 +2543,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
@@ -2722,6 +2776,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 +4180,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
diff --git a/manual/threads.texi b/manual/threads.texi
index 25e99c9..9ea137c 100644
--- a/manual/threads.texi
+++ b/manual/threads.texi
@@ -592,7 +592,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
diff --git a/manual/time.texi b/manual/time.texi
index 6b1080d..90bc9a2 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -532,6 +532,7 @@ Systems may support more than just these two POSIX clocks.
@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 +554,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}}.
@@ -1827,7 +1829,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 +1863,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 +1884,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 +1909,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 +1935,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
generated by cgit v1.1 at 2024-11-16 23:01:16 +0000