share/man/man3c/pthread_attr_get_np.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd Feb 07, 2015
  15 .Dt PTHREAD_ATTR_GET_NP 3C
  16 .Os
  17 .Sh NAME
  18 .Nm pthread_attr_get_np
  19 .Nd get pthread attributes of a running thread
  20 .Sh SYNOPSIS
  21 .In pthread.h
  22 .Ft int
  23 .Fo pthread_attr_get_np
  24 .Fa "pthread_t thread"
  25 .Fa "pthread_attr_t *attr"
  26 .Fc
  27 .Sh DESCRIPTION
  28 The
  29 .Fn pthread_attr_get_np
  30 function provides a way to get the attributes of the thread
  31 .Fa thread
  32 after it has been created.
  33 This function is most commonly used to obtain the actual location and size of a
  34 thread's stack.
  35 .Pp
  36 The attributes pointer,
  37 .Fa attr ,
  38 will be filled in with the current attributes for the thread.
  39 The attributes should be allocated by a call to
  40 .Xr pthread_attr_init 3C
  41 prior to calling the
  42 .Fn pthrad_attr_get_np
  43 function.
  44 When
  45 .Fa attr
  46 is done being used, it should be destroyed through a call to
  47 .Xr pthread_attr_destroy 3C .
  48 .Pp
  49 The attributes of the thread
  50 .Fa thread
  51 will be the same as those passed in at the time
  52 .Xr pthread_create 3C
  53 was called (or the default set if none were specified), except that the
  54 following values will be updated:
  55 .Bl -tag -width Sy
  56 .It Sy Thread Stack Size
  57 If no explicit stack size was specified, then
  58 .Fa attr
  59 will contain the actual size of the stack.
  60 .Pp
  61 If the size of the stack was specified, then it may have been changed to
  62 ensure that the required alignment of the platform is satisfied.
  63 .It Sy The Stack Address
  64 If no stack address was specified, then
  65 .Fa attr
  66 will contain the actual address of the stack that the system allocated
  67 for the thread.
  68 .It Sy Thread Detach State
  69 The detach state, whether or not the thread may be joined by a call to
  70 .Xr pthread_join 3C ,
  71 may have changed since the process was created due to a call to
  72 .Xr pthread_detach 3C .
  73 .Fa attr
  74 will reflect the current setting of
  75 .Fa thread .
  76 .It Sy Thread Scheduling Parameter
  77 The scheduling parameter attribute will be updated with the current
  78 scheduling parameter of
  79 .Fa thread .
  80 This is the same information as available through
  81 .Xr pthread_getschedparam 3C
  82 and it is the preferred interface for obtaining that information.
  83 .It Sy Thread Scheduling Policy
  84 The scheduling policy attribute of
  85 .Fa attr
  86 will be updated with the current scheduling policy being applied to the
  87 thread.
  88 This may have changed, for example, due to a call to
  89 .Xr pthread_setschedparam 3C .
  90 As with the thread's scheduling parameter, the preferred interface for
  91 obtaining this information is by using
  92 .Xr pthread_getschedparam 3C .
  93 .It Sy Thread Guard Size
  94 The value of the guard size attribute for the thread will be updated to
  95 reflect the actual size of the guard installed for
  96 .Fa thread .
  97 For more information on the guard size of a thread and its purpose, see
  98 .Xr pthread_attr_getguardsize 3C .
  99 .El
 100 .Sh RETURN VALUES
 101 Upon successful completion, the
 102 .Fn pthread_attr_get_np
 103 and
 104 .Fn pthread_getattr_np
 105 functions return
 106 .Sy 0 .
 107 Otherwise, an error number is returned to indicate the error.
 108 .Sh EXAMPLES
 109 The following program demonstrates how to use these functions to get
 110 the location and stack size of a newly created thread.
 111 .Bd -literal
 112 #include <assert.h>
 113 #include <errno.h>
 114 #include <pthread.h>
 115 #include <stdio.h>
 116 #include <stdlib.h>
 117 #include <string.h>
 118
 119 static pthread_t g_thr;
 120
 121 void *
 122 print_stackinfo(void *arg)
 123 {
 124         int ret;
 125         pthread_attr_t attr;
 126         pthread_t *thrp = arg;
 127         void *stk;
 128         size_t stksize;
 129
 130         if (pthread_attr_init(&attr) != 0) {
 131                 fprintf(stderr, "failed to init attr: %s\\n",
 132                     strerror(errno));
 133                 exit(1);
 134         }
 135
 136         if (pthread_attr_get_np(*thrp, &attr) != 0) {
 137                 fprintf(stderr, "failed to get thread attributes: %s\\n",
 138                     strerror(errno));
 139                 exit(1);
 140         }
 141
 142         ret = pthread_attr_getstackaddr(&attr, &stk);
 143         assert(ret == 0);
 144         ret = pthread_attr_getstacksize(&attr, &stksize);
 145         assert(ret == 0);
 146         (void) printf("stack base is at %p, it is %d bytes large\\n",
 147             stk, stksize);
 148         return (NULL);
 149 }
 150
 151 int
 152 main(void)
 153 {
 154         int ret;
 155
 156         if ((ret = pthread_create(&g_thr, NULL, print_stackinfo,
 157             &g_thr) != 0)) {
 158                 fprintf(stderr, "failed to create a thread: %s\\n",
 159                     strerror(errno));
 160                 exit(1);
 161         }
 162
 163         pthread_join(g_thr, NULL);
 164         return (0);
 165 }
 166 .Ed
 167 .Sh ERRORS
 168 The
 169 .Fn pthread_attr_get_np
 170 function will fail if:
 171 .Bl -tag -width Er
 172 .It Er EINVAL
 173 The pthread_attr_t object
 174 .Fa attr
 175 was not properly initialized with a call to
 176 .Xr pthread_attr_init 3C .
 177 .It Er ESRCH
 178 No thread could be found corresponding to the specified thread ID,
 179 .Fa thread .
 180 .El
 181 .Sh INTERFACE STABILITY
 182 .Sy Committed
 183 .Sh MT-LEVEL
 184 .Sy MT-Safe
 185 .Sh SEE ALSO
 186 .Xr pthread_attr_destroy 3C ,
 187 .Xr pthread_attr_getdetachstate 3C ,
 188 .Xr pthread_attr_getguardsize 3C ,
 189 .Xr pthread_attr_getinheritsched 3C ,
 190 .Xr pthread_attr_getschedparam 3C ,
 191 .Xr pthread_attr_getschedpolicy 3C ,
 192 .Xr pthread_attr_getscope 3C ,
 193 .Xr pthread_attr_getstackaddr 3C ,
 194 .Xr pthread_attr_getstacksize 3C ,
 195 .Xr pthread_attr_init 3C ,
 196 .Xr pthread_create 3C ,
 197 .Xr pthread_detach 3C ,
 198 .Xr pthread_getschedparam 3C ,
 199 .Xr pthread_setschedparam 3C ,
 200 .Xr attributes 5 ,
 201 .Xr threads 5