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