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 .\" $DragonFly: src/lib/libc_r/man/pthread_attr.3,v 1.2 2003/06/17 04:26:47 dillon Exp $
  30 .Dd July 10, 2009
  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 *attr" "size_t *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 *attr" "size_t *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 *attr" "int *inheritsched"
  87 .Ft int
  88 .Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param"
  89 .Ft int
  90 .Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *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 *attr" "int *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 *attr" "int *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 attr .
 185 .El
 186 .Pp
 187 The
 188 .Fn pthread_attr_setschedparam
 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 value for
 196 .Fa param .
 197 .El
 198 .Pp
 199 The
 200 .Fn pthread_attr_setschedpolicy
 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 policy .
 209 .El
 210 .Pp
 211 The
 212 .Fn pthread_attr_setscope
 213 function will fail if:
 214 .Bl -tag -width Er
 215 .It Bq Er EINVAL
 216 Invalid value for
 217 .Fa attr .
 218 .It Bq Er ENOTSUP
 219 Invalid or unsupported value for
 220 .Fa contentionscope .
 221 .El
 222 .Sh SEE ALSO
 223 .Xr pthread_attr_get_np 3 ,
 224 .Xr pthread_create 3
 225 .Sh STANDARDS
 226 The
 227 .Fn pthread_attr_init ,
 228 .Fn pthread_attr_destroy ,
 229 .Fn pthread_attr_setstacksize ,
 230 .Fn pthread_attr_getstacksize ,
 231 .Fn pthread_attr_setstackaddr ,
 232 .Fn pthread_attr_getstackaddr ,
 233 .Fn pthread_attr_setdetachstate ,
 234 and
 235 .Fn pthread_attr_getdetachstate
 236 functions conform to
 237 .St -p1003.1-96 .
 238 .Pp
 239 The
 240 .Fn pthread_attr_setinheritsched ,
 241 .Fn pthread_attr_getinheritsched ,
 242 .Fn pthread_attr_setschedparam ,
 243 .Fn pthread_attr_getschedparam ,
 244 .Fn pthread_attr_setschedpolicy ,
 245 .Fn pthread_attr_getschedpolicy ,
 246 .Fn pthread_attr_setscope ,
 247 and
 248 .Fn pthread_attr_getscope
 249 functions conform to
 250 .St -susv2 .