Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 314 insertions, 0 deletions

diff --git a/man3/pthread_attr_init.3 b/man3/pthread_attr_init.3
new file mode 100644
index 0000000..8792ab4
--- /dev/null
+++ b/man3/pthread_attr_init.3
@@ -0,0 +1,314 @@
+'\" t
+.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_attr_init 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+pthread_attr_init, pthread_attr_destroy \- initialize and destroy
+thread attributes object
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.PP
+.BI "int pthread_attr_init(pthread_attr_t *" attr );
+.BI "int pthread_attr_destroy(pthread_attr_t *" attr );
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_attr_init ()
+function initializes the thread attributes object pointed to by
+.I attr
+with default attribute values.
+After this call, individual attributes of the object can be set
+using various related functions (listed under SEE ALSO),
+and then the object can be used in one or more
+.BR pthread_create (3)
+calls that create threads.
+.PP
+Calling
+.BR pthread_attr_init ()
+on a thread attributes object that has already been initialized
+results in undefined behavior.
+.PP
+When a thread attributes object is no longer required,
+it should be destroyed using the
+.BR pthread_attr_destroy ()
+function.
+Destroying a thread attributes object has no effect
+on threads that were created using that object.
+.PP
+Once a thread attributes object has been destroyed,
+it can be reinitialized using
+.BR pthread_attr_init ().
+Any other use of a destroyed thread attributes object
+has undefined results.
+.SH RETURN VALUE
+On success, these functions return 0;
+on error, they return a nonzero error number.
+.SH ERRORS
+POSIX.1 documents an
+.B ENOMEM
+error for
+.BR pthread_attr_init ();
+on Linux these functions always succeed
+(but portable and future-proof applications should nevertheless
+handle a possible error return).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR pthread_attr_init (),
+.BR pthread_attr_destroy ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH NOTES
+The
+.I pthread_attr_t
+type should be treated as opaque:
+any access to the object other than via pthreads functions
+is nonportable and produces undefined results.
+.SH EXAMPLES
+The program below optionally makes use of
+.BR pthread_attr_init ()
+and various related functions to initialize a thread attributes
+object that is used to create a single thread.
+Once created, the thread uses the
+.BR pthread_getattr_np (3)
+function (a nonstandard GNU extension) to retrieve the thread's
+attributes, and then displays those attributes.
+.PP
+If the program is run with no command-line argument,
+then it passes NULL as the
+.I attr
+argument of
+.BR pthread_create (3),
+so that the thread is created with default attributes.
+Running the program on Linux/x86-32 with the NPTL threading implementation,
+we see the following:
+.PP
+.in +4n
+.EX
+.\" Results from glibc 2.8, SUSE 11.0; Oct 2008
+.RB "$" " ulimit \-s" "       # No stack limit ==> default stack size is 2 MB"
+unlimited
+.RB "$" " ./a.out"
+Thread attributes:
+        Detach state        = PTHREAD_CREATE_JOINABLE
+        Scope               = PTHREAD_SCOPE_SYSTEM
+        Inherit scheduler   = PTHREAD_INHERIT_SCHED
+        Scheduling policy   = SCHED_OTHER
+        Scheduling priority = 0
+        Guard size          = 4096 bytes
+        Stack address       = 0x40196000
+        Stack size          = 0x201000 bytes
+.EE
+.in
+.PP
+When we supply a stack size as a command-line argument,
+the program initializes a thread attributes object,
+sets various attributes in that object,
+and passes a pointer to the object in the call to
+.BR pthread_create (3).
+Running the program on Linux/x86-32 with the NPTL threading implementation,
+we see the following:
+.PP
+.in +4n
+.EX
+.\" Results from glibc 2.8, SUSE 11.0; Oct 2008
+.RB "$" " ./a.out 0x3000000"
+posix_memalign() allocated at 0x40197000
+Thread attributes:
+        Detach state        = PTHREAD_CREATE_DETACHED
+        Scope               = PTHREAD_SCOPE_SYSTEM
+        Inherit scheduler   = PTHREAD_EXPLICIT_SCHED
+        Scheduling policy   = SCHED_OTHER
+        Scheduling priority = 0
+        Guard size          = 0 bytes
+        Stack address       = 0x40197000
+        Stack size          = 0x3000000 bytes
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (pthread_attr_init.c)
+.EX
+#define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
+#include <err.h>
+#include <errno.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+static void
+display_pthread_attr(pthread_attr_t *attr, char *prefix)
+{
+    int s, i;
+    size_t v;
+    void *stkaddr;
+    struct sched_param sp;
+\&
+    s = pthread_attr_getdetachstate(attr, &i);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate");
+    printf("%sDetach state        = %s\en", prefix,
+           (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
+           (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
+           "???");
+\&
+    s = pthread_attr_getscope(attr, &i);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_attr_getscope");
+    printf("%sScope               = %s\en", prefix,
+           (i == PTHREAD_SCOPE_SYSTEM)  ? "PTHREAD_SCOPE_SYSTEM" :
+           (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
+           "???");
+\&
+    s = pthread_attr_getinheritsched(attr, &i);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched");
+    printf("%sInherit scheduler   = %s\en", prefix,
+           (i == PTHREAD_INHERIT_SCHED)  ? "PTHREAD_INHERIT_SCHED" :
+           (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
+           "???");
+\&
+    s = pthread_attr_getschedpolicy(attr, &i);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy");
+    printf("%sScheduling policy   = %s\en", prefix,
+           (i == SCHED_OTHER) ? "SCHED_OTHER" :
+           (i == SCHED_FIFO)  ? "SCHED_FIFO" :
+           (i == SCHED_RR)    ? "SCHED_RR" :
+           "???");
+\&
+    s = pthread_attr_getschedparam(attr, &sp);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_attr_getschedparam");
+    printf("%sScheduling priority = %d\en", prefix, sp.sched_priority);
+\&
+    s = pthread_attr_getguardsize(attr, &v);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_attr_getguardsize");
+    printf("%sGuard size          = %zu bytes\en", prefix, v);
+\&
+    s = pthread_attr_getstack(attr, &stkaddr, &v);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_attr_getstack");
+    printf("%sStack address       = %p\en", prefix, stkaddr);
+    printf("%sStack size          = %#zx bytes\en", prefix, v);
+}
+\&
+static void *
+thread_start(void *arg)
+{
+    int s;
+    pthread_attr_t gattr;
+\&
+    /* pthread_getattr_np() is a non\-standard GNU extension that
+       retrieves the attributes of the thread specified in its
+       first argument. */
+\&
+    s = pthread_getattr_np(pthread_self(), &gattr);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_getattr_np");
+\&
+    printf("Thread attributes:\en");
+    display_pthread_attr(&gattr, "\et");
+\&
+    exit(EXIT_SUCCESS);         /* Terminate all threads */
+}
+\&
+int
+main(int argc, char *argv[])
+{
+    pthread_t thr;
+    pthread_attr_t attr;
+    pthread_attr_t *attrp;      /* NULL or &attr */
+    int s;
+\&
+    attrp = NULL;
+\&
+    /* If a command\-line argument was supplied, use it to set the
+       stack\-size attribute and set a few other thread attributes,
+       and set attrp pointing to thread attributes object. */
+\&
+    if (argc > 1) {
+        size_t stack_size;
+        void *sp;
+\&
+        attrp = &attr;
+\&
+        s = pthread_attr_init(&attr);
+        if (s != 0)
+            errc(EXIT_FAILURE, s, "pthread_attr_init");
+\&
+        s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
+        if (s != 0)
+            errc(EXIT_FAILURE, s, "pthread_attr_setdetachstate");
+\&
+        s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
+        if (s != 0)
+            errc(EXIT_FAILURE, s, "pthread_attr_setinheritsched");
+\&
+        stack_size = strtoul(argv[1], NULL, 0);
+\&
+        s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
+        if (s != 0)
+            errc(EXIT_FAILURE, s, "posix_memalign");
+\&
+        printf("posix_memalign() allocated at %p\en", sp);
+\&
+        s = pthread_attr_setstack(&attr, sp, stack_size);
+        if (s != 0)
+            errc(EXIT_FAILURE, s, "pthread_attr_setstack");
+    }
+\&
+    s = pthread_create(&thr, attrp, &thread_start, NULL);
+    if (s != 0)
+        errc(EXIT_FAILURE, s, "pthread_create");
+\&
+    if (attrp != NULL) {
+        s = pthread_attr_destroy(attrp);
+        if (s != 0)
+            errc(EXIT_FAILURE, s, "pthread_attr_destroy");
+    }
+\&
+    pause();    /* Terminates when other thread calls exit() */
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.ad l
+.nh
+.BR pthread_attr_setaffinity_np (3),
+.BR pthread_attr_setdetachstate (3),
+.BR pthread_attr_setguardsize (3),
+.BR pthread_attr_setinheritsched (3),
+.BR pthread_attr_setschedparam (3),
+.BR pthread_attr_setschedpolicy (3),
+.BR pthread_attr_setscope (3),
+.BR pthread_attr_setsigmask_np (3),
+.BR pthread_attr_setstack (3),
+.BR pthread_attr_setstackaddr (3),
+.BR pthread_attr_setstacksize (3),
+.BR pthread_create (3),
+.BR pthread_getattr_np (3),
+.BR pthread_setattr_default_np (3),
+.BR pthreads (7)