diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/contrib.texi | 53 | ||||
| -rw-r--r-- | manual/creature.texi | 4 | ||||
| -rw-r--r-- | manual/dynlink.texi | 17 | ||||
| -rw-r--r-- | manual/examples/memstrm.c | 2 | ||||
| -rw-r--r-- | manual/examples/select.c | 2 | ||||
| -rw-r--r-- | manual/filesys.texi | 250 | ||||
| -rw-r--r-- | manual/getopt.texi | 31 | ||||
| -rw-r--r-- | manual/install.texi | 30 | ||||
| -rw-r--r-- | manual/intro.texi | 3 | ||||
| -rw-r--r-- | manual/libc.texinfo | 2 | ||||
| -rw-r--r-- | manual/llio.texi | 21 | ||||
| -rw-r--r-- | manual/maint.texi | 6 | ||||
| -rw-r--r-- | manual/math.texi | 32 | ||||
| -rw-r--r-- | manual/memory.texi | 8 | ||||
| -rw-r--r-- | manual/resource.texi | 199 | ||||
| -rw-r--r-- | manual/socket.texi | 79 | ||||
| -rw-r--r-- | manual/startup.texi | 4 | ||||
| -rw-r--r-- | manual/stdio.texi | 4 | ||||
| -rw-r--r-- | manual/terminal.texi | 483 | ||||
| -rw-r--r-- | manual/threads.texi | 396 | ||||
| -rw-r--r-- | manual/time.texi | 114 |
21 files changed, 1536 insertions, 204 deletions
diff --git a/manual/contrib.texi b/manual/contrib.texi index 3d1b170..30681fa 100644 --- a/manual/contrib.texi +++ b/manual/contrib.texi @@ -22,10 +22,13 @@ Rogerio Alves Cardoso for various fixes to PowerPC. Amrita H. S. for contributions to the PowerPC port. @item -John David Anglin for various fixes and co-maintainership of the HPPA +John David Anglin for many fixes and co-maintainership of the HPPA port. @item +H. Peter Anvin for work on the termios code. + +@item Albert ARIBAUD for Y2038 related fixes. @item @@ -139,14 +142,15 @@ Joana Cruz for contributions to the AArch64 port. Palmer Dabbelt for contributing the port to Linux/RISC-V. @item -DJ Delorie for maintenance of Linux/RISC-V, and numerous fixes. +DJ Delorie for maintenance of Linux/RISC-V, numerous fixes, and handbook +contributions. @item Jianbo Deng for the work on the Loongson port. @item -Wilco Dijkstra for various fixes and many improvements of the AArch64 -port. +Wilco Dijkstra for various fixes and many improvements as well as +maintainership of the AArch64 port. @item Liubov Dmitrieva for optimized string and math functions on x86-64 and @@ -206,6 +210,9 @@ Olaf Flebbe and Ralf B@"achle for contributing @file{sysdeps/mips/fpu_control.h}. @item +Dylan Fleming for work on the AArch64 port. + +@item Alistair Francis for Y2038 related fixes. @item @@ -213,6 +220,9 @@ Mike Frysinger for his maintaining of the IA64 architecture and for testing and bug fixing. @item +Collin Funk for various fixes and manual improvements. + +@item Martin Galvan for contributing gdb pretty printer support to glibc and adding an initial set of pretty printers for structures in the POSIX Threads library. @@ -309,6 +319,9 @@ his direction as part of @theglibc{} steering committee. Simon Josefsson for the @code{libidn} add-on. @item +Ben Kallus for various fixes. + +@item Geoffrey Keating for the port to Linux on PowerPC (@code{powerpc-@var{anything}-linux}). @@ -322,7 +335,8 @@ Mark Kettenis for implementing the @code{utmpx} interface and a utmp daemon, and for a Hesiod NSS module. @item -Yury Khrustalev for work on the AArch64 port and various fixes. +Yury Khrustalev for extensive work on the AArch64 port and its +maintainership, and various fixes. @item Simon Kissane for gmon improvements. @@ -353,7 +367,7 @@ for NSS (@file{nscd}). Akhilesh Kumar for various fixes to locales. @item -Luna Lamb for contributions to the AArch64 port. +Luna Lamb for various contributions to the AArch64 port. @item Jeff Law for various fixes. @@ -384,6 +398,9 @@ implementations, for implementing Intel Control-Flow Enforcement Technology, many x86-64 improvements, and many bug fixes. @item +Zhaoming Luo for work on the hurd port. + +@item Rafa@l{} Lu@dotaccent{z}y@'nski for contributing support for two grammatical forms of month names, and for various fixes to locales. @@ -449,6 +466,9 @@ Cupertino Miranda for various fixes. Alan Modra for his improvements for Linux on PowerPC. @item +Lenard Mollenkopf for work on C2Y support. + +@item Sachin Monga for various fixes and contributions to the PowerPC port. @item @@ -496,7 +516,7 @@ encryption support for ARM and various fixes. @item Carlos O'Donell for his maintainership of the HPPA architecture, for maintaining @theglibc{} web pages and wiki, for his direction as FSF -Project Steward for @theglibc{} and various bug fixes. +Project Steward for @theglibc{} and numerous bug fixes. @item Alexandre Oliva for adding TLS descriptors for LD and GD on x86 and @@ -506,7 +526,7 @@ safety documentation in the manual, for his direction as FSF Project Maintainer and for various fixes. @item -Sunil K. Pandey for many fixes. +Sunil K. Pandey for many fixes and x86-64 improvements. @item Ronan Pigott for various fixes. @@ -525,8 +545,8 @@ Yat Long Poon for contributions to the Aarch64 port. @item Siddhesh Poyarekar for various fixes, an implementation of a framework for -performance benchmarking of functions and implementing the tunables -infrastructure. +performance benchmarking of functions, implementing the tunables +infrastructure, and handbook improvements. @item Tom Quinn for contributing the startup code to support SunOS shared @@ -587,7 +607,7 @@ Andrew Senkevich for contributing vector math function implementations for x86. Carlos Eduardo Seo for optimized functions on PowerPC. @item -Arjun Shankar for testing, bug fixing, and handbook contributions. +Arjun Shankar for testing, bug fixing, and many handbook contributions. @item Marcus Shawcroft for contributing the AArch64 port. @@ -658,8 +678,9 @@ function family. Ulrich Weigand for various fixes to the PowerPC64 and Arm ports. @item -Florian Weimer for his maintainership of the network component, for handling -of security issues, and for numerous fixes and contributions. +Florian Weimer for his maintainership of the network and dynamic-link +components, for handling of security issues, and for numerous fixes and +contributions. @item Zack Weinberg for the @code{explicit_bzero} implementation and for various @@ -686,7 +707,8 @@ YunQiang Su for work on the MIPS port. @item Adhemerval Zanella for optimized functions on PowerPC, ISO C threads support, the work on tunables, fortify improvements, the CORE-MATH integration, -thread safety, and numerous further contributions and fixes. +thread safety, handling of security issues, and numerous further contributions +and fixes. @item Xuelei Zhang for optimized functions on AArch64. @@ -698,6 +720,9 @@ Junxian Zhu for work on the MIPS and RISC-V port. Paul Zimmermann for the work on mathematical functions and their testsuite. +@item +Claudiu Zissulescu for work on the SFrame support. + @end itemize Some code in @theglibc{} comes from other projects and might be under diff --git a/manual/creature.texi b/manual/creature.texi index 09e1c96..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/dynlink.texi b/manual/dynlink.texi index 3a4864f..cd05107 100644 --- a/manual/dynlink.texi +++ b/manual/dynlink.texi @@ -545,7 +545,8 @@ result data to the caller. @table @code @item unsigned long long int dlfo_flags -Currently unused and always 0. +Bit zero signals if SFrame stack data is valid. See +@code{DLFO_FLAG_SFRAME} below. @item void *dlfo_map_start The start address of the inspected mapping. This information comes from @@ -562,6 +563,11 @@ This member contains a pointer to the link map of the object. This member contains a pointer to the exception handling data of the object. See @code{DLFO_EH_SEGMENT_TYPE} below. +@item void *dlfo_sframe +This member points to the SFrame stack trace data associated with the +object. It is valid only when @code{DLFO_FLAG_SFRAME} is set in +@code{dlfo_flags}; otherwise, it may be null or undefined. + @end table This structure is a GNU extension. @@ -639,6 +645,15 @@ information is processed. This function is a GNU extension. @end deftypefun +The following flag masks are defined for use with @code{dlfo_flags}: + +@table @code +@item DLFO_FLAG_SFRAME +A bit mask used to signal that the object contains SFrame data. See +@code{dlfo_sframe} above. + +@end table + @node Dynamic Linker Hardening @section Avoiding Unexpected Issues With Dynamic Linking diff --git a/manual/examples/memstrm.c b/manual/examples/memstrm.c index 9ee6298..28be892 100644 --- a/manual/examples/memstrm.c +++ b/manual/examples/memstrm.c @@ -16,6 +16,7 @@ */ #include <stdio.h> +#include <stdlib.h> int main (void) @@ -31,6 +32,7 @@ main (void) fprintf (stream, ", world"); fclose (stream); printf ("buf = `%s', size = %zu\n", bp, size); + free (bp); return 0; } diff --git a/manual/examples/select.c b/manual/examples/select.c index 1398c7f..341b65f 100644 --- a/manual/examples/select.c +++ b/manual/examples/select.c @@ -20,7 +20,7 @@ #include <stdio.h> #include <unistd.h> #include <sys/types.h> -#include <sys/time.h> +#include <sys/select.h> /*@end group*/ /*@group*/ diff --git a/manual/filesys.texi b/manual/filesys.texi index aabb683..f49d7d7 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -310,12 +310,17 @@ This is a GNU extension. The flags argument in @code{@dots{}at} functions can be a combination of the following flags, defined in @file{fcntl.h}. Not all such functions support all flags, and some (such as @code{openat}) do not accept a -flags argument at all. - -In the flag descriptions below, the @dfn{effective final path component} -refers to the final component (basename) of the full path constructed -from the descriptor and file name arguments, using file name lookup, as -described above. +flags argument at all. Although the flags specific to each function have +distinct values from each other, some flags (relevant to different +functions) might share the same value and therefore are not guaranteed to +have unique values. + +A non-exhaustive list of common flags and their descriptions follows. Flags +specific to a function are described alongside the function itself. In +these flag descriptions, the @dfn{effective final path component} refers to +the final component (basename) of the full path constructed from the +descriptor and file name arguments, using file name lookup, as described +above. @vtable @code @item AT_EMPTY_PATH @@ -353,6 +358,28 @@ a non-final component of the file name are still followed. argument to the @code{getauxval} function (with @code{AT_@dots{}} constants defined in @file{elf.h}). @xref{Auxiliary Vector}. +@cindex common errors in descriptor-relative functions +@cindex common errors in @code{@dots{}at} functions + +The @code{@dots{}at} functions have some common error conditions due to the +nature of descriptor-relative access. A list of common errors and their +descriptions follows. Errors specific to a function are described alongside +the function itself. + +@table @code +@item EBADF +The file name argument is a relative path but the descriptor argument +is neither @code{AT_FDCWD} nor a valid file descriptor. + +@item EINVAL +If the function accepts a @var{flags} argument, the flag combination passed +is not valid for the function. + +@item ENOTDIR +The file name argument is a relative file name but the descriptor +argument is associated with a file that is not a directory. +@end table + @node Accessing Directories @section Accessing Directories @cindex accessing directories @@ -409,18 +436,41 @@ entries. It contains the following fields: This is the null-terminated file name component. This is the only field you can count on in all POSIX systems. +While this field is defined with a specified length, functions such as +@code{readdir} may return a pointer to a @code{struct dirent} where the +@code{d_name} extends beyond the end of the struct. + @item ino_t d_fileno This is the file serial number. For BSD compatibility, you can also refer to this member as @code{d_ino}. On @gnulinuxhurdsystems{} and most POSIX systems, for most files this the same as the @code{st_ino} member that @code{stat} will return for the file. @xref{File Attributes}. +@item off_t d_off +This value contains the offset of the next directory entry (after this +entry) in the directory stream. The value may not be compatible with +@code{lseek} or @code{seekdir}, especially if the width of @code{d_off} +is less than 64 bits. Directory entries are not ordered by offset, and +the @code{d_off} and @code{d_reclen} values are unrelated. Seeking on +directory streams is not recommended. The symbol +@code{_DIRENT_HAVE_D_OFF} is defined if the @code{d_ino} member is +available. + @item unsigned char d_namlen This is the length of the file name, not including the terminating null character. Its type is @code{unsigned char} because that is the integer type of the appropriate size. This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is -available. +available. (It is not available on Linux.) + +@item unsigned short int d_reclen +This is the length of the entire directory record. When iterating +through a buffer filled by @code{getdents64} (@pxref{Low-level Directory +Access}), this value needs to be added to the offset of the current +directory entry to obtain the offset of the next entry. When using +@code{readdir} and related functions, the value of @code{d_reclen} is +undefined and should not be accessed. The symbol +@code{_DIRENT_HAVE_D_RECLEN} is defined if this member is available. @item unsigned char d_type This is the type of the file, possibly unknown. The following constants @@ -457,7 +507,7 @@ This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_TYPE} is defined if this member is available. On systems where it is used, it corresponds to the file type bits in the @code{st_mode} member of @code{struct stat}. If the value cannot be determined the member -value is DT_UNKNOWN. These two macros convert between @code{d_type} +value is @code{DT_UNKNOWN}. These two macros convert between @code{d_type} values and @code{st_mode} values: @deftypefun int IFTODT (mode_t @var{mode}) @@ -632,6 +682,20 @@ and can be rewritten by a subsequent call. return entries for @file{.} and @file{..}, even though these are always valid file names in any directory. @xref{File Name Resolution}. +If a directory is modified between a call to @code{readdir} and after +the directory stream was created or @code{rewinddir} was last called on +it, it is unspecified according to POSIX whether newly created or +removed entries appear among the entries returned by repeated +@code{readdir} calls before the end of the directory is reached. +However, due to practical implementation constraints, it is possible +that entries (including unrelated, unmodified entries) appear multiple +times or do not appear at all if the directory is modified while listing +it. If the application intends to create files in the directory, it may +be necessary to complete the iteration first and create a copy of the +information obtained before creating any new files. (See below for +instructions regarding copying of @code{d_name}.) The iteration can be +restarted using @code{rewinddir}. @xref{Random Access Directory}. + If there are no more entries in the directory or an error is detected, @code{readdir} returns a null pointer. The following @code{errno} error conditions are defined for this function: @@ -812,6 +876,10 @@ directory since it was opened with @code{opendir}. (Entries for these files might or might not be returned by @code{readdir} if they were added or removed since you last called @code{opendir} or @code{rewinddir}.) + +For example, it is recommended to call @code{rewinddir} followed by +@code{readdir} to check if a directory is empty after listing it with +@code{readdir} and deleting all encountered files from it. @end deftypefun @deftypefun {long int} telldir (DIR *@var{dirstream}) @@ -823,6 +891,13 @@ added or removed since you last called @code{opendir} or The @code{telldir} function returns the file position of the directory stream @var{dirstream}. You can use this value with @code{seekdir} to restore the directory stream to that position. + +Using the the @code{telldir} function is not recommended. + +The value returned by @code{telldir} may not be compatible with the +@code{d_off} field in @code{struct dirent}, and cannot be used with the +@code{lseek} function. The returned value may not unambiguously +identify the position in the directory stream. @end deftypefun @deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos}) @@ -836,6 +911,9 @@ stream @var{dirstream} to @var{pos}. The value @var{pos} must be the result of a previous call to @code{telldir} on this particular stream; closing and reopening the directory can invalidate values returned by @code{telldir}. + +Using the the @code{seekdir} function is not recommended. To seek to +the beginning of the directory stream, use @code{rewinddir}. @end deftypefun @@ -1007,9 +1085,20 @@ Note that some file systems support file names longer than @code{NAME_MAX} bytes (e.g., because they support up to 255 Unicode characters), so a buffer size of at least 1024 is recommended. +If the directory has been modified since the first call to +@code{getdents64} on the directory (opening the descriptor or seeking to +offset zero), it is possible that the buffer contains entries that have +been encountered before. Likewise, it is possible that files that are +still present are not reported before the end of the directory is +encountered (and @code{getdents64} returns zero). + This function is specific to Linux. @end deftypefun +Systems that support @code{getdents64} support seeking on directory +streams. @xref{File Position Primitive}. However, the only offset that +works reliably is offset zero, indicating that reading the directory +should start from the beginning. @node Working with Directory Trees @section Working with Directory Trees @@ -1690,6 +1779,31 @@ file system and can't be modified. @end table @end deftypefun +@deftypefun int unlinkat (int @var{filedes}, const char *@var{filename}, int @var{flags}) +@standards{POSIX.1-2008, unistd.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{unlink} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument may either be @code{0} or contain the flag @code{AT_REMOVEDIR}: + +@table @code +@item AT_REMOVEDIR +This flag causes @code{unlinkat} to perform an @code{rmdir} operation on +@code{filename} instead of performing the equivalent of @code{unlink}. +@end table + +Compared to @code{unlink}, some additional error conditions can occur due to +descriptor-relative access. @xref{Descriptor-Relative Access}. In +addition to this, the following other errors can also occur: + +@table @code +@item EISDIR +The effective final path derived from @var{filename} and @var{filedes} is a +directory but @code{AT_REMOVEDIR} was not passed in @code{flags}. +@end table +@end deftypefun + @deftypefun int rmdir (const char *@var{filename}) @standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @@ -1821,6 +1935,20 @@ file systems. @end table @end deftypefun +@deftypefun int renameat (int @var{oldfiledes}, const char *@var{oldname}, int @var{newfiledes}, const char *@var{newname}) +@standards{POSIX.1-2008, stdio.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{rename} +function above. @xref{Descriptor-Relative Access}. If @var{oldname} or +@var{newname} is a relative path, it is interpreted relative to the +directory associated with @var{oldfiledes} or @var{newfiledes}, +respectively. Absolute paths are interpreted in the usual way. + +Compared to @code{rename}, some additional error conditions can occur. +@xref{Descriptor-Relative Access}. +@end deftypefun + @node Creating Directories @section Creating Directories @cindex creating a directory @@ -1875,6 +2003,17 @@ To use this function, your program should include the header file @pindex sys/stat.h @end deftypefun +@deftypefun int mkdirat (int @var{filedes}, const char *@var{filename}, mode_t @var{mode}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{mkdir} +function above. @xref{Descriptor-Relative Access}. + +Compared to @code{mkdir}, some additional error conditions can occur. +@xref{Descriptor-Relative Access}. +@end deftypefun + @node File Attributes @section File Attributes @@ -2259,6 +2398,11 @@ The @var{flags} argument is not valid for this function. @item ENOTDIR The descriptor @var{filedes} is not associated with a directory, and @var{filename} is a relative file name. + +@item ENOENT +The file named by @var{filename} does not exist, it's a dangling symbolic link +and @var{flags} does not contain @code{AT_SYMLINK_NOFOLLOW}, or @var{filename} +is an empty string and @var{flags} does not contain @code{AT_EMPTY_PATH}. @end table When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this @@ -2980,6 +3124,29 @@ Flag meaning test for execute/search permission. Flag meaning test for existence of the file. @end deftypevr +@deftypefun int faccessat (int @var{filedes}, const char *@var{filename}, int @var{how}, int @var{flags}) +@standards{POSIX.1-2008, unistd.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{access} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument can contain a combination of the flags @code{AT_EACCESS} described +below, @code{AT_EMPTY_PATH}, and @code{AT_SYMLINK_NOFOLLOW}. + +@vtable @code +@item AT_EACCESS +This flag when passed to the @code{faccessat} function causes it to perform +access checks using effective user and group IDs instead of real IDs, which +is the default and matches the @code{access} function. +@end vtable + +Compared to @code{access}, some additional error conditions can occur. +@xref{Descriptor-Relative Access}. + +This function may not work correctly on older kernels missing the +@code{faccessat2} system call. +@end deftypefun + @node File Times @subsection File Times @@ -3148,6 +3315,10 @@ permission for the file, or be a privileged user. @item EBADF The @var{filedes} argument is not a valid file descriptor. +@item EINVAL +At least one of the fields in the @code{tvp} array passed has an invalid +value. + @item EPERM If the @var{times} argument is not a null pointer, you must either be the owner of the file or be a privileged user. @@ -3157,6 +3328,64 @@ The file lives on a read-only file system. @end table @end deftypefun +@deftypefun int futimens (int @var{filedes}, const struct timespec @var{tsp}@t{[2]}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is like @code{futimes}, except that it sets the file access +and modification timestamps with nanosecond precision. The argument +@code{tsp} is used similarly to @code{futimes}' @code{tvp}, but has a +@code{const struct timespec} type that can express calendar time with +nanosecond precision. @xref{Time Types}. +@end deftypefun + +@deftypefun int utimensat (int @var{filedes}, const char *@var{filename}, const struct timespec @var{tsp}@t{[2]}, int @var{flags}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{futimens} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument can contain a combination of the flags @code{AT_EMPTY_PATH}, and +@code{AT_SYMLINK_NOFOLLOW}. The call: + +@smallexample +futimens (@var{filedes}, @var{tsp}) +@end smallexample + +is equivalent to: + +@smallexample +utimensat (@var{filedes}, @code{NULL}, @var{tsp}, 0) +@end smallexample + +Compared to @code{futimens}, some additional error conditions can occur due +to descriptor-relative access. @xref{Descriptor-Relative Access}. In +addition to this, the following other errors can also occur: + +@table @code +@item EINVAL +The @var{filename} argument is NULL, @var{filedes} is not @code{AT_FDCWD}, +and @var{flags} is not @code{0}. + +@item ELOOP +There are too many levels of indirection. This can be the result of +circular symbolic links to directories. + +@item ENAMETOOLONG +The resulting path is too long. This error only occurs on systems which +have a limit on the file name length. + +@item ENOENT +The @var{filename} argument is an empty string and @var{flags} does not +contain @code{AT_EMPTY_PATH}, or @var{filename} does not refer to an +existing file. + +@item ESRCH +Search permission was denied for one of the prefix components of the the +@var{filename} argument. +@end table +@end deftypefun + @node File Size @subsection File Size @@ -3760,22 +3989,17 @@ creation always works like @code{open} with @code{O_EXCL}. The @code{mkdtemp} function comes from OpenBSD. @c FIXME these are undocumented: -@c faccessat @c fchmodat @c fchownat @c futimesat @c fstatat (there's a commented-out safety assessment for this one) @c statx -@c mkdirat @c mkfifoat @c name_to_handle_at @c openat @c open_by_handle_at @c readlinkat -@c renameat @c renameat2 @c scandirat @c symlinkat -@c unlinkat -@c utimensat @c mknodat diff --git a/manual/getopt.texi b/manual/getopt.texi index b4c0b15..79a9423 100644 --- a/manual/getopt.texi +++ b/manual/getopt.texi @@ -301,7 +301,10 @@ application to pass long options with only @samp{-} instead of @samp{--}. The @samp{--} prefix is still recognized but instead of looking through the short options if a @samp{-} is seen it is first tried whether this parameter names a long option. If not, it is parsed -as a short option. +as a short option. In case both short and long options could be +matched (this can happen with single letter long options), the short +option is preferred (with some caveats). For long options, +abbreviations are detected as well. Assuming @code{getopt_long_only} is used starting an application with @@ -313,6 +316,32 @@ Assuming @code{getopt_long_only} is used starting an application with the @code{getopt_long_only} will first look for a long option named @samp{foo}. If this is not found, the short options @samp{f}, @samp{o}, and again @samp{o} are recognized. + +It gets more interesting with single letter long options. If we +define options in the following way + +@smallexample + static struct option long_options[] = @{ + @{"f", no_argument, 0, 0 @}, + @{"foo", no_argument, 0, 0 @}, + @{0, 0, 0, 0 @}, + @}; +@end smallexample + +@noindent +use @code{"f"} (as a C string) as an option string and start the +application with @option{-f}, the short option will be matched. +@option{--f} will match the long one. And both @option{-fo} and +@option{-foo} will match the long option @code{"foo"}. + +Be aware that if the option string would be @code{"f:"} (thus the +short option requires an argument), using just @option{-f} leads to an +error. But using @option{-fo} results in the long option being +matched. For passing an argument in this situation, you need to do it +as two arguments (@option{-f}, @option{o}). Though any other value +would work in a single argument (e.g., @option{-f1}), since it would +not match a long option (or its abbreviation). + @end deftypefun @node Getopt Long Option Example diff --git a/manual/install.texi b/manual/install.texi index 7fcdda9..8f8f0a1 100644 --- a/manual/install.texi +++ b/manual/install.texi @@ -320,6 +320,14 @@ If not provided, @option{LEVEL} defaults to highest possible value supported by the build compiler. Default is to disable fortification. + +@item --enable-sframe +Experimental option supported by some architectures, where @theglibc{} +is built with @option{-Wa,--gsframe} if @code{binutils} supports it. +Currently this is only supported on x86_64 and aarch64. The option +enables SFrame support on @code{backtrace}. + +Default is to disable SFrame support. @end table To build the library and related programs, type @code{make}. This will @@ -535,7 +543,7 @@ GCC 12.1 or newer GCC 12.1 or higher is required. In general it is recommended to use the newest version of the compiler that is known to work for building @theglibc{}, as newer compilers usually produce better code. As of -release time, GCC 14.2.1 is the newest compiler verified to work to build +release time, GCC 15.1.1 is the newest compiler verified to work to build @theglibc{}. For multi-arch support it is recommended to use a GCC which has been built with @@ -552,19 +560,13 @@ You can use whatever compiler you like to compile programs that use Check the FAQ for any special compiler issues on particular platforms. @item -GNU @code{binutils} 2.25 or later +GNU @code{binutils} 2.39 or later You must use GNU @code{binutils} (as and ld) to build @theglibc{}. No other assembler or linker has the necessary functionality at the -moment. As of release time, GNU @code{binutils} 2.43.1 is the newest +moment. As of release time, GNU @code{binutils} 2.45 is the newest verified to work to build @theglibc{}. -For PowerPC 64-bits little-endian (powerpc64le), @command{objcopy} is required -to support @option{--update-section}. This option requires binutils 2.26 or -newer. - -ARC architecture needs @code{binutils} 2.32 or higher for TLS related fixes. - @item GNU @code{texinfo} 4.7 or later @@ -581,7 +583,7 @@ GNU @code{awk} 3.1.2, or higher @code{awk} is used in several places to generate files. Some @code{gawk} extensions are used, including the @code{asorti} function, which was introduced in version 3.1.2 of @code{gawk}. -As of release time, @code{gawk} version 5.3.1 is the newest verified +As of release time, @code{gawk} version 5.3.2 is the newest verified to work to build @theglibc{}. Testing the GNU C Library requires @code{gawk} to be compiled with @@ -600,7 +602,7 @@ Perl 5 Perl is not required, but if present it is used in some tests and the @code{mtrace} program, to build the @glibcadj{} manual. As of release -time @code{perl} version 5.40.0 is the newest verified to work to +time @code{perl} version 5.42.0 is the newest verified to work to build @theglibc{}. @item @@ -614,7 +616,7 @@ with any version of @code{sed}. As of release time, @code{sed} version Python 3.4 or later Python is required to build @theglibc{}. As of release time, Python -3.12.8 is the newest verified to work for building and testing +3.13.5 is the newest verified to work for building and testing @theglibc{}. @item PExpect 4.0 @@ -634,7 +636,7 @@ missing @code{abnf} module does not reduce the test coverage of the library itself. @item -GDB 7.8 or later with support for Python 2.7/3.4 or later +GDB 7.8 or later with support for Python 3.4 or later GDB itself needs to be configured with Python support in order to use the pretty printers. Notice that your system having Python available @@ -663,7 +665,7 @@ and if you change any of the message translation files you will need @item GNU @code{gettext} 0.10.36 or later -As of release time, GNU @code{gettext} version 0.23 is the newest +As of release time, GNU @code{gettext} version 0.23.2 is the newest version verified to work to build @theglibc{}. @end itemize diff --git a/manual/intro.texi b/manual/intro.texi index d956484..3a45a51 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -1061,8 +1061,7 @@ put the @samp{#include} directives immediately afterwards, following the feature test macro definition (@pxref{Feature Test Macros}). For more information about the use of header files and @samp{#include} -directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor -Manual}. +directives, @pxref{Header Files,,, cpp, The GNU C Preprocessor Manual}. @Theglibc{} provides several header files, each of which contains the type and macro definitions and variable and function declarations diff --git a/manual/libc.texinfo b/manual/libc.texinfo index ff0beb1..870ed7a 100644 --- a/manual/libc.texinfo +++ b/manual/libc.texinfo @@ -29,7 +29,7 @@ @comment %**end of header (This is for running Texinfo on a region.) @c Everything related to printed editions is disabled until we have -@c resolved how to keep them in sync with the master sources of the +@c resolved how to keep them in sync with the primary sources of the @c manual. @c sold 0.06/1.09, print run out 21may96 @c @set EDITION 0.13 diff --git a/manual/llio.texi b/manual/llio.texi index 7b5f77b..e7fd6ca 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -2271,8 +2271,8 @@ inefficient. A better solution is to use the @code{select} function. This blocks the program until input or output is ready on a specified set of file descriptors, or until a timer expires, whichever comes first. This -facility is declared in the header file @file{sys/types.h}. -@pindex sys/types.h +facility is declared in the header file @file{sys/select.h}. +@pindex sys/select.h In the case of a server socket (@pxref{Listening}), we say that ``input'' is available when there are pending connections that could be @@ -2286,13 +2286,13 @@ as @code{fd_set} objects. Here is the description of the data type and some macros for manipulating these objects. @deftp {Data Type} fd_set -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} The @code{fd_set} data type represents file descriptor sets for the @code{select} function. It is actually a bit array. @end deftp @deftypevr Macro int FD_SETSIZE -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} The value of this macro is the maximum number of file descriptors that a @code{fd_set} object can hold information about. On systems with a fixed maximum number, @code{FD_SETSIZE} is at least that number. On @@ -2304,14 +2304,14 @@ that descriptor into an @code{fd_set}. @end deftypevr @deftypefn Macro void FD_ZERO (fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro initializes the file descriptor set @var{set} to be the empty set. @end deftypefn @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} @c Setting a bit isn't necessarily atomic, so there's a potential race @c here if set is not used exclusively. @@ -2322,7 +2322,7 @@ evaluated more than once. @end deftypefn @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} @c Setting a bit isn't necessarily atomic, so there's a potential race @c here if set is not used exclusively. @@ -2333,7 +2333,7 @@ evaluated more than once. @end deftypefn @deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro returns a nonzero value (true) if @var{filedes} is a member of the file descriptor set @var{set}, and zero (false) otherwise. @@ -2345,7 +2345,7 @@ evaluated more than once. Next, here is the description of the @code{select} function itself. @deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout}) -@standards{BSD, sys/types.h} +@standards{POSIX.1, sys/select.h} @safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}} @c The select syscall is preferred, but pselect6 may be used instead, @c which requires converting timeout to a timespec and back. The @@ -2420,9 +2420,6 @@ or too large. @end table @end deftypefun -@strong{Portability Note:} The @code{select} function is a BSD Unix -feature. - Here is an example showing how you can use @code{select} to establish a timeout period for reading from a file descriptor. The @code{input_timeout} function blocks the calling process until input is available on the diff --git a/manual/maint.texi b/manual/maint.texi index b6ee5b6..58479ec 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 @@ -725,8 +725,8 @@ just @w{@samp{--with-@var{package}}} (no argument), then it sets @item configure.ac This file is an Autoconf input fragment to be processed into the file -@file{configure} in this subdirectory. @xref{Introduction,,, -autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, +@file{configure} in this subdirectory. @xref{Introduction,,, autoconf, +Autoconf: Generating Automatic Configuration Scripts}, for a description of Autoconf. You should write either @file{configure} or @file{configure.ac}, but not both. The first line of @file{configure.ac} should invoke the @code{m4} macro diff --git a/manual/math.texi b/manual/math.texi index adbe271..fbabf37 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -803,6 +803,22 @@ The @code{pown} functions are from TS 18661-4:2015 (which used @code{long long int} in C23). @end deftypefun +@deftypefun double compoundn (double @var{x}, long long int @var{power}) +@deftypefunx float compoundnf (float @var{x}, long long int @var{power}) +@deftypefunx {long double} compoundnl (long double @var{x}, long long int @var{power}) +@deftypefunx _FloatN compoundnfN (_Float@var{N} @var{x}, long long int @var{power}) +@deftypefunx _FloatNx compoundnfNx (_Float@var{N}x @var{x}, long long int @var{power}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These return @code{1 + @var{x}} raised to @var{power} (an integer). +If @var{x} is less than @minus{}1, @code{compoundn} signals a domain +error. + +The @code{compoundn} functions are from TS 18661-4:2015 (which used +@code{intmax_t} as the type of @var{power}; the type changed to +@code{long long int} in C23). +@end deftypefun + @cindex square root function @deftypefun double sqrt (double @var{x}) @deftypefunx float sqrtf (float @var{x}) @@ -867,6 +883,22 @@ instead of the direct formula is wise, since the error is much smaller. See also the function @code{cabs} in @ref{Absolute Value}. @end deftypefun +@deftypefun double rootn (double @var{x}, long long int @var{n}) +@deftypefunx float rootnf (float @var{x}, long long int @var{n}) +@deftypefunx {long double} rootnl (long double @var{x}, long long int @var{n}) +@deftypefunx _FloatN rootnfN (_Float@var{N} @var{x}, long long int @var{n}) +@deftypefunx _FloatNx rootnfNx (_Float@var{N}x @var{x}, long long int @var{n}) +@standards{TS 18661-4:2015, math.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +These return the @var{n}th root of @var{x}. If @var{n} is zero, or if +@var{x} is negative and @var{n} is even, @code{rootn} signals a domain +error. + +The @code{rootn} functions are from TS 18661-4:2015 (which used +@code{intmax_t} as the type of @var{n}; the type changed to +@code{long long int} in C23). +@end deftypefun + @deftypefun double expm1 (double @var{x}) @deftypefunx float expm1f (float @var{x}) @deftypefunx {long double} expm1l (long double @var{x}) diff --git a/manual/memory.texi b/manual/memory.texi index 9a29c7d..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/startup.texi b/manual/startup.texi index 6f29ddd..c444750 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -219,8 +219,8 @@ argument which itself is a comma separated list of options. To ease the programming of code like this the function @code{getsubopt} is available. -@deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep}) -@standards{???, stdlib.h} +@deftypefun int getsubopt (char **restrict @var{optionp}, char *const *restrict @var{tokens}, char **restrict @var{valuep}) +@standards{POSIX, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c getsubopt ok @c strchrnul dup ok diff --git a/manual/stdio.texi b/manual/stdio.texi index 29ed720..16d4594 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -3518,8 +3518,8 @@ If you are trying to read input that doesn't match a single, fixed pattern, you may be better off using a tool such as Flex to generate a lexical scanner, or Bison to generate a parser, rather than using @code{scanf}. For more information about these tools, see @ref{Top, , , -flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , , -bison.info, The Bison Reference Manual}. +flex, Flex: The Lexical Scanner Generator}, and @ref{Top, , , bison, The +Bison Reference Manual}. @node Input Conversion Syntax @subsection Input Conversion Syntax diff --git a/manual/terminal.texi b/manual/terminal.texi index b437cb5..8f4bb84 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -13,6 +13,7 @@ Most of the functions in this chapter operate on file descriptors. descriptor is and how to open a file descriptor for a terminal device. @menu +* Terminal Device Model:: The fundamental concepts of a terminal device * Is It a Terminal:: How to determine if a file is a terminal device, and what its name is. * I/O Queues:: About flow control and typeahead. @@ -28,6 +29,83 @@ descriptor is and how to open a file descriptor for a terminal device. * Pseudo-Terminals:: How to open a pseudo-terminal. @end menu +@node Terminal Device Model +@section Terminal Device Model +@cindex terminal model + +A @dfn{terminal device}, abbreviated @code{tty} (for @dfn{teletype}), is +a character device which implements a set of functionality appropriate +for communications devices, and which can host an interactive login +session. Conceptually, a terminal device implements an RS232 +asynchronous serial interface, but the actual hardware implementation +may be entirely different, or it may be entirely virtual, notably +@pxref{Pseudo-Terminals}. + +For a true conventional asynchronous serial port, such as RS232/V.24, +RS422/V.11, RS423, or RS485, the functionality is generally as +described, whereas for other devices, the meaning of serial port +specific functionality such as modem control signals, BREAK, and line +speed is device specific. + +The rest of this section is described in terms of a physical RS232 +interface. + +The RS232 specification assumes the host (Data Terminal Equipment, DTE) +connects to a modem (Data Communications Equipment, DCE), regardless of +if a physical modem is present or not. + +In addition to the serial data, the DTE provides a set of control +signals to the DCE, and the DCE a set of status signals to the DTE. The +full RS232 and V.24 specifications provide a large number of signals, +but the ones that are typically implemented in contemporary hardware and +are relevant to the terminal device interface are: + +@table @asis +@item DTR - Data Terminal Ready (control) + +If asserted (true), the DTE is ready to accept/continue an incoming +communications session. If deasserted (false), this is a +@dfn{modem disconnect request} to the DCE. The DCE may, but is not +required to, trigger a modem disconnect in response. +@cindex modem disconnect request + +@item RTS - Request To Send (control) + +This signal is also referred to as Ready To Receive (RTR). + +If asserted, the DTE is ready to accept data. If deasserted, the DCE is +requested to hold data temporarily without disconnecting. This is known +as hardware or RTS/CTS @dfn{flow control} and can be handled +automatically if the appropriate terminal mode flags are set. + +@item DSR - Data Set Ready (status) + +If asserted, the DCE is ready to communicate, but may or may not have a +connection to a remote peer. + +@item DCD - Data Carrier Detect (status) + +If asserted, the DCE has a connection to the remote peer. If +deasserted, this is a @dfn{modem disconnect} signal to the DTE. A modem +disconnect may be triggered in response to the DTR control signal being +deasserted, or it may be caused by an external event. +@cindex modem disconnect + +@item CTS - Clear To Send (status) + +If asserted, the DCE is ready to accept data. If deasserted, the DTE is +requested to hold data temporarily but should not interpret it as a +disconnect. This is the DCE to DTE part of RTS/CTS flow +control. + +@item RI - Ring Indicator (status) + +If asserted, this indicates that a remote peer is requesting to connect +(``the phone is ringing''). Depending on how the DCE is configured, the +DTE may need to assert the DTR control signal before the DCE will accept +the incoming connection. +@end table + @node Is It a Terminal @section Identifying Terminals @cindex terminal identification @@ -685,8 +763,10 @@ clear the condition. @deftypevr Macro tcflag_t HUPCL @standards{POSIX.1, termios.h} -If this bit is set, a modem disconnect is generated when all processes -that have the terminal device open have either closed the file or exited. +If this bit is set, a modem disconnect request is generated when all +processes that have the terminal device open have either closed the file +or exited. +@cindex modem disconnect request @end deftypevr @deftypevr Macro tcflag_t CREAD @@ -771,11 +851,11 @@ If this bit is set, it says to ignore the control modes and line speed values entirely. This is only meaningful in a call to @code{tcsetattr}. The @code{c_cflag} member and the line speed values returned by -@code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the -call. @code{CIGNORE} is useful if you want to set all the software -modes in the other members, but leave the hardware details in -@code{c_cflag} unchanged. (This is how the @code{TCSASOFT} flag to -@code{tcsettattr} works.) +@code{cfgetispeed}, @code{cfgetospeed}, @code{cfgetibaud} and +@code{cfsetibaud} will be unaffected by the call. @code{CIGNORE} is +useful if you want to set all the software modes in the other members, +but leave the hardware details in @code{c_cflag} unchanged. (This is +how the @code{TCSASOFT} flag to @code{tcsetattr} works.) This bit is never set in the structure filled in by @code{tcgetattr}. @end deftypevr @@ -965,106 +1045,82 @@ bit remains set until reprinting is finished. @xref{Editing Characters}. The terminal line speed tells the computer how fast to read and write data on the terminal. -If the terminal is connected to a real serial line, the terminal speed -you specify actually controls the line---if it doesn't match the -terminal's own idea of the speed, communication does not work. Real -serial ports accept only certain standard speeds. Also, particular -hardware may not support even all the standard speeds. Specifying a -speed of zero hangs up a dialup connection and turns off modem control -signals. - -If the terminal is not a real serial line (for example, if it is a -network connection), then the line speed won't really affect data -transmission speed, but some programs will use it to determine the -amount of padding needed. It's best to specify a line speed value that -matches the actual speed of the actual terminal, but you can safely -experiment with different values to vary the amount of padding. +For standard asynchronous serial lines employing binary NRZ encoding +such as RS232, RS422, RS423, or RS485, the terminal speed will equal the +physical layer baud rate including asynchronous framing and parity bits. +This needs to match the communication speed expected by the peer device, +or communication will not work. Which particular speeds are supported +by any particular interface is hardware specific. + +For other types of devices the meaning of the line speed is +device-specific and may not even affect the actual data transmission +speed at all (for example, if it is a pseudo-terminal or network +connection), but some programs will use it to determine the amount of +padding needed. It's best to specify a line speed value that matches +the actual speed of the actual terminal, but you can safely experiment +with different values to vary the amount of padding. + +As the terminal interface models an RS232 serial interface +(@pxref{Terminal Device Model}), the term ``baud rate'' is frequently +used as a direct alias for ``line speed''; this convention is followed +in the following descriptions. There are actually two line speeds for each terminal, one for input and one for output. You can set them independently, but most often -terminals use the same speed for both directions. +terminals use the same speed for both directions. If the hardware does +not support different speeds for each direction, the output speed will +be used for both input and output. -The speed values are stored in the @code{struct termios} structure, but -don't try to access them in the @code{struct termios} structure -directly. Instead, you should use the following functions to read and -store them: +Specifying an output speed of zero generates a modem disconnect request. +For the @code{speed_t} interface, this is the constant @code{B0} which +may or may not have the numeric value @math{0}. -@deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Direct access to a single termios field, except on Linux, where -@c multiple accesses may take place. No worries either way, callers -@c must ensure mutual exclusion on such non-opaque types. -This function returns the output line speed stored in the structure -@code{*@var{termios-p}}. -@end deftypefun - -@deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function returns the input line speed stored in the structure -@code{*@var{termios-p}}. -@end deftypefun - -@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function stores @var{speed} in @code{*@var{termios-p}} as the output -speed. The normal return value is @math{0}; a value of @math{-1} -indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} -returns @math{-1}. -@end deftypefun +Specifying an input speed value of zero sets the input speed to equal +the output speed. This is the numeric constant @math{0} (not +necessarily the same as @code{B0}) for both the @code{speed_t} and +@code{baud_t} interfaces. This use is deprecated. -@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed}) -@standards{POSIX.1, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function stores @var{speed} in @code{*@var{termios-p}} as the input -speed. The normal return value is @math{0}; a value of @math{-1} -indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} -returns @math{-1}. -@end deftypefun - -@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed}) -@standards{BSD, termios.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c There's no guarantee that the two calls are atomic, but since this is -@c not an opaque type, callers ought to ensure mutual exclusion to the -@c termios object. - -@c cfsetspeed ok -@c cfsetispeed ok -@c cfsetospeed ok -This function stores @var{speed} in @code{*@var{termios-p}} as both the -input and output speeds. The normal return value is @math{0}; a value -of @math{-1} indicates an error. If @var{speed} is not a speed, -@code{cfsetspeed} returns @math{-1}. This function is an extension in -4.4 BSD. -@end deftypefun +The line speed values are stored in the @code{struct termios} structure, but +don't try to access them in the @code{struct termios} structure +directly. Instead, you should use the functions defined by the +interfaces below to access them. + +The line speed setting functions report errors only when attempting to +set line rate values that the system simply cannot handle. If you +specify a line speed value that is plausible for the system, then the +functions will succeed. However, they do not check that a particular +hardware device can actually support the specified value---in fact, they +don't know which device you plan to set the line speed for until +@code{tcsetattr} is called. If you use @code{tcsetattr} to set the +speed of a particular device to a value that it cannot handle, either +@code{tcsetattr} returns @math{-1} and sets @code{errno} to +@code{EINVAL}, or the value is adjusted to the closest supported value, +depending on the policy of the kernel driver. In the latter case, a +subsequent call to @code{tcgetattr} may or may not reflect this +adjustment. + +@Theglibc{} supports two interoperable interfaces for setting the line +speed: the POSIX.1 @code{speed_t} interface, which requires the use of a +set of enumerated constants, and the @code{baud_t} interface, a GNU +extension, which is guaranteed to use plain numeric values. + +@subsubsection The @code{speed_t} interface @deftp {Data Type} speed_t @standards{POSIX.1, termios.h} The @code{speed_t} type is an unsigned integer data type used to represent line speeds. -@end deftp -The functions @code{cfsetospeed} and @code{cfsetispeed} report errors -only for speed values that the system simply cannot handle. If you -specify a speed value that is basically acceptable, then those functions -will succeed. But they do not check that a particular hardware device -can actually support the specified speeds---in fact, they don't know -which device you plan to set the speed for. If you use @code{tcsetattr} -to set the speed of a particular device to a value that it cannot -handle, @code{tcsetattr} returns @math{-1}. - -@strong{Portability note:} In @theglibc{}, the functions above -accept speeds measured in bits per second as input, and return speed -values measured in bits per second. Other libraries require speeds to -be indicated by special codes. For POSIX.1 portability, you must use +@strong{Portability note:} In the current version of @theglibc{}, the +@code{speed_t} type is numerically indentical to the line speed rate. +Other libraries and older versions of @theglibc{} may require speeds to +be indicated by enumerated constants, which may not be numerically +identical to the requested line speed. For portability, you must use one of the following symbols to represent the speed; their precise numeric values are system-dependent, but each name has a fixed meaning: @code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on. -There is no portable way to represent any speed but these, but these are -the only speeds that typical serial lines can support. +There is no portable way to represent any speed but these. +@end deftp @comment termios.h @comment POSIX.1 @@ -1114,23 +1170,92 @@ the only speeds that typical serial lines can support. @comment termios.h @comment POSIX.1 @vindex B38400 +@smallexample +B0 B50 B75 B110 B134 B150 B200 B300 B600 B1200 +B1800 B2400 B4800 B9600 B19200 B38400 +@end smallexample + +@Theglibc{} defines these additional constants: + +@comment termios.h +@comment GNU +@vindex B7200 +@comment termios.h +@comment GNU +@vindex B14400 +@comment termios.h +@comment GNU +@vindex B28800 +@comment termios.h +@comment GNU +@vindex B33600 @comment termios.h @comment GNU @vindex B57600 @comment termios.h @comment GNU +@vindex B76800 +@comment termios.h +@comment GNU @vindex B115200 @comment termios.h @comment GNU +@vindex B153600 +@comment termios.h +@comment GNU @vindex B230400 @comment termios.h @comment GNU +@vindex B307200 +@comment termios.h +@comment GNU @vindex B460800 +@comment termios.h +@comment GNU +@vindex B500000 +@comment termios.h +@comment GNU +@vindex B576000 +@comment termios.h +@comment GNU +@vindex B614400 +@comment termios.h +@comment GNU +@vindex B921600 +@comment termios.h +@comment GNU +@vindex B1000000 +@comment termios.h +@comment GNU +@vindex B1152000 +@comment termios.h +@comment GNU +@vindex B1500000 +@comment termios.h +@comment GNU +@vindex B2000000 +@comment termios.h +@comment GNU +@vindex B2500000 +@comment termios.h +@comment GNU +@vindex B3000000 +@comment termios.h +@comment GNU +@vindex B3500000 +@comment termios.h +@comment GNU +@vindex B4000000 +@comment termios.h +@comment GNU +@vindex B5000000 +@comment termios.h +@comment GNU +@vindex B10000000 @smallexample -B0 B50 B75 B110 B134 B150 B200 -B300 B600 B1200 B1800 B2400 B4800 -B9600 B19200 B38400 B57600 B115200 -B230400 B460800 +B7200 B14400 B28800 B33600 B57600 B76800 B115200 B153600 B230400 B307200 +B460800 B500000 B576000 B614400 B921600 B1000000 B1152000 B1500000 +B2000000 B2500000 B3000000 B3500000 B4000000 B5000000 B10000000 @end smallexample @vindex EXTA @@ -1139,6 +1264,172 @@ BSD defines two additional speed symbols as aliases: @code{EXTA} is an alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}. These aliases are obsolete. +@deftypevr Macro speed_t SPEED_MAX +@standards{GNU, termios.h} + +@Theglibc{} defines the constant @code{SPEED_MAX} for the largest valid +value of type @code{speed_t}. This value may be smaller than the +underlying C type can store. + +For compatiblity with some other platforms the alias @code{__MAX_BAUD} +is defined for this constant. +@end deftypevr + +@deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field. However, this may not be +@c true on other implementations; callers must ensure mutual exclusion +@c on such non-opaque types. +This function returns the output line speed stored in the structure +@code{*@var{termios-p}}. +@end deftypefun + +@deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function returns the input line speed stored in the structure +@code{*@var{termios-p}}. +@end deftypefun + +@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field, except on Linux, where two +@c fields are accessed, one of which (c_cflag) is read-modify-write. No +@c worries either way, callers must ensure mutual exclusion on such +@c non-opaque types. +This function stores @var{speed} in @code{*@var{termios-p}} as the +output line speed. If @var{speed} is @code{B0}, generates a modem +disconnect request. + +If @var{speed} is neither a plausible line speed nor @code{B0}, +@code{cfsetospeed} returns @math{-1} and sets @code{errno} to +@code{EINVAL}. +@end deftypefun + +@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{POSIX.1, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function stores @var{speed} in @code{*@var{termios-p}} as the input +speed. If @var{speed} is @math{0}, the input speed is set to equal the +output speed; note that POSIX.1 specifies this as the numeric value +@math{0} which is not required to equal the constant @code{B0}. + +If @var{speed} is not a plausible line speed or @math{0}, +@code{cfsetispeed} returns @math{-1} and sets @code{errno} to +@code{EINVAL}. + +@strong{Portability note:} POSIX.1-2024 has deprecated setting of the +input speed to @math{0} to set the input line speed to equal the output +line speed. After calling @code{tcsetattr} followed by +@code{tcgetattr}, @code{cfgetispeed} may report the input line speed +either as @math{0} or the same as @code{cfgetospeed}. +@end deftypefun + +@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{BSD, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c There's no guarantee that the two calls are atomic, but since this is +@c not an opaque type, callers ought to ensure mutual exclusion to the +@c termios object. + +@c cfsetspeed ok +@c cfsetispeed ok +@c cfsetospeed ok +This function stores @var{speed} in @code{*@var{termios-p}} as both the +input and output speeds. + +If @var{baud} is not a plausible line speed, @code{cfsetbaud} returns +@math{-1} and sets @code{errno} to @code{EINVAL}. + +This function is an extension which originated in 4.4 BSD. +@end deftypefun + +@subsubsection The @code{baud_t} interface + +@deftp {Data Type} baud_t +@standards{GNU, termios.h} +The @code{baud_t} type is a numeric data type used to represent line +baud rates. It will always represent the actual numeric value +corresponding to the line speed, unlike @code{speed_t}. In the current +version of @theglibc{} this is the same type as @code{speed_t}, but this +may not be the case in future versions or on other implementations; it +is specifically not guaranteed to be an integer type. +@end deftp + +@deftypevr Macro baud_t BAUD_MAX +@standards{GNU, termios.h} +The constant @code{BAUD_MAX} is defined to the maximum valid value of +type @code{baud_t}. This value may be smaller than the underlying C +type can store. +@end deftypevr + +@deftypefun baud_t cfgetobaud (const struct termios *@var{termios-p}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field. However, this may not be +@c true on other implementations; callers must ensure mutual exclusion +@c on such non-opaque types. +This function returns the output line speed stored in the structure +@code{*@var{termios-p}} as a numeric value. +@end deftypefun + +@deftypefun baud_t cfgetibaud (const struct termios *@var{termios-p}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function returns the input line speed stored in the structure +@code{*@var{termios-p}} as a numeric value. +@end deftypefun + +@deftypefun int cfsetobaud (struct termios *@var{termios-p}, baud_t @var{baud}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct access to a single termios field, except on Linux, where two +@c fields are accessed, one of which (c_cflag) is read-modify-write. No +@c worries either way, callers must ensure mutual exclusion on such +@c non-opaque types. +This function stores @var{baud} in @code{*@var{termios-p}} as the output +line speed. If @var{baud} is @math{0}, generates a modem disconnect. + +If @var{speed} is not a plausible line speed, @code{cfsetspeed} returns +@math{-1} and sets @code{errno} to @code{EINVAL}. +@end deftypefun + +@deftypefun int cfsetibaud (struct termios *@var{termios-p}, baud_t @var{baud}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This function stores @var{baud} in @code{*@var{termios-p}} as the input +line speed. + +To simplify conversions from the @code{speed_t} interface, setting the +input line speed to @math{0} is interpreted as setting the input line +speed equal to the output line speed. The caveats described under +@code{cfsetispeed} apply equally to @code{cfsetibaud}. As for +@code{cfsetispeed}, this usage is deprecated. + +If @var{baud} is not a plausible line speed or @math{0}, +@code{cfsetibaud} returns @math{-1} and sets @code{errno} to +@code{EINVAL}. +@end deftypefun + +@deftypefun int cfsetbaud (struct termios *@var{termios-p}, baud_t @var{baud}) +@standards{GNU, termios.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c There's no guarantee that the two calls are atomic, but since this is +@c not an opaque type, callers should ensure mutual exclusion to the +@c termios object. + +@c cfsetbaud ok +@c cfsetibaud ok +@c cfsetobaud ok +This function stores @var{baud} in @code{*@var{termios-p}} as both the +input and output line speeds. + +If @var{baud} is not a plausible line speed, @code{cfsetbaud} returns +@math{-1} and sets @code{errno} to @code{EINVAL}. +@end deftypefun + @node Special Characters @subsection Special Characters diff --git a/manual/threads.texi b/manual/threads.texi index 67955e1..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 6b89b85..d003ddb 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -529,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} @@ -3151,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 @@ -3165,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 |