aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
Diffstat (limited to 'manual')
-rw-r--r--manual/creature.texi4
-rw-r--r--manual/examples/memstrm.c2
-rw-r--r--manual/filesys.texi245
-rw-r--r--manual/getopt.texi31
-rw-r--r--manual/install.texi8
-rw-r--r--manual/libc.texinfo2
-rw-r--r--manual/maint.texi2
-rw-r--r--manual/math.texi32
-rw-r--r--manual/memory.texi8
-rw-r--r--manual/resource.texi199
-rw-r--r--manual/socket.texi79
-rw-r--r--manual/stdio.texi26
-rw-r--r--manual/terminal.texi164
-rw-r--r--manual/threads.texi396
-rw-r--r--manual/time.texi117
-rw-r--r--manual/tunables.texi2
16 files changed, 1222 insertions, 95 deletions
diff --git a/manual/creature.texi b/manual/creature.texi
index 09e1c96..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
diff --git a/manual/examples/memstrm.c b/manual/examples/memstrm.c
index 9ee6298..28be892 100644
--- a/manual/examples/memstrm.c
+++ b/manual/examples/memstrm.c
@@ -16,6 +16,7 @@
*/
#include <stdio.h>
+#include <stdlib.h>
int
main (void)
@@ -31,6 +32,7 @@ main (void)
fprintf (stream, ", world");
fclose (stream);
printf ("buf = `%s', size = %zu\n", bp, size);
+ free (bp);
return 0;
}
diff --git a/manual/filesys.texi b/manual/filesys.texi
index aabb683..e1c7be8 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -310,12 +310,17 @@ This is a GNU extension.
The flags argument in @code{@dots{}at} functions can be a combination of
the following flags, defined in @file{fcntl.h}. Not all such functions
support all flags, and some (such as @code{openat}) do not accept a
-flags argument at all.
-
-In the flag descriptions below, the @dfn{effective final path component}
-refers to the final component (basename) of the full path constructed
-from the descriptor and file name arguments, using file name lookup, as
-described above.
+flags argument at all. Although the flags specific to each function have
+distinct values from each other, some flags (relevant to different
+functions) might share the same value and therefore are not guaranteed to
+have unique values.
+
+A non-exhaustive list of common flags and their descriptions follows. Flags
+specific to a function are described alongside the function itself. In
+these flag descriptions, the @dfn{effective final path component} refers to
+the final component (basename) of the full path constructed from the
+descriptor and file name arguments, using file name lookup, as described
+above.
@vtable @code
@item AT_EMPTY_PATH
@@ -353,6 +358,28 @@ a non-final component of the file name are still followed.
argument to the @code{getauxval} function (with @code{AT_@dots{}}
constants defined in @file{elf.h}). @xref{Auxiliary Vector}.
+@cindex common errors in descriptor-relative functions
+@cindex common errors in @code{@dots{}at} functions
+
+The @code{@dots{}at} functions have some common error conditions due to the
+nature of descriptor-relative access. A list of common errors and their
+descriptions follows. Errors specific to a function are described alongside
+the function itself.
+
+@table @code
+@item EBADF
+The file name argument is a relative path but the descriptor argument
+is neither @code{AT_FDCWD} nor a valid file descriptor.
+
+@item EINVAL
+If the function accepts a @var{flags} argument, the flag combination passed
+is not valid for the function.
+
+@item ENOTDIR
+The file name argument is a relative file name but the descriptor
+argument is associated with a file that is not a directory.
+@end table
+
@node Accessing Directories
@section Accessing Directories
@cindex accessing directories
@@ -409,18 +436,41 @@ entries. It contains the following fields:
This is the null-terminated file name component. This is the only
field you can count on in all POSIX systems.
+While this field is defined with a specified length, functions such as
+@code{readdir} may return a pointer to a @code{struct dirent} where the
+@code{d_name} extends beyond the end of the struct.
+
@item ino_t d_fileno
This is the file serial number. For BSD compatibility, you can also
refer to this member as @code{d_ino}. On @gnulinuxhurdsystems{} and most POSIX
systems, for most files this the same as the @code{st_ino} member that
@code{stat} will return for the file. @xref{File Attributes}.
+@item off_t d_off
+This value contains the offset of the next directory entry (after this
+entry) in the directory stream. The value may not be compatible with
+@code{lseek} or @code{seekdir}, especially if the width of @code{d_off}
+is less than 64 bits. Directory entries are not ordered by offset, and
+the @code{d_off} and @code{d_reclen} values are unrelated. Seeking on
+directory streams is not recommended. The symbol
+@code{_DIRENT_HAVE_D_OFF} is defined if the @code{d_ino} member is
+available.
+
@item unsigned char d_namlen
This is the length of the file name, not including the terminating
null character. Its type is @code{unsigned char} because that is the
integer type of the appropriate size. This member is a BSD extension.
The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is
-available.
+available. (It is not available on Linux.)
+
+@item unsigned short int d_reclen
+This is the length of the entire directory record. When iterating
+through a buffer filled by @code{getdents64} (@pxref{Low-level Directory
+Access}), this value needs to be added to the offset of the current
+directory entry to obtain the offset of the next entry. When using
+@code{readdir} and related functions, the value of @code{d_reclen} is
+undefined and should not be accessed. The symbol
+@code{_DIRENT_HAVE_D_RECLEN} is defined if this member is available.
@item unsigned char d_type
This is the type of the file, possibly unknown. The following constants
@@ -457,7 +507,7 @@ This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_TYPE}
is defined if this member is available. On systems where it is used, it
corresponds to the file type bits in the @code{st_mode} member of
@code{struct stat}. If the value cannot be determined the member
-value is DT_UNKNOWN. These two macros convert between @code{d_type}
+value is @code{DT_UNKNOWN}. These two macros convert between @code{d_type}
values and @code{st_mode} values:
@deftypefun int IFTODT (mode_t @var{mode})
@@ -632,6 +682,20 @@ and can be rewritten by a subsequent call.
return entries for @file{.} and @file{..}, even though these are always
valid file names in any directory. @xref{File Name Resolution}.
+If a directory is modified between a call to @code{readdir} and after
+the directory stream was created or @code{rewinddir} was last called on
+it, it is unspecified according to POSIX whether newly created or
+removed entries appear among the entries returned by repeated
+@code{readdir} calls before the end of the directory is reached.
+However, due to practical implementation constraints, it is possible
+that entries (including unrelated, unmodified entries) appear multiple
+times or do not appear at all if the directory is modified while listing
+it. If the application intends to create files in the directory, it may
+be necessary to complete the iteration first and create a copy of the
+information obtained before creating any new files. (See below for
+instructions regarding copying of @code{d_name}.) The iteration can be
+restarted using @code{rewinddir}. @xref{Random Access Directory}.
+
If there are no more entries in the directory or an error is detected,
@code{readdir} returns a null pointer. The following @code{errno} error
conditions are defined for this function:
@@ -812,6 +876,10 @@ directory since it was opened with @code{opendir}. (Entries for these
files might or might not be returned by @code{readdir} if they were
added or removed since you last called @code{opendir} or
@code{rewinddir}.)
+
+For example, it is recommended to call @code{rewinddir} followed by
+@code{readdir} to check if a directory is empty after listing it with
+@code{readdir} and deleting all encountered files from it.
@end deftypefun
@deftypefun {long int} telldir (DIR *@var{dirstream})
@@ -823,6 +891,13 @@ added or removed since you last called @code{opendir} or
The @code{telldir} function returns the file position of the directory
stream @var{dirstream}. You can use this value with @code{seekdir} to
restore the directory stream to that position.
+
+Using the the @code{telldir} function is not recommended.
+
+The value returned by @code{telldir} may not be compatible with the
+@code{d_off} field in @code{struct dirent}, and cannot be used with the
+@code{lseek} function. The returned value may not unambiguously
+identify the position in the directory stream.
@end deftypefun
@deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos})
@@ -836,6 +911,9 @@ stream @var{dirstream} to @var{pos}. The value @var{pos} must be the
result of a previous call to @code{telldir} on this particular stream;
closing and reopening the directory can invalidate values returned by
@code{telldir}.
+
+Using the the @code{seekdir} function is not recommended. To seek to
+the beginning of the directory stream, use @code{rewinddir}.
@end deftypefun
@@ -1007,9 +1085,20 @@ Note that some file systems support file names longer than
@code{NAME_MAX} bytes (e.g., because they support up to 255 Unicode
characters), so a buffer size of at least 1024 is recommended.
+If the directory has been modified since the first call to
+@code{getdents64} on the directory (opening the descriptor or seeking to
+offset zero), it is possible that the buffer contains entries that have
+been encountered before. Likewise, it is possible that files that are
+still present are not reported before the end of the directory is
+encountered (and @code{getdents64} returns zero).
+
This function is specific to Linux.
@end deftypefun
+Systems that support @code{getdents64} support seeking on directory
+streams. @xref{File Position Primitive}. However, the only offset that
+works reliably is offset zero, indicating that reading the directory
+should start from the beginning.
@node Working with Directory Trees
@section Working with Directory Trees
@@ -1690,6 +1779,31 @@ file system and can't be modified.
@end table
@end deftypefun
+@deftypefun int unlinkat (int @var{filedes}, const char *@var{filename}, int @var{flags})
+@standards{POSIX.1-2008, unistd.h}
+@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+This function is a descriptor-relative version of the @code{unlink}
+function above. @xref{Descriptor-Relative Access}. The @var{flags}
+argument may either be @code{0} or contain the flag @code{AT_REMOVEDIR}:
+
+@table @code
+@item AT_REMOVEDIR
+This flag causes @code{unlinkat} to perform an @code{rmdir} operation on
+@code{filename} instead of performing the equivalent of @code{unlink}.
+@end table
+
+Compared to @code{unlink}, some additional error conditions can occur due to
+descriptor-relative access. @xref{Descriptor-Relative Access}. In
+addition to this, the following other errors can also occur:
+
+@table @code
+@item EISDIR
+The effective final path derived from @var{filename} and @var{filedes} is a
+directory but @code{AT_REMOVEDIR} was not passed in @code{flags}.
+@end table
+@end deftypefun
+
@deftypefun int rmdir (const char *@var{filename})
@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@@ -1821,6 +1935,20 @@ file systems.
@end table
@end deftypefun
+@deftypefun int renameat (int @var{oldfiledes}, const char *@var{oldname}, int @var{newfiledes}, const char *@var{newname})
+@standards{POSIX.1-2008, stdio.h}
+@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+This function is a descriptor-relative version of the @code{rename}
+function above. @xref{Descriptor-Relative Access}. If @var{oldname} or
+@var{newname} is a relative path, it is interpreted relative to the
+directory associated with @var{oldfiledes} or @var{newfiledes},
+respectively. Absolute paths are interpreted in the usual way.
+
+Compared to @code{rename}, some additional error conditions can occur.
+@xref{Descriptor-Relative Access}.
+@end deftypefun
+
@node Creating Directories
@section Creating Directories
@cindex creating a directory
@@ -1875,6 +2003,17 @@ To use this function, your program should include the header file
@pindex sys/stat.h
@end deftypefun
+@deftypefun int mkdirat (int @var{filedes}, const char *@var{filename}, mode_t @var{mode})
+@standards{POSIX.1-2008, sys/stat.h}
+@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+This function is a descriptor-relative version of the @code{mkdir}
+function above. @xref{Descriptor-Relative Access}.
+
+Compared to @code{mkdir}, some additional error conditions can occur.
+@xref{Descriptor-Relative Access}.
+@end deftypefun
+
@node File Attributes
@section File Attributes
@@ -2980,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
@@ -3148,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.
@@ -3157,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
@@ -3760,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 7fcdda9..006f93b 100644
--- a/manual/install.texi
+++ b/manual/install.texi
@@ -552,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.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
diff --git a/manual/libc.texinfo b/manual/libc.texinfo
index ff0beb1..870ed7a 100644
--- a/manual/libc.texinfo
+++ b/manual/libc.texinfo
@@ -29,7 +29,7 @@
@comment %**end of header (This is for running Texinfo on a region.)
@c Everything related to printed editions is disabled until we have
-@c resolved how to keep them in sync with the master sources of the
+@c resolved how to keep them in sync with the primary sources of the
@c manual.
@c sold 0.06/1.09, print run out 21may96
@c @set EDITION 0.13
diff --git a/manual/maint.texi b/manual/maint.texi
index b6ee5b6..3176546 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -496,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 adbe271..fbabf37 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -803,6 +803,22 @@ The @code{pown} functions are from TS 18661-4:2015 (which used
@code{long long int} in C23).
@end deftypefun
+@deftypefun double compoundn (double @var{x}, long long int @var{power})
+@deftypefunx float compoundnf (float @var{x}, long long int @var{power})
+@deftypefunx {long double} compoundnl (long double @var{x}, long long int @var{power})
+@deftypefunx _FloatN compoundnfN (_Float@var{N} @var{x}, long long int @var{power})
+@deftypefunx _FloatNx compoundnfNx (_Float@var{N}x @var{x}, long long int @var{power})
+@standards{TS 18661-4:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These return @code{1 + @var{x}} raised to @var{power} (an integer).
+If @var{x} is less than @minus{}1, @code{compoundn} signals a domain
+error.
+
+The @code{compoundn} functions are from TS 18661-4:2015 (which used
+@code{intmax_t} as the type of @var{power}; the type changed to
+@code{long long int} in C23).
+@end deftypefun
+
@cindex square root function
@deftypefun double sqrt (double @var{x})
@deftypefunx float sqrtf (float @var{x})
@@ -867,6 +883,22 @@ instead of the direct formula is wise, since the error is
much smaller. See also the function @code{cabs} in @ref{Absolute Value}.
@end deftypefun
+@deftypefun double rootn (double @var{x}, long long int @var{n})
+@deftypefunx float rootnf (float @var{x}, long long int @var{n})
+@deftypefunx {long double} rootnl (long double @var{x}, long long int @var{n})
+@deftypefunx _FloatN rootnfN (_Float@var{N} @var{x}, long long int @var{n})
+@deftypefunx _FloatNx rootnfNx (_Float@var{N}x @var{x}, long long int @var{n})
+@standards{TS 18661-4:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These return the @var{n}th root of @var{x}. If @var{n} is zero, or if
+@var{x} is negative and @var{n} is even, @code{rootn} signals a domain
+error.
+
+The @code{rootn} functions are from TS 18661-4:2015 (which used
+@code{intmax_t} as the type of @var{n}; the type changed to
+@code{long long int} in C23).
+@end deftypefun
+
@deftypefun double expm1 (double @var{x})
@deftypefunx float expm1f (float @var{x})
@deftypefunx {long double} expm1l (long double @var{x})
diff --git a/manual/memory.texi b/manual/memory.texi
index 9a29c7d..46f76c1 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -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. */
@@ -3256,9 +3256,9 @@ not @math{-1}.
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Change the access restrictions of the current thread for memory pages with
the protection key @var{key} to @var{access_restrictions}. If
-@var{access_restrictions} is zero, no additional access restrictions on top of
-the page protection flags are applied. Otherwise, @var{access_restrictions} is
-a combination of the following flags:
+@var{access_restrictions} is @code{PKEY_UNRESTRICTED} (zero), no additional
+access restrictions on top of the page protection flags are applied. Otherwise,
+@var{access_restrictions} is a combination of the following flags:
@vtable @code
@item PKEY_DISABLE_READ
diff --git a/manual/resource.texi b/manual/resource.texi
index acdb1f3..1fd0310 100644
--- a/manual/resource.texi
+++ b/manual/resource.texi
@@ -977,7 +977,7 @@ multiple parameters (not just priority and niceness).
It is expected that these interfaces will be compatible with all future
scheduling policies.
-For additional information about scheduling policies, consult consult
+For additional information about scheduling policies, consult
the manual pages @manpageurl{sched,7} and @manpageurl{sched_setattr,2}.
@strong{Note:} Calling the @code{sched_setattr} function is incompatible
@@ -1015,7 +1015,7 @@ For additional information, consult the manual page
@manpageurl{sched_setattr,2}.
@end deftp
-@deftypefun int sched_setaddr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int flags)
+@deftypefun int sched_setattr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int flags)
@standards{Linux, sched.h}
@safety{@mtsafe{}@assafe{}@acsafe{}}
This functions applies the scheduling policy described by
@@ -1058,7 +1058,7 @@ policy of the thread @var{tid}.
Other error codes depend on the scheduling policy.
@end deftypefun
-@deftypefun int sched_getaddr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int size, unsigned int flags)
+@deftypefun int sched_getattr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int size, unsigned int flags)
@standards{Linux, sched.h}
@safety{@mtsafe{}@assafe{}@acsafe{}}
This function obtains the scheduling policy of the thread @var{tid}
@@ -1362,26 +1362,73 @@ extent the Linux kernel interface.
@standards{GNU, sched.h}
This data set is a bitset where each bit represents a CPU. How the
system's CPUs are mapped to bits in the bitset is system dependent.
-The data type has a fixed size; in the unlikely case that the number
-of bits are not sufficient to describe the CPUs of the system a
-different interface has to be used.
+The data type has a fixed size; it is strongly recommended to allocate
+a dynamically sized set based on the actual number of CPUs detected,
+such as via @code{get_nprocs_conf()}, and use the @code{CPU_*_S}
+variants instead of the fixed-size ones.
This type is a GNU extension and is defined in @file{sched.h}.
@end deftp
-To manipulate the bitset, to set and reset bits, a number of macros are
-defined. Some of the macros take a CPU number as a parameter. Here
-it is important to never exceed the size of the bitset. The following
-macro specifies the number of bits in the @code{cpu_set_t} bitset.
+To manipulate the bitset, to set and reset bits, and thus add and
+remove CPUs from the sets, a number of macros are defined. Some of
+the macros take a CPU number as a parameter. Here it is important to
+never exceed the size of the bitset, either @code{CPU_SETSIZE} for
+fixed sets or the allocated size for dynamic sets. For each macro
+there is a fixed-size version (documented below) and a dynamic-sized
+version (with a @code{_S} suffix).
@deftypevr Macro int CPU_SETSIZE
@standards{GNU, sched.h}
The value of this macro is the maximum number of CPUs which can be
-handled with a @code{cpu_set_t} object.
+handled with a fixed @code{cpu_set_t} object.
@end deftypevr
+For applications that require CPU sets larger than the built-in size,
+a set of macros that support dynamically-sized sets are defined.
+
+@deftypefn Macro size_t CPU_ALLOC_SIZE (size_t @var{count})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_ALLOC_SIZE ok
+@c __CPU_ALLOC_SIZE ok
+Given a count of CPUs to hold, returns the size of the set to
+allocate. This return value is appropriate to be used in the *_S macros.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@deftypefn Macro {cpu_set_t *} CPU_ALLOC (size_t @var{count})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c CPU_ALLOC
+@c __CPU_ALLOC
+@c __sched_cpualloc
+@c malloc
+Given the count of CPUs to hold, returns a set large enough to hold
+them; that is, the resulting set will be valid for CPUs numbered 0
+through @var{count}-1, inclusive. This set must be freed via
+@code{CPU_FREE} to avoid memory leaks. Warning: the argument is the
+CPU @emph{count} and not the size returned by @code{CPU_ALLOC_SIZE}.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@deftypefn Macro void CPU_FREE (cpu_set_t *@var{set})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c CPU_FREE
+@c __CPU_FREE
+@c __sched_cpufree
+@c free
+Frees a CPU set previously allocated by @code{CPU_ALLOC}.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
The type @code{cpu_set_t} should be considered opaque; all
-manipulation should happen via the next four macros.
+manipulation should happen via the @code{CPU_*} macros described
+below.
@deftypefn Macro void CPU_ZERO (cpu_set_t *@var{set})
@standards{GNU, sched.h}
@@ -1424,6 +1471,39 @@ evaluated more than once.
This macro is a GNU extension and is defined in @file{sched.h}.
@end deftypefn
+@deftypefn Macro {cpu_set_t *} CPU_AND (cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_AND ok
+@c __CPU_OP_S ok
+This macro populates @var{dest} with only those CPUs included in both
+@var{src1} and @var{src2}. Its value is @var{dest}.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@deftypefn Macro {cpu_set_t *} CPU_OR (cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_OR ok
+@c __CPU_OP_S ok
+This macro populates @var{dest} with those CPUs included in either
+@var{src1} or @var{src2}. Its value is @var{dest}.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@deftypefn Macro {cpu_set_t *} CPU_XOR (cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_XOR ok
+@c __CPU_OP_S ok
+This macro populates @var{dest} with those CPUs included in either
+@var{src1} or @var{src2}, but not both. Its value is @var{dest}.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
@deftypefn Macro int CPU_ISSET (int @var{cpu}, const cpu_set_t *@var{set})
@standards{GNU, sched.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@@ -1440,6 +1520,54 @@ evaluated more than once.
This macro is a GNU extension and is defined in @file{sched.h}.
@end deftypefn
+@deftypefn Macro int CPU_COUNT (const cpu_set_t *@var{set})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_COUNT ok
+@c __CPU_COUNT_S ok
+@c __sched_cpucount ok
+@c countbits ok
+This macro returns the count of CPUs (bits) set in @var{set}.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@deftypefn Macro int CPU_EQUAL (cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@standards{GNU, sched.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_EQUAL ok
+@c __CPU_EQUAL_S ok
+@c memcmp ok
+This macro returns nonzero if the two sets @var{set1} and @var{set2}
+have the same contents; that is, the set of CPUs represented by both
+sets is identical.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@deftypefn Macro void CPU_ZERO_S (size_t @var{size}, cpu_set_t *@var{set})
+@end deftypefn
+@deftypefn Macro void CPU_SET_S (int @var{cpu}, size_t @var{size}, cpu_set_t *@var{set})
+@end deftypefn
+@deftypefn Macro void CPU_CLR_S (int @var{cpu}, size_t @var{size}, cpu_set_t *@var{set})
+@end deftypefn
+@deftypefn Macro {cpu_set_t *} CPU_AND_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@end deftypefn
+@deftypefn Macro {cpu_set_t *} CPU_OR_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@end deftypefn
+@deftypefn Macro {cpu_set_t *} CPU_XOR_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@end deftypefn
+@deftypefn Macro int CPU_ISSET_S (int @var{cpu}, size_t @var{size}, const cpu_set_t *@var{set})
+@end deftypefn
+@deftypefn Macro int CPU_COUNT_S (size_t @var{size}, const cpu_set_t *@var{set})
+@end deftypefn
+@deftypefn Macro int CPU_EQUAL_S (size_t @var{size}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
+@end deftypefn
+
+Each of these macros performs the same action as its non-@code{_S} variant,
+but takes a @var{size} argument to specify the set size. This
+@var{size} argument is as returned by the @code{CPU_ALLOC_SIZE} macro,
+defined above.
CPU bitsets can be constructed from scratch or the currently installed
affinity mask can be retrieved from the system.
@@ -1525,6 +1653,53 @@ The operating system does not support this function.
This function is Linux-specific and is declared in @file{sched.h}.
@end deftypefun
+@deftypefun int sched_getcpu (void)
+@standards{Linux, <sched.h>}
+
+Similar to @code{getcpu} but with a simpler interface. On success,
+returns a nonnegative number identifying the CPU on which the current
+thread is running. Returns @code{-1} on failure. The following
+@code{errno} error condition is defined for this function:
+
+@table @code
+@item ENOSYS
+The operating system does not support this function.
+@end table
+
+This function is Linux-specific and is declared in @file{sched.h}.
+@end deftypefun
+
+Here's an example of how to use most of the above to limit the number
+of CPUs a process runs on, not including error handling or good logic
+on CPU choices:
+
+@example
+#define _GNU_SOURCE
+#include <sched.h>
+#include <sys/sysinfo.h>
+#include <unistd.h>
+void
+limit_cpus (void)
+@{
+ unsigned int mycpu;
+ size_t nproc, cssz, cpu;
+ cpu_set_t *cs;
+ getcpu (&mycpu, NULL);
+ nproc = get_nprocs_conf ();
+ cssz = CPU_ALLOC_SIZE (nproc);
+ cs = CPU_ALLOC (nproc);
+ sched_getaffinity (0, cssz, cs);
+ if (CPU_COUNT_S (cssz, cs) > nproc / 2)
+ @{
+ for (cpu = nproc / 2; cpu < nproc; cpu ++)
+ if (cpu != mycpu)
+ CPU_CLR_S (cpu, cssz, cs);
+ sched_setaffinity (0, cssz, cs);
+ @}
+ CPU_FREE (cs);
+@}
+@end example
+
@node Memory Resources
@section Querying memory available resources
diff --git a/manual/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/stdio.texi b/manual/stdio.texi
index 01b9f47..29ed720 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -1231,17 +1231,18 @@ convenient to have functions to read a line of text from a stream.
Standard C has functions to do this, but they aren't very safe: null
characters and even (for @code{gets}) long lines can confuse them. So
-@theglibc{} provides the nonstandard @code{getline} function that
-makes it easy to read lines reliably.
+@theglibc{} provides the @code{getline} function that makes it easy to
+read lines reliably.
-Another GNU extension, @code{getdelim}, generalizes @code{getline}. It
-reads a delimited record, defined as everything through the next
-occurrence of a specified delimiter character.
+The @code{getdelim} function is a generalized version of @code{getline}.
+It reads a delimited record, defined as everything through the next
+occurrence of a specified delimiter character. These functions were
+both GNU extensions until standardized by POSIX.1-2008.
All these functions are declared in @file{stdio.h}.
-@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
-@standards{GNU, stdio.h}
+@deftypefun ssize_t getline (char **restrict @var{lineptr}, size_t *restrict @var{n}, FILE *restrict @var{stream})
+@standards{POSIX.1-2008, stdio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
@c Besides the usual possibility of getting an inconsistent stream in a
@c signal handler or leaving it inconsistent in case of cancellation,
@@ -1274,15 +1275,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
@@ -1294,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:
diff --git a/manual/terminal.texi b/manual/terminal.texi
index b437cb5..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
diff --git a/manual/threads.texi b/manual/threads.texi
index 67955e1..eeefa9b 100644
--- a/manual/threads.texi
+++ b/manual/threads.texi
@@ -552,16 +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
@@ -769,6 +852,272 @@ against the clock specified by @var{clockid} rather than
@end deftypefun
+@node POSIX Barriers
+@subsection POSIX Barriers
+
+A POSIX barrier works as follows: a file-local or global
+@code{pthread_barrier_t} object is initialized via
+@code{pthread_barrier_init} to require @var{count} threads to wait on
+it. After that, up to @var{count}-1 threads will wait on the barrier
+via @code{pthread_barrier_wait}. None of these calls will return
+until @var{count} threads are waiting via the next call to
+@code{pthread_barrier_wait}, at which point, all of these calls will
+return. The net result is that @var{count} threads will be
+synchronized at that point. At some point after this, the barrier is
+destroyed via @code{pthread_barrier_destroy}. Note that a barrier
+must be destroyed before being re-initialized, to ensure that all
+threads are properly synchronized, but need not be destroyed and
+re-initialized before being reused.
+
+@deftypefun int pthread_barrier_init (pthread_barrier_t *@var{barrier}, const pthread_barrierattr_t *@var{attr}, unsigned int @var{count})
+@standards{POSIX, pthread.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function initializes a barrier to synchronize @var{count}
+threads. The barrier must be uninitialized or destroyed before it is
+initialized; attempting to initialize an in-use barrier results in
+undefined behavior.
+
+The @var{attr} argument to @code{pthread_barrier_init} is typically
+NULL for a process-private barrier, but may be used to share a barrier
+across processes (documentation TBD).
+
+On success, 0 is returned. On error, one of the following is returned:
+
+@table @code
+@item EINVAL
+Either @var{count} is zero, or is large enough to cause an internal
+overflow.
+@end table
+
+@end deftypefun
+
+@deftypefun int pthread_barrier_wait (pthread_barrier_t *@var{barrier})
+@standards{POSIX, pthread.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function synchronizes threads. The first @var{count}-1 threads
+that wait on @var{barrier} will just wait. The next thread that waits
+on @var{barrier} will cause all @var{count} threads' calls to return.
+The @var{barrier} must be initialized with @code{pthread_barrier_init}
+and not yet destroyed with @code{pthread_barrier_destroy}.
+
+The return value of this function is
+@code{PTHREAD_BARRIER_SERIAL_THREAD} for one thread (it is unspecified
+which thread) and 0 for the remainder, for each batch of @var{count}
+threads synchronized. After such a batch is synchronized, the
+@var{barrier} will begin synchronizing the next @var{count} threads.
+
+@end deftypefun
+
+
+@deftypefun int pthread_barrier_destroy (pthread_barrier_t *@var{barrier})
+@standards{POSIX, pthread.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+Destroys @var{barrier} and releases any resources it may have
+allocated. A barrier must not be destroyed if any thread is waiting
+on it, or if it was not initialized. This call always succeeds and
+returns 0.
+
+@end deftypefun
+
+@node POSIX Spin Locks
+@subsection POSIX Spin Locks
+
+A spinlock is a low overhead lock suitable for use in a realtime
+thread where it's known that the thread won't be paused by the
+scheduler. Non-realtime threads should use mutexes instead.
+
+@deftypefun int pthread_spin_init (pthread_spinlock_t *@var{lock}, int @var{pshared})
+Initializes a spinlock. @var{pshared} is one of:
+
+@table @code
+@item PTHREAD_PROCESS_PRIVATE
+This spinlock is private to the process which created it.
+
+@item PTHREAD_PROCESS_SHARED
+This spinlock is shared across any process that can access it, for
+example through shared memory.
+@end table
+
+@manpagefunctionstub{pthread_spin_init, 3}
+@end deftypefun
+
+@deftypefun int pthread_spin_destroy (pthread_spinlock_t *@var{lock})
+Destroys a spinlock and releases any resources it held.
+@manpagefunctionstub{pthread_spin_destroy, 3}
+@end deftypefun
+
+@deftypefun int pthread_spin_lock (pthread_spinlock_t *@var{lock})
+Locks a spinlock. Only one thread at a time can lock a spinlock. If
+another thread has locked this spinlock, the calling thread waits
+until it is unlocked, then attempts to lock it.
+@manpagefunctionstub{pthread_spin_lock, 3}
+@end deftypefun
+
+@deftypefun int pthread_spin_unlock (pthread_spinlock_t *@var{lock})
+Unlocks a spinlock. If one or more threads are waiting for the lock
+to be unlocked, one of them (unspecified which) will succeed in
+locking it, and will return from @code{pthread_spin_lock}).
+@manpagefunctionstub{pthread_spin_unlock, 3}
+@end deftypefun
+
+@deftypefun int pthread_spin_trylock (pthread_spinlock_t *@var{lock})
+Like @code{pthread_spin_unlock} but returns 0 if the lock was
+unlocked, or EBUSY if it was locked.
+@manpagefunctionstub{pthread_spin_trylock, 3}
+@end deftypefun
+
+@node POSIX Mutexes
+@subsection POSIX Mutexes
+
+A @emph{mutex}, or ``mutual exclusion'', is a way of guaranteeing that
+only one thread at a time is able to execute a protected bit of code
+(or access any other resource). Two or more threads trying to execute
+the same code at the same time, will instead take turns, according to
+the mutex.
+
+A mutex is much like a spinlock, but implemented in a way that is more
+appropriate for use in non-realtime threads, and is more
+resource-conserving.
+
+@deftypefun int pthread_mutex_init (pthread_mutex_t *@var{mutex}, const pthread_mutexattr_t *@var{mutexattr})
+Initiailizes a mutex.
+@manpagefunctionstub{pthread_mutex_init, 3}
+@end deftypefun
+
+@deftypefun int pthread_mutex_destroy (pthread_mutex_t *@var{mutex})
+Destroys a no-longer-needed mutex.
+@manpagefunctionstub{pthread_mutex_destroy, 3}
+@end deftypefun
+
+@deftypefun int pthread_mutex_lock (pthread_mutex_t *@var{mutex})
+Only one thread at a time may lock @var{mutex}, and must unlock it
+when appropriate. If a thread calls @code{pthread_mutex_lock} while
+@var{mutex} is locked by another thread, the calling thread will wait
+until @var{mutex} is unlocked, then attempt to lock it. Since there
+may be many threads waiting at the same time, the calling thread may
+need to repeat this wait-and-try many times before it successfully
+locks @var{mutex}, at which point the call to
+@code{pthread_mutex_locks} returns succesfully.
+
+This function may fail with the following:
+
+@table @code
+@item EAGAIN
+Too many locks were attempted.
+
+@item EDEADLK
+The calling thread already holds a lock on @var{mutex}.
+
+@item EINVAL
+@var{mutex} has an invalid kind, or an invalid priority was requested.
+
+@item ENOTRECOVERABLE
+The thread holding the lock died in a way that the system cannot recover from.
+
+@item EOWNERDEAD
+The thread holding the lock died in a way that the system can recover from.
+
+@end table
+
+@manpagefunctionstub{pthread_mutex_lock, 3}
+@end deftypefun
+
+@deftypefun int pthread_mutex_trylock (pthread_mutex_t *@var{mutex})
+Like @code{pthread_mutex_lock} but if the lock cannot be immediately
+obtained, returns EBUSY.
+@manpagefunctionstub{pthread_mutex_trylock, 3}
+@end deftypefun
+
+@deftypefun int pthread_mutex_unlock (pthread_mutex_t *@var{mutex})
+Unlocks @var{mutex}. Returns EPERM if the calling thread doesn't hold
+the lock on @var{mutex}.
+@manpagefunctionstub{pthread_mutex_unlock, 3}
+@end deftypefun
+
+@deftypefun int pthread_mutex_clocklock (pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime})
+@end deftypefun
+
+@deftypefun int pthread_mutex_timedlock (pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})
+
+These two functions act like @code{pthread_mutex_lock} with the
+exception that the call will not wait past time @var{abstime}, as
+reported by @var{clockid} or (for @code{pthread_mutex_timedlock})
+@code{CLOCK_REALTIME}. If @var{abstime} is reached and the mutex
+still cannot be locked, an @code{ETIMEDOUT} error is returned.
+If the time had already passed when these functions
+are called, and the mutex cannot be immediately locked, the function
+times out immediately.
+@end deftypefun
+
+@deftypefun int pthread_mutexattr_init (const pthread_mutexattr_t *@var{attr})
+Initializes @var{attr} with default values.
+@manpagefunctionstub{pthread_mutexattr_init, 3}
+@end deftypefun
+
+@deftypefun int pthread_mutexattr_destroy (pthread_mutexattr_t *@var{attr})
+Destroys @var{attr} and releases any resources it may have allocated.
+@manpagefunctionstub{pthread_mutexattr_destroy, 3}
+@end deftypefun
+
+@deftypefun int pthread_mutexattr_settype (pthread_mutexattr_t *@var{attr}, int @var{kind})
+This functions allow you to change what kind of mutex a mutex is, by
+changing the attributes used to initialize it. The values for
+@var{kind} are:
+
+@table @code
+@item PTHREAD_MUTEX_NORMAL
+No attempt to detect deadlock is performed; a thread will deadlock if
+it tries to lock this mutex yet already holds a lock to it.
+Attempting to unlock a mutex not locked by the calling thread results
+in undefined behavior.
+
+@item PTHREAD_MUTEX_ERRORCHECK
+Attemps to relock a mutex, or unlock a mutex not held, will result in an error.
+
+@item PTHREAD_MUTEX_RECURSIVE
+Attempts to relock a mutex already held succeed, but require a
+matching number of unlocks to release it. Attempts to unlock a mutex
+not held will result in an error.
+
+@item PTHREAD_MUTEX_DEFAULT
+Attemps to relock a mutex, or unlock a mutex not held, will result in
+undefined behavior. This is the default.
+
+@end table
+@end deftypefun
+
+@deftypefun int pthread_mutexattr_gettype (const pthread_mutexattr_t *@var{attr}, int *@var{kind})
+This function gets the kind of mutex @var{mutex} is.
+@end deftypefun
+
+@node POSIX Threads Other APIs
+@subsection POSIX Threads Other APIs
+
+@deftypefun int pthread_equal (pthread_t @var{thread1}, pthread_t @var{thread2})
+Compares two thread IDs. If they are the same, returns nonzero, else returns zero.
+@manpagefunctionstub{pthread_equal, 3}
+@end deftypefun
+
+@deftypefun int pthread_getcpuclockid (pthread_t @var{th}, __clockid_t *@var{clock_id})
+Get the clock associated with @var{th}.
+@manpagefunctionstub{pthread_getcpuclockid, 3}
+@end deftypefun
+
+@deftypefun int pthread_once (pthread_once_t *@var{once_control}, void (*@var{init_routine}) (void))
+Calls @var{init_routine} once for each @var{once_control}, which must
+be statically initalized to @code{PTHREAD_ONCE_INIT}. Subsequent
+calls to @code{pthread_once} with the same @var{once_control} do not
+call @var{init_routine}, even in multi-threaded environments.
+@manpagefunctionstub{pthread_once, 3}
+@end deftypefun
+
+@deftypefun int pthread_sigmask (int @var{how}, const __sigset_t *@var{newmask}, __sigset_t *@var{oldmask})
+@manpagefunctionstub{pthread_sigmask, 3}
+@end deftypefun
+
@node Non-POSIX Extensions
@subsection Non-POSIX Extensions
@@ -780,7 +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.
+* Thread CPU Affinity:: Limiting which CPUs can run a thread.
* Joining Threads:: Wait for a thread to terminate.
+* Thread Names:: Changing the name of a thread.
* Single-Threaded:: Detecting single-threaded execution.
* Restartable Sequences:: Linux-specific restartable sequences
integration.
@@ -899,6 +1250,36 @@ signal mask and use @code{pthread_sigmask} to apply it to the thread.
If the signal mask was copied to a heap allocation, the copy should be
freed.
+@node Thread CPU Affinity
+@subsubsection Thread CPU Affinity
+
+Processes and threads normally run on any available CPU. However,
+they can be given an @emph{affinity} to one or more CPUs, which limits
+them to the CPU set specified.
+
+@deftypefun int pthread_attr_setaffinity_np (pthread_attr_t *@var{attr}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset})
+Sets the CPU affinity in @var{attr}. The CPU affinity
+controls which CPUs a thread may execute on. @xref{CPU Affinity}.
+@manpagefunctionstub{pthread_attr_setaffinity_np, 3}
+@end deftypefun
+
+@deftypefun int pthread_attr_getaffinity_np (const pthread_attr_t *@var{attr}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset})
+Gets the CPU affinity settings from @var{attr}.
+@manpagefunctionstub{pthread_attr_getaffinity_np, 3}
+@end deftypefun
+
+@deftypefun int pthread_setaffinity_np (pthread_t *@var{th}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset})
+Sets the CPU affinity for thread @var{th}. The CPU affinity controls
+which CPUs a thread may execute on. @xref{CPU Affinity}.
+@manpagefunctionstub{pthread_setaffinity_np, 3}
+@end deftypefun
+
+@deftypefun int pthread_getaffinity_np (const pthread_t *@var{th}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset})
+Gets the CPU affinity for thread @var{th}. The CPU affinity controls
+which CPUs a thread may execute on. @xref{CPU Affinity}.
+@manpagefunctionstub{pthread_getaffinity_np, 3}
+@end deftypefun
+
@node Joining Threads
@subsubsection Wait for a thread to terminate
@@ -940,6 +1321,21 @@ Currently, @var{clockid} must be either @code{CLOCK_MONOTONIC} or
The @code{sem_clockwait} function also works using a @code{clockid_t}
argument. @xref{POSIX Semaphores}.
+@node Thread Names
+@subsubsection Thread Names
+
+@deftypefun int pthread_setname_np (pthread_t @var{th}, const char *@var{name})
+Gives thread @var{th} the name @var{name}. This name shows up in
+@code{ps} when it's listing individual threads. @var{name} is a
+NUL-terminated string of no more than 15 non-NUL characters.
+@manpagefunctionstub{pthread_setname_np, 3}
+@end deftypefun
+
+@deftypefun int pthread_getname_np (pthread_t @var{th}, char *@var{buf}, size_t @var{buflen})
+Retrieves the name of thread @var{th}.
+@manpagefunctionstub{pthread_getname_np, 3}
+@end deftypefun
+
@node Single-Threaded
@subsubsection Detecting Single-Threaded Execution
diff --git a/manual/time.texi b/manual/time.texi
index 04c97f5..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,7 +529,36 @@ Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure
absolute time, only elapsed time.
@end deftypevr
-Systems may support more than just these two POSIX clocks.
+The following clocks are defined by POSIX, but may not be supported by
+all POSIX systems:
+
+@deftypevr Macro clockid_t CLOCK_PROCESS_CPUTIME_ID
+@standards{POSIX.1, time.h}
+This POSIX clock measures the amount of CPU time used by the calling
+process.
+@end deftypevr
+
+@deftypevr Macro clockid_t CLOCK_THREAD_CPUTIME_ID
+@standards{POSIX.1, time.h}
+This POSIX clock measures the amount of CPU time used by the calling
+thread.
+@end deftypevr
+
+The following clocks are Linux extensions:
+
+@deftypevr Macro clockid_t CLOCK_MONOTONIC_RAW
+@deftypevrx Macro clockid_t CLOCK_REALTIME_COARSE
+@deftypevrx Macro clockid_t CLOCK_MONOTONIC_COARSE
+@deftypevrx Macro clockid_t CLOCK_BOOTTIME
+@deftypevrx Macro clockid_t CLOCK_REALTIME_ALARM
+@deftypevrx Macro clockid_t CLOCK_BOOTTIME_ALARM
+@deftypevrx Macro clockid_t CLOCK_TAI
+@standards{Linux, time.h}
+For details of these clocks, see the manual page
+@manpageurl{clock_gettime,2}.
+@end deftypevr
+
+Systems may support additional clocks beyond those listed here.
@deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts})
@standards{POSIX.1, time.h}
@@ -3150,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
@@ -3164,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/tunables.texi b/manual/tunables.texi
index 67064f5..d11ca7e 100644
--- a/manual/tunables.texi
+++ b/manual/tunables.texi
@@ -367,7 +367,7 @@ 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. Tthis is provided for compatibility reasons, when
+stack at process start. This is provided for compatibility reasons, when
the program dynamically loads modules with @code{dlopen} which require
an executable stack.
generated by cgit v1.1 at 2025-07-02 02:28:04 +0000