diff --git a/manual/llio.texi b/manual/llio.texi index b6bc7f2210..7b5f77bb7b 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -1693,6 +1693,8 @@ existing map is unmapped. @c Which is which? @item MAP_ANONYMOUS @itemx MAP_ANON +@standards{POSIX.1-2024, sys/mman.h} +@standardsx{MAP_ANON, POSIX.1-2024, sys/mman.h} This flag tells the system to create an anonymous mapping, not connected to a file. @var{filedes} and @var{offset} are ignored, and the region is initialized with zeros. @@ -3639,11 +3641,14 @@ duplicate of @var{old}. @end deftypefun @deftypefun int dup3 (int @var{old}, int @var{new}, int @var{flags}) -@standards{Linux, unistd.h} +@standards{POSIX.1-2024, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is the same as @code{dup2} but creates the new descriptor as if it had been opened with flags @var{flags}. The only allowed flag is @code{O_CLOEXEC}. + +This function was originally a Linux extension, but was added in +POSIX.1-2024. @end deftypefun @deftypevr Macro int F_DUPFD diff --git a/manual/memory.texi b/manual/memory.texi index dc4621e2c5..9a29c7d133 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -842,8 +842,8 @@ is left undisturbed. @end deftypefun @deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size}) -@standards{BSD, malloc.h} -@standards{BSD, stdlib.h} +@standards{POSIX.1-2024, malloc.h} +@standards{POSIX.1-2024, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} The @code{reallocarray} function changes the size of the block whose address @@ -856,8 +856,8 @@ returning a null pointer, and leaving the original block unchanged. @code{reallocarray} should be used instead of @code{realloc} when the new size of the allocated block is the result of a multiplication that might overflow. -@strong{Portability Note:} This function is not part of any standard. It was -first introduced in OpenBSD 5.6. +This function was originally derived from OpenBSD 5.6, but was added in +POSIX.1-2024. @end deftypefun Like @code{malloc}, @code{realloc} and @code{reallocarray} may return a null diff --git a/manual/message.texi b/manual/message.texi index ef68693fd1..71b56e6a3a 100644 --- a/manual/message.texi +++ b/manual/message.texi @@ -18,11 +18,11 @@ in separate files which are loaded at runtime depending on the language selection of the user. @Theglibc{} provides two different sets of functions to support -message translation. The problem is that neither of the interfaces is -officially defined by the POSIX standard. The @code{catgets} family of -functions is defined in the X/Open standard but this is derived from -industry decisions and therefore not necessarily based on reasonable -decisions. +message translation. The @code{catgets} family of functions were +previously the only family defined in the X/Open standard but they were +derived from industry decisions and therefore not necessarily based on +reasonable decisions. However, the preferable @code{gettext} family of +functions was standardized in POSIX-1.2024. As mentioned above, the message catalog handling provides easy extendability by using external data files which contain the message @@ -830,7 +830,7 @@ not part of the C library they can be found in a separate library named @file{libintl.a} (or accordingly different for shared libraries). @deftypefun {char *} gettext (const char *@var{msgid}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcgettext. The @code{gettext} function searches the currently selected message @@ -878,7 +878,7 @@ currently selected default message catalog it must specify all ambiguous information. @deftypefun {char *} dgettext (const char *@var{domainname}, const char *@var{msgid}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcgettext. The @code{dgettext} function acts just like the @code{gettext} @@ -893,7 +893,7 @@ anachronism. The returned string must never be modified. @end deftypefun @deftypefun {char *} dcgettext (const char *@var{domainname}, const char *@var{msgid}, int @var{category}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c dcgettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem @c dcigettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem @@ -1112,7 +1112,7 @@ exactly one domain is active. This is controlled with the following function. @deftypefun {char *} textdomain (const char *@var{domainname}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c textdomain @asulock @ascuheap @aculock @acsmem @c libc_rwlock_wrlock @asulock @aculock @@ -1149,7 +1149,7 @@ really never should be used. @end deftypefun @deftypefun {char *} bindtextdomain (const char *@var{domainname}, const char *@var{dirname}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c bindtextdomain @ascuheap @acsmem @c set_binding_values @ascuheap @acsmem @@ -1271,7 +1271,7 @@ to be written in English, this solution nevertheless fulfills its purpose. @deftypefun {char *} ngettext (const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcngettext. The @code{ngettext} function is similar to the @code{gettext} function @@ -1295,7 +1295,7 @@ Please note that the numeric value @var{n} has to be passed to the @end deftypefun @deftypefun {char *} dngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcngettext. The @code{dngettext} is similar to the @code{dgettext} function in the @@ -1305,7 +1305,7 @@ parameters are handled in the same way @code{ngettext} handles them. @end deftypefun @deftypefun {char *} dcngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}, int @var{category}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcigettext. The @code{dcngettext} is similar to the @code{dcgettext} function in the @@ -1562,7 +1562,7 @@ independently of the current output character set. It is therefore recommended that all @var{msgid}s be US-ASCII strings. @deftypefun {char *} bind_textdomain_codeset (const char *@var{domainname}, const char *@var{codeset}) -@standards{GNU, libintl.h} +@standards{POSIX-1.2024, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c bind_textdomain_codeset @ascuheap @acsmem @c set_binding_values dup @ascuheap @acsmem diff --git a/manual/pattern.texi b/manual/pattern.texi index 250fa1e265..f2e83532f5 100644 --- a/manual/pattern.texi +++ b/manual/pattern.texi @@ -119,9 +119,12 @@ If this flag is set, either @samp{foo*} or @samp{foobar} as a pattern would match the string @samp{foobar/frobozz}. @item FNM_CASEFOLD -@standards{GNU, fnmatch.h} +@standards{POSIX.1-2024, fnmatch.h} Ignore case in comparing @var{string} to @var{pattern}. +This macro was originally a GNU extension, but was added in +POSIX.1-2024. + @item FNM_EXTMATCH @standards{GNU, fnmatch.h} @cindex Korn Shell diff --git a/manual/process.texi b/manual/process.texi index a8f37e55a3..609c78a101 100644 --- a/manual/process.texi +++ b/manual/process.texi @@ -338,7 +338,7 @@ signals and signal actions from the parent process.) @end itemize @deftypefun pid_t _Fork (void) -@standards{GNU, unistd.h} +@standards{POSIX.1-2024, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{_Fork} function is similar to @code{fork}, but it does not invoke any callbacks registered with @code{pthread_atfork}, nor does it reset @@ -347,8 +347,9 @@ new subprocess, only async-signal-safe functions may be called, such as @code{dup2} or @code{execve}. The @code{_Fork} function is an async-signal-safe replacement of @code{fork}. -It is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun pid_t vfork (void) @@ -835,10 +836,13 @@ signal number of the signal that terminated the child process. @end deftypefn @deftypefn Macro int WCOREDUMP (int @var{status}) -@standards{BSD, sys/wait.h} +@standards{POSIX.1-2024, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if the child process terminated and produced a core dump. + +This macro was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefn @deftypefn Macro int WIFSTOPPED (int @var{status}) diff --git a/manual/signal.texi b/manual/signal.texi index 842b4e49a2..7e21a93674 100644 --- a/manual/signal.texi +++ b/manual/signal.texi @@ -803,7 +803,7 @@ The default action is to terminate the process. @end deftypevr @deftypevr Macro int SIGWINCH -@standards{BSD, signal.h} +@standards{POSIX.1-2024, signal.h} Window size change. This is generated on some systems (including GNU) when the terminal driver's record of the number of rows and columns on the screen is changed. The default action is to ignore it. @@ -811,6 +811,9 @@ the screen is changed. The default action is to ignore it. If a program does full-screen display, it should handle @code{SIGWINCH}. When the signal arrives, it should fetch the new screen size and reformat its display accordingly. + +This macro was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypevr @deftypevr Macro int SIGINFO diff --git a/manual/startup.texi b/manual/startup.texi index 95b0ed8fc7..6f29ddd8cf 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -337,7 +337,7 @@ pointer. @end deftypefun @deftypefun {char *} secure_getenv (const char *@var{name}) -@standards{GNU, stdlib.h} +@standards{POSIX.1-2024, stdlib.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}} @c Calls getenv unless secure mode is enabled. This function is similar to @code{getenv}, but it returns a null @@ -346,7 +346,8 @@ program file has SUID or SGID bits set. General-purpose libraries should always prefer this function over @code{getenv} to avoid vulnerabilities if the library is referenced from a SUID/SGID program. -This function is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun diff --git a/manual/string.texi b/manual/string.texi index 0b667bd3fb..feba0b7ae3 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -1081,7 +1081,7 @@ issues. @xref{Concatenating Strings}. @end deftypefun @deftypefun size_t strlcpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX-1.2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the string @var{from} to the destination array @var{to}, limiting the result's size (including the null terminator) @@ -1114,21 +1114,23 @@ processing strings. Also, this function has a performance issue, as its time cost is proportional to the length of @var{from} even when @var{size} is small. -This function is derived from OpenBSD 2.4. +This function was originally derived from OpenBSD 2.4, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t wcslcpy (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is a variant of @code{strlcpy} for wide strings. The @var{size} argument counts the length of the destination buffer in wide characters (and not bytes). -This function is derived from BSD. +This function was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t strlcat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX-1.2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function appends the string @var{from} to the string @var{to}, limiting the result's total size (including the null @@ -1156,17 +1158,19 @@ As noted below, this function is generally a poor choice for processing strings. Also, this function has significant performance issues. @xref{Concatenating Strings}. -This function is derived from OpenBSD 2.4. +This function was originally derived from OpenBSD 2.4, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t wcslcat (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is a variant of @code{strlcat} for wide strings. The @var{size} argument counts the length of the destination buffer in wide characters (and not bytes). -This function is derived from BSD. +This function was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefun Because these functions can abruptly truncate strings or wide strings, @@ -2008,14 +2012,15 @@ strcasestr ("hello, World", "wo") @deftypefun {void *} memmem (const void *@var{haystack}, size_t @var{haystack-len},@*const void *@var{needle}, size_t @var{needle-len}) -@standards{GNU, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{strstr}, but @var{needle} and @var{haystack} are byte arrays rather than strings. @var{needle-len} is the length of @var{needle} and @var{haystack-len} is the length of @var{haystack}. -This function is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t strspn (const char *@var{string}, const char *@var{skipset}) diff --git a/manual/terminal.texi b/manual/terminal.texi index bdaee56053..b437cb5322 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -2107,7 +2107,7 @@ might be overwritten by subsequent calls to @code{ptsname}. @end deftypefun @deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) -@standards{GNU, stdlib.h} +@standards{POSIX.1-2024, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} @c ptsname_r @ascuheap/bsd @acsmem @acsfd @c /hurd @@ -2143,7 +2143,8 @@ The @code{ptsname_r} function is similar to the @code{ptsname} function except that it places its result into the user-specified buffer starting at @var{buf} with length @var{len}. -This function is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun Typical usage of these functions is illustrated by the following example: diff --git a/manual/threads.texi b/manual/threads.texi index 7b9c79636c..67955e10af 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -554,6 +554,8 @@ This section describes the @glibcadj{} POSIX Threads implementation. @menu * 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 * Non-POSIX Extensions:: Additional functions to extend @@ -617,6 +619,55 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread. @end deftypefun +@node Waiting with Explicit Clocks +@subsection Functions for Waiting According to a Specific Clock + +@Theglibc{} provides several waiting functions that expect an explicit +@code{clockid_t} argument. These functions were all adopted by +POSIX.1-2024. + +@comment pthread.h +@deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@standards{POSIX-1.2024, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c If exactly the same function with arguments is called from a signal +@c handler that interrupts between the mutex unlock and sleep then it +@c will unlock the mutex twice resulting in undefined behaviour. Keep +@c in mind that the unlock and sleep are only atomic with respect to other +@c threads (really a happens-after relationship for pthread_cond_broadcast +@c and pthread_cond_signal). +@c In the AC case we would cancel the thread and the mutex would remain +@c locked and we can't recover from that. +Behaves like @code{pthread_cond_timedwait} except the time @var{abstime} is +measured against the clock specified by @var{clockid} rather than the clock +specified or defaulted when @code{pthread_cond_init} was called. Currently, +@var{clockid} must be either @code{CLOCK_MONOTONIC} or +@code{CLOCK_REALTIME}. +@end deftypefun + +@comment pthread.h +@deftypefun int pthread_rwlock_clockrdlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@standards{POSIX-1.2024, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +Behaves like @code{pthread_rwlock_timedrdlock} except the time +@var{abstime} is measured against the clock specified by @var{clockid} +rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either +@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is +returned. +@end deftypefun + +@comment pthread.h +@deftypefun int pthread_rwlock_clockwrlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@standards{POSIX-1.2024, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +Behaves like @code{pthread_rwlock_timedwrlock} except the time +@var{abstime} is measured against the clock specified by @var{clockid} +rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either +@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is +returned. +@end deftypefun + + @node POSIX Semaphores @subsection POSIX Semaphores @@ -729,8 +780,7 @@ the standard. * Default Thread Attributes:: Setting default attributes for threads in a process. * Initial Thread Signal Mask:: Setting the initial mask of threads. -* Waiting with Explicit Clocks:: Functions for waiting with an - explicit clock specification. +* Joining Threads:: Wait for a thread to terminate. * Single-Threaded:: Detecting single-threaded execution. * Restartable Sequences:: Linux-specific restartable sequences integration. @@ -849,52 +899,11 @@ signal mask and use @code{pthread_sigmask} to apply it to the thread. If the signal mask was copied to a heap allocation, the copy should be freed. -@node Waiting with Explicit Clocks -@subsubsection Functions for Waiting According to a Specific Clock +@node Joining Threads +@subsubsection Wait for a thread to terminate -@Theglibc{} provides several waiting functions that expect an explicit -@code{clockid_t} argument. - -@comment pthread.h -@comment POSIX-proposed -@deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c If exactly the same function with arguments is called from a signal -@c handler that interrupts between the mutex unlock and sleep then it -@c will unlock the mutex twice resulting in undefined behaviour. Keep -@c in mind that the unlock and sleep are only atomic with respect to other -@c threads (really a happens-after relationship for pthread_cond_broadcast -@c and pthread_cond_signal). -@c In the AC case we would cancel the thread and the mutex would remain -@c locked and we can't recover from that. -Behaves like @code{pthread_cond_timedwait} except the time @var{abstime} is -measured against the clock specified by @var{clockid} rather than the clock -specified or defaulted when @code{pthread_cond_init} was called. Currently, -@var{clockid} must be either @code{CLOCK_MONOTONIC} or -@code{CLOCK_REALTIME}. -@end deftypefun - -@comment pthread.h -@comment POSIX-proposed -@deftypefun int pthread_rwlock_clockrdlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -Behaves like @code{pthread_rwlock_timedrdlock} except the time -@var{abstime} is measured against the clock specified by @var{clockid} -rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either -@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is -returned. -@end deftypefun - -@comment pthread.h -@comment POSIX-proposed -@deftypefun int pthread_rwlock_clockwrlock (pthread_rwlock_t *@var{rwlock}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -Behaves like @code{pthread_rwlock_timedwrlock} except the time -@var{abstime} is measured against the clock specified by @var{clockid} -rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either -@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is -returned. -@end deftypefun +@Theglibc{} provides several extensions to the @code{pthread_join} +function. @comment pthread.h @comment GNU extension