man3/pthread_getattr_default_np.3

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