| .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
| .\" <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH PTHREAD_ATTR_INIT 3 2015-07-23 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| pthread_attr_init, pthread_attr_destroy \- initialize and destroy |
| thread attributes object |
| .SH SYNOPSIS |
| .nf |
| .B #include <pthread.h> |
| |
| .BI "int pthread_attr_init(pthread_attr_t *" attr ); |
| .BI "int pthread_attr_destroy(pthread_attr_t *" attr ); |
| .sp |
| Compile and link with \fI\-pthread\fP. |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR pthread_attr_init () |
| function initializes the thread attributes object pointed to by |
| .IR 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. |
| |
| Calling |
| .BR pthread_attr_init () |
| on a thread attributes object that has already been initialized |
| results in undefined behavior. |
| |
| 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. |
| |
| 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). |
| .ad l |
| .TS |
| allbox; |
| lbw22 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR pthread_attr_init (), |
| .BR pthread_attr_destroy () |
| T} Thread safety MT-Safe |
| .TE |
| .ad |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008. |
| .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 EXAMPLE |
| 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. |
| |
| 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: |
| |
| .in +4n |
| .nf |
| .\" Results from glibc 2.8, SUSE 11.0; Oct 2008 |
| .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2MB" |
| 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 |
| .fi |
| .in |
| |
| 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: |
| |
| .in +4n |
| .nf |
| .\" 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 |
| .fi |
| .in |
| .SS Program source |
| \& |
| .nf |
| #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ |
| #include <pthread.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| #include <errno.h> |
| |
| #define handle_error_en(en, msg) \\ |
| do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) |
| |
| 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) |
| handle_error_en(s, "pthread_attr_getdetachstate"); |
| printf("%sDetach state = %s\\n", prefix, |
| (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : |
| (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : |
| "???"); |
| |
| s = pthread_attr_getscope(attr, &i); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_getscope"); |
| printf("%sScope = %s\\n", prefix, |
| (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : |
| (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : |
| "???"); |
| |
| s = pthread_attr_getinheritsched(attr, &i); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_getinheritsched"); |
| printf("%sInherit scheduler = %s\\n", prefix, |
| (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : |
| (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : |
| "???"); |
| |
| s = pthread_attr_getschedpolicy(attr, &i); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_getschedpolicy"); |
| printf("%sScheduling policy = %s\\n", 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) |
| handle_error_en(s, "pthread_attr_getschedparam"); |
| printf("%sScheduling priority = %d\\n", prefix, sp.sched_priority); |
| |
| s = pthread_attr_getguardsize(attr, &v); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_getguardsize"); |
| printf("%sGuard size = %d bytes\\n", prefix, v); |
| |
| s = pthread_attr_getstack(attr, &stkaddr, &v); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_getstack"); |
| printf("%sStack address = %p\\n", prefix, stkaddr); |
| printf("%sStack size = 0x%zx bytes\\n", 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) |
| handle_error_en(s, "pthread_getattr_np"); |
| |
| printf("Thread attributes:\\n"); |
| display_pthread_attr(&gattr, "\\t"); |
| |
| 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) { |
| int stack_size; |
| void *sp; |
| |
| attrp = &attr; |
| |
| s = pthread_attr_init(&attr); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_init"); |
| |
| s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_setdetachstate"); |
| |
| s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_setinheritsched"); |
| |
| stack_size = strtoul(argv[1], NULL, 0); |
| |
| s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); |
| if (s != 0) |
| handle_error_en(s, "posix_memalign"); |
| |
| printf("posix_memalign() allocated at %p\\n", sp); |
| |
| s = pthread_attr_setstack(&attr, sp, stack_size); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_setstack"); |
| } |
| |
| s = pthread_create(&thr, attrp, &thread_start, NULL); |
| if (s != 0) |
| handle_error_en(s, "pthread_create"); |
| |
| if (attrp != NULL) { |
| s = pthread_attr_destroy(attrp); |
| if (s != 0) |
| handle_error_en(s, "pthread_attr_destroy"); |
| } |
| |
| pause(); /* Terminates when other thread calls exit() */ |
| } |
| .fi |
| .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_setstack (3), |
| .BR pthread_attr_setstackaddr (3), |
| .BR pthread_attr_setstacksize (3), |
| .BR pthread_create (3), |
| .BR pthread_getattr_np (3), |
| .BR pthreads (7) |