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/lib/libc_r/man/pthread_attr.3,v 1.4.2.7 2003/03/04 16:51:13 phantom Exp $
  29 .\" $DragonFly: src/lib/libc_r/man/pthread_attr.3,v 1.2 2003/06/17 04:26:47 dillon Exp $
  30 .Dd June 28, 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 .Fn pthread_attr_init
 130 will fail if:
 131 .Bl -tag -width Er
 132 .It Bq Er ENOMEM
 133 Out of memory.
 134 .El
 135 .Pp
 136 .Fn pthread_attr_destroy
 137 will fail if:
 138 .Bl -tag -width Er
 139 .It Bq Er EINVAL
 140 Invalid value for
 141 .Fa attr .
 142 .El
 143 .Pp
 144 The
 145 .Fn pthread_attr_setstacksize
 146 and
 147 .Fn pthread_attr_setstack
 148 functions will fail if:
 149 .Bl -tag -width Er
 150 .It Bq Er EINVAL
 151 .Fa stacksize
 152 is less than
 153 .Dv PTHREAD_STACK_MIN .
 154 .El
 155 .Pp
 156 The
 157 .Fn pthread_attr_setguardsize
 158 and
 159 .Fn pthread_attr_getguardsize
 160 functions will fail if:
 161 .Bl -tag -width Er
 162 .It Bq Er EINVAL
 163 Invalid value for
 164 .Fa guardsize .
 165 .El
 166 .Pp
 167 .Fn pthread_attr_setdetachstate
 168 will fail if:
 169 .Bl -tag -width Er
 170 .It Bq Er EINVAL
 171 Invalid value for
 172 .Fa detachstate .
 173 .El
 174 .Pp
 175 .Fn pthread_attr_setinheritsched
 176 will fail if:
 177 .Bl -tag -width Er
 178 .It Bq Er EINVAL
 179 Invalid value for
 180 .Fa attr .
 181 .El
 182 .Pp
 183 .Fn pthread_attr_setschedparam
 184 will fail if:
 185 .Bl -tag -width Er
 186 .It Bq Er EINVAL
 187 Invalid value for
 188 .Fa attr .
 189 .It Bq Er ENOTSUP
 190 Invalid value for
 191 .Fa param .
 192 .El
 193 .Pp
 194 .Fn pthread_attr_setschedpolicy
 195 will fail if:
 196 .Bl -tag -width Er
 197 .It Bq Er EINVAL
 198 Invalid value for
 199 .Fa attr .
 200 .It Bq Er ENOTSUP
 201 Invalid or unsupported value for
 202 .Fa policy .
 203 .El
 204 .Pp
 205 .Fn pthread_attr_setscope
 206 will fail if:
 207 .Bl -tag -width Er
 208 .It Bq Er EINVAL
 209 Invalid value for
 210 .Fa attr .
 211 .It Bq Er ENOTSUP
 212 Invalid or unsupported value for
 213 .Fa contentionscope .
 214 .El
 215 .Sh SEE ALSO
 216 .Xr pthread_attr_get_np 3 ,
 217 .Xr pthread_create 3
 218 .Sh STANDARDS
 219 .Fn pthread_attr_init ,
 220 .Fn pthread_attr_destroy ,
 221 .Fn pthread_attr_setstacksize ,
 222 .Fn pthread_attr_getstacksize ,
 223 .Fn pthread_attr_setstackaddr ,
 224 .Fn pthread_attr_getstackaddr ,
 225 .Fn pthread_attr_setdetachstate ,
 226 and
 227 .Fn pthread_attr_getdetachstate
 228 conform to
 229 .St -p1003.1-96
 230 .Pp
 231 .Fn pthread_attr_setinheritsched ,
 232 .Fn pthread_attr_getinheritsched ,
 233 .Fn pthread_attr_setschedparam ,
 234 .Fn pthread_attr_getschedparam ,
 235 .Fn pthread_attr_setschedpolicy ,
 236 .Fn pthread_attr_getschedpolicy ,
 237 .Fn pthread_attr_setscope ,
 238 and
 239 .Fn pthread_attr_getscope
 240 conform to
 241 .St -susv2