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