man3/pthread_getattr_default_np.3

   1 '\" t
   2 .\" Copyright (c) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH pthread_getattr_default_np 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 pthread_getattr_default_np, pthread_setattr_default_np, \-
   9 get or set default thread-creation attributes
  10 .SH LIBRARY
  11 POSIX threads library
  12 .RI ( libpthread ", " \-lpthread )
  13 .SH SYNOPSIS
  14 .nf
  15 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  16 .B #include <pthread.h>
  17 .P
  18 .BI "int pthread_getattr_default_np(pthread_attr_t *" attr );
  19 .BI "int pthread_setattr_default_np(const pthread_attr_t *" attr );
  20 .fi
  21 .SH DESCRIPTION
  22 The
  23 .BR pthread_setattr_default_np ()
  24 function sets the default attributes used for creation of a new
  25 thread\[em]that is, the attributes that are used when
  26 .BR pthread_create (3)
  27 is called with a second argument that is NULL.
  28 The default attributes are set using the attributes supplied in
  29 .IR *attr ,
  30 a previously initialized thread attributes object.
  31 Note the following details about the supplied attributes object:
  32 .IP \[bu] 3
  33 The attribute settings in the object must be valid.
  34 .IP \[bu]
  35 The
  36 .I stack address
  37 attribute must not be set in the object.
  38 .IP \[bu]
  39 Setting the
  40 .I stack size
  41 attribute to zero means leave the default stack size unchanged.
  42 .P
  43 The
  44 .BR pthread_getattr_default_np ()
  45 function initializes the thread attributes object referred to by
  46 .I attr
  47 so that it contains the default attributes used for thread creation.
  48 .SH ERRORS
  49 .TP
  50 .B EINVAL
  51 .RB ( pthread_setattr_default_np ())
  52 One of the attribute settings in
  53 .I attr
  54 is invalid, or the stack address attribute is set in
  55 .IR attr .
  56 .TP
  57 .B ENOMEM
  58 .\" Can happen (but unlikely) while trying to allocate memory for cpuset
  59 .RB ( pthread_setattr_default_np ())
  60 Insufficient memory.
  61 .SH ATTRIBUTES
  62 For an explanation of the terms used in this section, see
  63 .BR attributes (7).
  64 .TS
  65 allbox;
  66 lbx lb lb
  67 l l l.
  68 Interface       Attribute       Value
  69 T{
  70 .na
  71 .nh
  72 .BR pthread_getattr_default_np (),
  73 .BR pthread_setattr_default_np ()
  74 T}      Thread safety   MT-Safe
  75 .TE
  76 .SH STANDARDS
  77 GNU;
  78 hence the suffix "_np" (nonportable) in their names.
  79 .SH HISTORY
  80 glibc 2.18.
  81 .SH EXAMPLES
  82 The program below uses
  83 .BR pthread_getattr_default_np ()
  84 to fetch the default thread-creation attributes and then displays
  85 various settings from the returned thread attributes object.
  86 When running the program, we see the following output:
  87 .P
  88 .in +4n
  89 .EX
  90 $ \fB./a.out\fP
  91 Stack size:          8388608
  92 Guard size:          4096
  93 Scheduling policy:   SCHED_OTHER
  94 Scheduling priority: 0
  95 Detach state:        JOINABLE
  96 Inherit scheduler:   INHERIT
  97 .EE
  98 .in
  99 .SS Program source
 100 \&
 101 .\" SRC BEGIN (pthread_getattr_default_np.c)
 102 .EX
 103 #define _GNU_SOURCE
 104 #include <err.h>
 105 #include <errno.h>
 106 #include <pthread.h>
 107 #include <stdio.h>
 108 #include <stdlib.h>
 109 \&
 110 static void
 111 display_pthread_attr(pthread_attr_t *attr)
 112 {
 113     int s;
 114     size_t stacksize;
 115     size_t guardsize;
 116     int policy;
 117     struct sched_param schedparam;
 118     int detachstate;
 119     int inheritsched;
 120 \&
 121     s = pthread_attr_getstacksize(attr, &stacksize);
 122     if (s != 0)
 123         errc(EXIT_FAILURE, s, "pthread_attr_getstacksize");
 124     printf("Stack size:          %zu\en", stacksize);
 125 \&
 126     s = pthread_attr_getguardsize(attr, &guardsize);
 127     if (s != 0)
 128         errc(EXIT_FAILURE, s, "pthread_attr_getguardsize");
 129     printf("Guard size:          %zu\en", guardsize);
 130 \&
 131     s = pthread_attr_getschedpolicy(attr, &policy);
 132     if (s != 0)
 133         errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy");
 134     printf("Scheduling policy:   %s\en",
 135            (policy == SCHED_FIFO) ? "SCHED_FIFO" :
 136            (policy == SCHED_RR) ? "SCHED_RR" :
 137            (policy == SCHED_OTHER) ? "SCHED_OTHER" : "[unknown]");
 138 \&
 139     s = pthread_attr_getschedparam(attr, &schedparam);
 140     if (s != 0)
 141         errc(EXIT_FAILURE, s, "pthread_attr_getschedparam");
 142     printf("Scheduling priority: %d\en", schedparam.sched_priority);
 143 \&
 144     s = pthread_attr_getdetachstate(attr, &detachstate);
 145     if (s != 0)
 146         errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate");
 147     printf("Detach state:        %s\en",
 148            (detachstate == PTHREAD_CREATE_DETACHED) ? "DETACHED" :
 149            (detachstate == PTHREAD_CREATE_JOINABLE) ? "JOINABLE" :
 150            "???");
 151 \&
 152     s = pthread_attr_getinheritsched(attr, &inheritsched);
 153     if (s != 0)
 154         errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched");
 155     printf("Inherit scheduler:   %s\en",
 156            (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
 157            (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
 158            "???");
 159 }
 160 \&
 161 int
 162 main(void)
 163 {
 164     int s;
 165     pthread_attr_t attr;
 166 \&
 167     s = pthread_getattr_default_np(&attr);
 168     if (s != 0)
 169         errc(EXIT_FAILURE, s, "pthread_getattr_default_np");
 170 \&
 171     display_pthread_attr(&attr);
 172 \&
 173     exit(EXIT_SUCCESS);
 174 }
 175 .EE
 176 .\" SRC END
 177 .SH SEE ALSO
 178 .ad l
 179 .nh
 180 .BR pthread_attr_getaffinity_np (3),
 181 .BR pthread_attr_getdetachstate (3),
 182 .BR pthread_attr_getguardsize (3),
 183 .BR pthread_attr_getinheritsched (3),
 184 .BR pthread_attr_getschedparam (3),
 185 .BR pthread_attr_getschedpolicy (3),
 186 .BR pthread_attr_getscope (3),
 187 .BR pthread_attr_getstack (3),
 188 .BR pthread_attr_getstackaddr (3),
 189 .BR pthread_attr_getstacksize (3),
 190 .BR pthread_attr_init (3),
 191 .BR pthread_create (3),
 192 .BR pthreads (7)