lib/libpthread/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/share/man/man3/pthread_attr.3,v 1.18 2007/10/22 10:08:00 ru Exp $
  29 .\"
  30 .Dd February 22, 2018
  31 .Dt PTHREAD_ATTR 3
  32 .Os
  33 .Sh NAME
  34 .Nm pthread_attr_init ,
  35 .Nm pthread_attr_destroy ,
  36 .Nm pthread_attr_setstack ,
  37 .Nm pthread_attr_getstack ,
  38 .Nm pthread_attr_setstacksize ,
  39 .Nm pthread_attr_getstacksize ,
  40 .Nm pthread_attr_setguardsize ,
  41 .Nm pthread_attr_getguardsize ,
  42 .Nm pthread_attr_setstackaddr ,
  43 .Nm pthread_attr_getstackaddr ,
  44 .Nm pthread_attr_setdetachstate ,
  45 .Nm pthread_attr_getdetachstate ,
  46 .Nm pthread_attr_setinheritsched ,
  47 .Nm pthread_attr_getinheritsched ,
  48 .Nm pthread_attr_setschedparam ,
  49 .Nm pthread_attr_getschedparam ,
  50 .Nm pthread_attr_setschedpolicy ,
  51 .Nm pthread_attr_getschedpolicy ,
  52 .Nm pthread_attr_setscope ,
  53 .Nm pthread_attr_getscope
  54 .Nd thread attribute operations
  55 .Sh LIBRARY
  56 .Lb libpthread
  57 .Sh SYNOPSIS
  58 .In pthread.h
  59 .Ft int
  60 .Fn pthread_attr_init "pthread_attr_t *attr"
  61 .Ft int
  62 .Fn pthread_attr_destroy "pthread_attr_t *attr"
  63 .Ft int
  64 .Fn pthread_attr_setstack "pthread_attr_t *attr" "void *stackaddr" "size_t stacksize"
  65 .Ft int
  66 .Fn pthread_attr_getstack "const pthread_attr_t * restrict attr" "void ** restrict stackaddr" "size_t * restrict stacksize"
  67 .Ft int
  68 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
  69 .Ft int
  70 .Fn pthread_attr_getstacksize "const pthread_attr_t * restrict attr" "size_t * restrict stacksize"
  71 .Ft int
  72 .Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize"
  73 .Ft int
  74 .Fn pthread_attr_getguardsize "const pthread_attr_t * restrict attr" "size_t * restrict guardsize"
  75 .Ft int
  76 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
  77 .Ft int
  78 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
  79 .Ft int
  80 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
  81 .Ft int
  82 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
  83 .Ft int
  84 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
  85 .Ft int
  86 .Fn pthread_attr_getinheritsched "const pthread_attr_t * restrict attr" "int * restrict inheritsched"
  87 .Ft int
  88 .Fn pthread_attr_setschedparam "pthread_attr_t * restrict attr" "const struct sched_param * restrict param"
  89 .Ft int
  90 .Fn pthread_attr_getschedparam "const pthread_attr_t * restrict attr" "struct sched_param * restrict param"
  91 .Ft int
  92 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
  93 .Ft int
  94 .Fn pthread_attr_getschedpolicy "const pthread_attr_t * restrict attr" "int * restrict policy"
  95 .Ft int
  96 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
  97 .Ft int
  98 .Fn pthread_attr_getscope "const pthread_attr_t * restrict attr" "int * restrict contentionscope"
  99 .Sh DESCRIPTION
 100 Thread attributes are used to specify parameters to
 101 .Fn pthread_create .
 102 One attribute object can be used in multiple calls to
 103 .Fn pthread_create ,
 104 with or without modifications between calls.
 105 .Pp
 106 The
 107 .Fn pthread_attr_init
 108 function initializes
 109 .Fa attr
 110 with all the default thread attributes.
 111 .Pp
 112 The
 113 .Fn pthread_attr_destroy
 114 function destroys
 115 .Fa attr .
 116 .Pp
 117 The
 118 .Fn pthread_attr_set*
 119 functions set the attribute that corresponds to each function name.
 120 .Pp
 121 The
 122 .Fn pthread_attr_get*
 123 functions copy the value of the attribute that corresponds to each function name
 124 to the location pointed to by the second function parameter.
 125 .Sh RETURN VALUES
 126 If successful, these functions return 0.
 127 Otherwise, an error number is returned to indicate the error.
 128 .Sh ERRORS
 129 The
 130 .Fn pthread_attr_init
 131 function will fail if:
 132 .Bl -tag -width Er
 133 .It Bq Er ENOMEM
 134 Out of memory.
 135 .El
 136 .Pp
 137 The
 138 .Fn pthread_attr_destroy
 139 function will fail if:
 140 .Bl -tag -width Er
 141 .It Bq Er EINVAL
 142 Invalid value for
 143 .Fa attr .
 144 .El
 145 .Pp
 146 The
 147 .Fn pthread_attr_setstacksize
 148 and
 149 .Fn pthread_attr_setstack
 150 functions will fail if:
 151 .Bl -tag -width Er
 152 .It Bq Er EINVAL
 153 .Fa stacksize
 154 is less than
 155 .Dv PTHREAD_STACK_MIN .
 156 .El
 157 .Pp
 158 The
 159 .Fn pthread_attr_setguardsize
 160 and
 161 .Fn pthread_attr_getguardsize
 162 functions will fail if:
 163 .Bl -tag -width Er
 164 .It Bq Er EINVAL
 165 Invalid value for
 166 .Fa guardsize .
 167 .El
 168 .Pp
 169 The
 170 .Fn pthread_attr_setdetachstate
 171 function will fail if:
 172 .Bl -tag -width Er
 173 .It Bq Er EINVAL
 174 Invalid value for
 175 .Fa detachstate .
 176 .El
 177 .Pp
 178 The
 179 .Fn pthread_attr_setinheritsched
 180 function will fail if:
 181 .Bl -tag -width Er
 182 .It Bq Er EINVAL
 183 Invalid value for
 184 .Fa inheritsched
 185 or uninitialized
 186 .Fa attr .
 187 .El
 188 .Pp
 189 The
 190 .Fn pthread_attr_setschedparam
 191 function will fail if:
 192 .Bl -tag -width Er
 193 .It Bq Er EINVAL
 194 Invalid value for
 195 .Fa attr .
 196 .It Bq Er ENOTSUP
 197 Invalid value for
 198 .Fa param .
 199 .El
 200 .Pp
 201 The
 202 .Fn pthread_attr_setschedpolicy
 203 function will fail if:
 204 .Bl -tag -width Er
 205 .It Bq Er EINVAL
 206 Invalid value for
 207 .Fa policy
 208 or uninitialized
 209 .Fa attr .
 210 .El
 211 .Pp
 212 The
 213 .Fn pthread_attr_setscope
 214 function will fail if:
 215 .Bl -tag -width Er
 216 .It Bq Er EINVAL
 217 Invalid value for
 218 .Fa attr .
 219 .It Bq Er ENOTSUP
 220 Invalid or unsupported value for
 221 .Fa contentionscope .
 222 .El
 223 .Sh SEE ALSO
 224 .Xr pthread_attr_get_np 3 ,
 225 .Xr pthread_create 3
 226 .Sh STANDARDS
 227 The
 228 .Fn pthread_attr_init ,
 229 .Fn pthread_attr_destroy ,
 230 .Fn pthread_attr_setstacksize ,
 231 .Fn pthread_attr_getstacksize ,
 232 .Fn pthread_attr_setstackaddr ,
 233 .Fn pthread_attr_getstackaddr ,
 234 .Fn pthread_attr_setdetachstate ,
 235 and
 236 .Fn pthread_attr_getdetachstate
 237 functions conform to
 238 .St -p1003.1-96 .
 239 .Pp
 240 The
 241 .Fn pthread_attr_setinheritsched ,
 242 .Fn pthread_attr_getinheritsched ,
 243 .Fn pthread_attr_setschedparam ,
 244 .Fn pthread_attr_getschedparam ,
 245 .Fn pthread_attr_setschedpolicy ,
 246 .Fn pthread_attr_getschedpolicy ,
 247 .Fn pthread_attr_setscope ,
 248 and
 249 .Fn pthread_attr_getscope
 250 functions conform to
 251 .St -susv2 .