man3/pthread_getattr_default_np.3

   1 .\" Copyright (c) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH PTHREAD_GETATTR_DEFAULT_NP 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 pthread_getattr_default_np, pthread_setattr_default_np, \-
  28 get or set default thread-creation attributes
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  32 .B #include <pthread.h>
  33 .PP
  34 .BI "int pthread_getattr_default_np(pthread_attr_t *" attr );
  35 .BI "int pthread_setattr_default_np(const pthread_attr_t *" attr );
  36 .PP
  37 Compile and link with \fI\-pthread\fP.
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR pthread_setattr_default_np ()
  42 function sets the default attributes used for creation of a new
  43 thread\(emthat is, the attributes that are used when
  44 .BR pthread_create (3)
  45 is called with a second argument that is NULL.
  46 The default attributes are set using the attributes supplied in
  47 .IR *attr ,
  48 a previously initialized thread attributes object.
  49 Note the following details about the supplied attributes object:
  50 .IP * 3
  51 The attribute settings in the object must be valid.
  52 .IP *
  53 The
  54 .IR "stack address"
  55 attribute must not be set in the object.
  56 .IP *
  57 Setting the
  58 .IR "stack size"
  59 attribute to zero means leave the default stack size unchanged.
  60 .PP
  61 The
  62 .BR pthread_getattr_default_np ()
  63 function initializes the thread attributes object referred to by
  64 .I attr
  65 so that it contains the default attributes used for thread creation.
  66 .SH ERRORS
  67 .TP
  68 .B EINVAL
  69 .RB ( pthread_setattr_default_np ())
  70 One of the attribute settings in
  71 .IR attr
  72 is invalid, or the stack address attribute is set in
  73 .IR attr .
  74 .TP
  75 .B ENOMEM
  76 .\" Can happen (but unlikely) while trying to allocate memory for cpuset
  77 .RB ( pthread_setattr_default_np ())
  78 Insufficient memory.
  79 .SH VERSIONS
  80 These functions are available in glibc since version 2.18.
  81 .SH ATTRIBUTES
  82 For an explanation of the terms used in this section, see
  83 .BR attributes (7).
  84 .ad l
  85 .nh
  86 .TS
  87 allbox;
  88 lbx lb lb
  89 l l l.
  90 Interface       Attribute       Value
  91 T{
  92 .BR pthread_getattr_default_np (),
  93 .BR pthread_setattr_default_np ()
  94 T}      Thread safety   MT-Safe
  95 .TE
  96 .hy
  97 .ad
  98 .sp 1
  99 .SH CONFORMING TO
 100 These functions are nonstandard GNU extensions;
 101 hence the suffix "_np" (nonportable) in their names.
 102 .SH EXAMPLES
 103 The program below uses
 104 .BR pthread_getattr_default_np ()
 105 to fetch the default thread-creation attributes and then displays
 106 various settings from the returned thread attributes object.
 107 When running the program, we see the following output:
 108 .PP
 109 .in +4n
 110 .EX
 111 $ \fB./a.out\fP
 112 Stack size:          8388608
 113 Guard size:          4096
 114 Scheduling policy:   SCHED_OTHER
 115 Scheduling priority: 0
 116 Detach state:        JOINABLE
 117 Inherit scheduler:   INHERIT
 118 .EE
 119 .in
 120 .SS Program source
 121 \&
 122 .EX
 123 #define _GNU_SOURCE
 124 #include <pthread.h>
 125 #include <stdio.h>
 126 #include <stdlib.h>
 127 #include <errno.h>
 128
 129 #define errExitEN(en, msg) \e
 130                         do { errno = en; perror(msg); \e
 131                              exit(EXIT_FAILURE); } while (0)
 132
 133 static void
 134 display_pthread_attr(pthread_attr_t *attr)
 135 {
 136     int s;
 137     size_t stacksize;
 138     size_t guardsize;
 139     int policy;
 140     struct sched_param schedparam;
 141     int detachstate;
 142     int inheritsched;
 143
 144     s = pthread_attr_getstacksize(attr, &stacksize);
 145     if (s != 0)
 146         errExitEN(s, "pthread_attr_getstacksize");
 147     printf("Stack size:          %zd\en", stacksize);
 148
 149     s = pthread_attr_getguardsize(attr, &guardsize);
 150     if (s != 0)
 151         errExitEN(s, "pthread_attr_getguardsize");
 152     printf("Guard size:          %zd\en", guardsize);
 153
 154     s = pthread_attr_getschedpolicy(attr, &policy);
 155     if (s != 0)
 156         errExitEN(s, "pthread_attr_getschedpolicy");
 157     printf("Scheduling policy:   %s\en",
 158             (policy == SCHED_FIFO) ? "SCHED_FIFO" :
 159             (policy == SCHED_RR) ? "SCHED_RR" :
 160             (policy == SCHED_OTHER) ? "SCHED_OTHER" : "[unknown]");
 161
 162     s = pthread_attr_getschedparam(attr, &schedparam);
 163     if (s != 0)
 164         errExitEN(s, "pthread_attr_getschedparam");
 165     printf("Scheduling priority: %d\en", schedparam.sched_priority);
 166
 167     s = pthread_attr_getdetachstate(attr, &detachstate);
 168     if (s != 0)
 169         errExitEN(s, "pthread_attr_getdetachstate");
 170     printf("Detach state:        %s\en",
 171             (detachstate == PTHREAD_CREATE_DETACHED) ? "DETACHED" :
 172             (detachstate == PTHREAD_CREATE_JOINABLE) ? "JOINABLE" :
 173             "???");
 174
 175     s = pthread_attr_getinheritsched(attr, &inheritsched);
 176     if (s != 0)
 177         errExitEN(s, "pthread_attr_getinheritsched");
 178     printf("Inherit scheduler:   %s\en",
 179             (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
 180             (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
 181             "???");
 182 }
 183
 184 int
 185 main(int argc, char *argv[])
 186 {
 187     int s;
 188     pthread_attr_t attr;
 189
 190     s = pthread_getattr_default_np(&attr);
 191     if (s != 0)
 192         errExitEN(s, "pthread_getattr_default_np");
 193
 194     display_pthread_attr(&attr);
 195
 196     exit(EXIT_SUCCESS);
 197 }
 198 .EE
 199 .SH SEE ALSO
 200 .ad l
 201 .nh
 202 .BR pthread_attr_getaffinity_np (3),
 203 .BR pthread_attr_getdetachstate (3),
 204 .BR pthread_attr_getguardsize (3),
 205 .BR pthread_attr_getinheritsched (3),
 206 .BR pthread_attr_getschedparam (3),
 207 .BR pthread_attr_getschedpolicy (3),
 208 .BR pthread_attr_getscope (3),
 209 .BR pthread_attr_getstack (3),
 210 .BR pthread_attr_getstackaddr (3),
 211 .BR pthread_attr_getstacksize (3),
 212 .BR pthread_attr_init (3),
 213 .BR pthread_create (3),
 214 .BR pthreads (7)