diff options
Diffstat (limited to 'man3/pthread_attr_init.3')
| -rw-r--r-- | man3/pthread_attr_init.3 | 314 |
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) |