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