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 2019-03-06 "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(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 .TS
  86 allbox;
  87 lbw30 lb lb
  88 l l l.
  89 Interface       Attribute       Value
  90 T{
  91 .BR pthread_getattr_default_np (),
  92 .BR pthread_setattr_default_np ()
  93 T}      Thread safety   MT-Safe
  94 .TE
  95 .ad
  96 .SH CONFORMING TO
  97 These functions are nonstandard GNU extensions;
  98 hence the suffix "_np" (nonportable) in their names.
  99 .SH EXAMPLE
 100 The program below uses
 101 .BR pthread_getattr_default_np ()
 102 to fetch the default thread-creation attributes and then displays
 103 various settings from the returned thread attributes object.
 104 When running the program, we see the following output:
 105 .PP
 106 .in +4n
 107 .EX
 108 $ \fB./a.out\fP
 109 Stack size:          8388608
 110 Guard size:          4096
 111 Scheduling policy:   SCHED_OTHER
 112 Scheduling priority: 0
 113 Detach state:        JOINABLE
 114 Inherit scheduler:   INHERIT
 115 .EE
 116 .in
 117 .PP
 118 .SS Program source
 119 \&
 120 .EX
 121 #define _GNU_SOURCE
 122 #include <pthread.h>
 123 #include <stdio.h>
 124 #include <stdlib.h>
 125 #include <errno.h>
 126
 127 #define errExitEN(en, msg) \e
 128                         do { errno = en; perror(msg); \e
 129                              exit(EXIT_FAILURE); } while (0)
 130
 131 static void
 132 display_pthread_attr(pthread_attr_t *attr)
 133 {
 134     int s;
 135     size_t stacksize;
 136     size_t guardsize;
 137     int policy;
 138     struct sched_param schedparam;
 139     int detachstate;
 140     int inheritsched;
 141
 142     s = pthread_attr_getstacksize(attr, &stacksize);
 143     if (s != 0)
 144         errExitEN(s, "pthread_attr_getstacksize");
 145     printf("Stack size:          %zd\en", stacksize);
 146
 147     s = pthread_attr_getguardsize(attr, &guardsize);
 148     if (s != 0)
 149         errExitEN(s, "pthread_attr_getguardsize");
 150     printf("Guard size:          %zd\en", guardsize);
 151
 152     s = pthread_attr_getschedpolicy(attr, &policy);
 153     if (s != 0)
 154         errExitEN(s, "pthread_attr_getschedpolicy");
 155     printf("Scheduling policy:   %s\en",
 156             (policy == SCHED_FIFO) ? "SCHED_FIFO" :
 157             (policy == SCHED_RR) ? "SCHED_RR" :
 158             (policy == SCHED_OTHER) ? "SCHED_OTHER" : "[unknown]");
 159
 160     s = pthread_attr_getschedparam(attr, &schedparam);
 161     if (s != 0)
 162         errExitEN(s, "pthread_attr_getschedparam");
 163     printf("Scheduling priority: %d\en", schedparam.sched_priority);
 164
 165     s = pthread_attr_getdetachstate(attr, &detachstate);
 166     if (s != 0)
 167         errExitEN(s, "pthread_attr_getdetachstate");
 168     printf("Detach state:        %s\en",
 169             (detachstate == PTHREAD_CREATE_DETACHED) ? "DETACHED" :
 170             (detachstate == PTHREAD_CREATE_JOINABLE) ? "JOINABLE" :
 171             "???");
 172
 173     s = pthread_attr_getinheritsched(attr, &inheritsched);
 174     if (s != 0)
 175         errExitEN(s, "pthread_attr_getinheritsched");
 176     printf("Inherit scheduler:   %s\en",
 177             (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
 178             (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
 179             "???");
 180 }
 181
 182 int
 183 main(int argc, char *argv[])
 184 {
 185     int s;
 186     pthread_attr_t attr;
 187
 188     s = pthread_getattr_default_np(&attr);
 189     if (s != 0)
 190         errExitEN(s, "pthread_getattr_default_np");
 191
 192     display_pthread_attr(&attr);
 193
 194     exit(EXIT_SUCCESS);
 195 }
 196 .EE
 197 .SH SEE ALSO
 198 .ad l
 199 .nh
 200 .BR pthread_attr_getaffinity_np (3),
 201 .BR pthread_attr_getdetachstate (3),
 202 .BR pthread_attr_getguardsize (3),
 203 .BR pthread_attr_getinheritsched (3),
 204 .BR pthread_attr_getschedparam (3),
 205 .BR pthread_attr_getschedpolicy (3),
 206 .BR pthread_attr_getscope (3),
 207 .BR pthread_attr_getstack (3),
 208 .BR pthread_attr_getstackaddr (3),
 209 .BR pthread_attr_getstacksize (3),
 210 .BR pthread_attr_init (3),
 211 .BR pthread_create (3),
 212 .BR pthreads (7)