man/pthread_attr.3

   1 .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  23 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  25 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  26 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/lib/libc_r/man/pthread_attr.3,v 1.4.2.5 2001/08/17 15:42:51 ru Exp $
  29 .Dd April 28, 2000
  30 .Dt PTHREAD_ATTR 3
  31 .Os
  32 .Sh NAME
  33 .Nm pthread_attr_destroy ,
  34 .Nm pthread_attr_getdetachstate ,
  35 .Nm pthread_attr_getinheritsched ,
  36 .Nm pthread_attr_getschedparam ,
  37 .Nm pthread_attr_getschedpolicy ,
  38 .Nm pthread_attr_getscope ,
  39 .Nm pthread_attr_getstackaddr ,
  40 .Nm pthread_attr_getstacksize ,
  41 .Nm pthread_attr_init ,
  42 .Nm pthread_attr_setdetachstate ,
  43 .Nm pthread_attr_setinheritsched ,
  44 .Nm pthread_attr_setschedparam ,
  45 .Nm pthread_attr_setschedpolicy ,
  46 .Nm pthread_attr_setscope ,
  47 .Nm pthread_attr_setstackaddr ,
  48 .Nm pthread_attr_setstacksize
  49 .Nd thread attribute operations
  50 .Sh SYNOPSIS
  51 .Fd #include <pthread.h>
  52 .Ft int
  53 .Fo pthread_attr_destroy
  54 .Fa "pthread_attr_t *attr"
  55 .Fc
  56 .Ft int
  57 .Fo pthread_attr_getdetachstate
  58 .Fa "const pthread_attr_t *attr"
  59 .Fa "int *detachstate"
  60 .Fc
  61 .Ft int
  62 .Fo pthread_attr_getinheritsched
  63 .Fa "const pthread_attr_t *restrict attr"
  64 .Fa "int *restrict inheritsched"
  65 .Fc
  66 .Ft int
  67 .Fo pthread_attr_getschedparam
  68 .Fa "const pthread_attr_t *restrict attr"
  69 .Fa "struct sched_param *restrict param"
  70 .Fc
  71 .Ft int
  72 .Fo pthread_attr_getschedpolicy
  73 .Fa "const pthread_attr_t *restrict attr"
  74 .Fa "int *restrict policy"
  75 .Fc
  76 .Ft int
  77 .Fo pthread_attr_getscope
  78 .Fa "const pthread_attr_t *restrict attr"
  79 .Fa "int *restrict contentionscope"
  80 .Fc
  81 .Ft int
  82 .Fo pthread_attr_getstackaddr
  83 .Fa "const pthread_attr_t *restrict attr"
  84 .Fa "void **restrict stackaddr"
  85 .Fc
  86 .Ft int
  87 .Fo pthread_attr_getstacksize
  88 .Fa "const pthread_attr_t *restrict attr"
  89 .Fa "size_t *restrict stacksize"
  90 .Fc
  91 .Ft int
  92 .Fo pthread_attr_init
  93 .Fa "pthread_attr_t *attr"
  94 .Fc
  95 .Ft int
  96 .Fo pthread_attr_setdetachstate
  97 .Fa "pthread_attr_t *attr"
  98 .Fa "int detachstate"
  99 .Fc
 100 .Ft int
 101 .Fo pthread_attr_setinheritsched
 102 .Fa "pthread_attr_t *attr"
 103 .Fa "int inheritsched"
 104 .Fc
 105 .Ft int
 106 .Fo pthread_attr_setschedparam
 107 .Fa "pthread_attr_t *restrict attr"
 108 .Fa "const struct sched_param *restrict param"
 109 .Fc
 110 .Ft int
 111 .Fo pthread_attr_setschedpolicy
 112 .Fa "pthread_attr_t *attr"
 113 .Fa "int policy"
 114 .Fc
 115 .Ft int
 116 .Fo pthread_attr_setscope
 117 .Fa "pthread_attr_t *attr"
 118 .Fa "int contentionscope"
 119 .Fc
 120 .Ft int
 121 .Fo pthread_attr_setstackaddr
 122 .Fa "pthread_attr_t *attr"
 123 .Fa "void *stackaddr"
 124 .Fc
 125 .Ft int
 126 .Fo pthread_attr_setstacksize
 127 .Fa "pthread_attr_t *attr"
 128 .Fa "size_t stacksize"
 129 .Fc
 130 .Sh DESCRIPTION
 131 Thread attributes are used to specify parameters to
 132 .Fn pthread_create .
 133 One attribute object can be used in multiple calls to
 134 .Fn pthread_create ,
 135 with or without modifications between calls.
 136 .Pp
 137 The
 138 .Fn pthread_attr_init
 139 function initializes
 140 .Fa attr
 141 with all the default thread attributes.
 142 .Pp
 143 The
 144 .Fn pthread_attr_destroy
 145 function destroys
 146 .Fa attr .
 147 .Pp
 148 The
 149 .Fn pthread_attr_set*
 150 functions set the attribute that corresponds to each function name.
 151 .Pp
 152 The
 153 .Fn pthread_attr_get*
 154 functions copy the value of the attribute that corresponds to each function name
 155 to the location pointed to by the second function parameter.
 156 .Sh RETURN VALUES
 157 If successful, these functions return 0.
 158 Otherwise, an error number is returned to indicate the error.
 159 .Sh ERRORS
 160 .Fn pthread_attr_init
 161 will fail if:
 162 .Bl -tag -width Er
 163 .\" ========
 164 .It Bq Er ENOMEM
 165 Out of memory.
 166 .El
 167 .Pp
 168 .Fn pthread_attr_destroy
 169 will fail if:
 170 .Bl -tag -width Er
 171 .\" ========
 172 .It Bq Er EINVAL
 173 Invalid value for
 174 .Fa attr .
 175 .El
 176 .Pp
 177 .Fn pthread_attr_setstacksize
 178 will fail if:
 179 .Bl -tag -width Er
 180 .\" ========
 181 .It Bq Er EINVAL
 182 Invalid value for
 183 .Fa attr .
 184 .\" ========
 185 .It Bq Er EINVAL
 186 .Fa stacksize
 187 is less than
 188 .Dv PTHREAD_STACK_MIN .
 189 .\" ========
 190 .It Bq Er EINVAL
 191 .Fa stacksize
 192 is not a multiple of the system page size.
 193 .El
 194 .Pp
 195 .Fn pthread_attr_setdetachstate
 196 will fail if:
 197 .Bl -tag -width Er
 198 .\" ========
 199 .It Bq Er EINVAL
 200 Invalid value for
 201 .Fa attr
 202 or
 203 .Fa detachstate .
 204 .El
 205 .Pp
 206 .Fn pthread_attr_setinheritsched
 207 will fail if:
 208 .Bl -tag -width Er
 209 .\" ========
 210 .It Bq Er EINVAL
 211 Invalid value for
 212 .Fa attr .
 213 .El
 214 .Pp
 215 .Fn pthread_attr_setschedparam
 216 will fail if:
 217 .Bl -tag -width Er
 218 .\" ========
 219 .It Bq Er EINVAL
 220 Invalid value for
 221 .Fa attr .
 222 .\" ========
 223 .It Bq Er ENOTSUP
 224 Invalid value for
 225 .Fa param .
 226 .El
 227 .Pp
 228 .Fn pthread_attr_setschedpolicy
 229 will fail if:
 230 .Bl -tag -width Er
 231 .\" ========
 232 .It Bq Er EINVAL
 233 Invalid value for
 234 .Fa attr .
 235 .It Bq Er ENOTSUP
 236 Invalid or unsupported value for
 237 .Fa policy .
 238 .El
 239 .Pp
 240 .Fn pthread_attr_setscope
 241 will fail if:
 242 .Bl -tag -width Er
 243 .\" ========
 244 .It Bq Er EINVAL
 245 Invalid value for
 246 .Fa attr .
 247 .\" ========
 248 .It Bq Er ENOTSUP
 249 Invalid or unsupported value for
 250 .Fa contentionscope .
 251 .El
 252 .Sh SEE ALSO
 253 .Xr pthread_create 3
 254 .Sh STANDARDS
 255 .Fn pthread_attr_init ,
 256 .Fn pthread_attr_destroy ,
 257 .Fn pthread_attr_setstacksize ,
 258 .Fn pthread_attr_getstacksize ,
 259 .Fn pthread_attr_setstackaddr ,
 260 .Fn pthread_attr_getstackaddr ,
 261 .Fn pthread_attr_setdetachstate ,
 262 and
 263 .Fn pthread_attr_getdetachstate
 264 conform to
 265 .St -p1003.1-96
 266 .Pp
 267 .Fn pthread_attr_setinheritsched ,
 268 .Fn pthread_attr_getinheritsched ,
 269 .Fn pthread_attr_setschedparam ,
 270 .Fn pthread_attr_getschedparam ,
 271 .Fn pthread_attr_setschedpolicy ,
 272 .Fn pthread_attr_getschedpolicy ,
 273 .Fn pthread_attr_setscope ,
 274 and
 275 .Fn pthread_attr_getscope
 276 conform to
 277 .St -susv2