share/man/man3/pthread_mutexattr.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 August 17, 2018
  30 .Dt PTHREAD_MUTEXATTR 3
  31 .Os
  32 .Sh NAME
  33 .Nm pthread_mutexattr_init ,
  34 .Nm pthread_mutexattr_destroy ,
  35 .Nm pthread_mutexattr_setprioceiling ,
  36 .Nm pthread_mutexattr_getprioceiling ,
  37 .Nm pthread_mutexattr_setprotocol ,
  38 .Nm pthread_mutexattr_getprotocol ,
  39 .Nm pthread_mutexattr_setrobust ,
  40 .Nm pthread_mutexattr_getrobust ,
  41 .Nm pthread_mutexattr_settype ,
  42 .Nm pthread_mutexattr_gettype
  43 .Nd mutex attribute operations
  44 .Sh LIBRARY
  45 .Lb libpthread
  46 .Sh SYNOPSIS
  47 .In pthread.h
  48 .Ft int
  49 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
  50 .Ft int
  51 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
  52 .Ft int
  53 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
  54 .Ft int
  55 .Fn pthread_mutexattr_getprioceiling "const pthread_mutexattr_t *attr" "int *prioceiling"
  56 .Ft int
  57 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
  58 .Ft int
  59 .Fn pthread_mutexattr_getprotocol "const pthread_mutexattr_t *restrict attr" "int *restrict protocol"
  60 .Ft int
  61 .Fn pthread_mutexattr_setrobust "pthread_mutexattr_t *attr" "int robust"
  62 .Ft int
  63 .Fn pthread_mutexattr_getrobust "pthread_mutexattr_t *attr" "int *robust"
  64 .Ft int
  65 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
  66 .Ft int
  67 .Fn pthread_mutexattr_gettype "const pthread_mutexattr_t *restrict attr" "int *restrict type"
  68 .Sh DESCRIPTION
  69 Mutex attributes are used to specify parameters to
  70 .Fn pthread_mutex_init .
  71 One attribute object can be used in multiple calls to
  72 .Fn pthread_mutex_init ,
  73 with or without modifications between calls.
  74 .Pp
  75 The
  76 .Fn pthread_mutexattr_init
  77 function initializes
  78 .Fa attr
  79 with all the default mutex attributes.
  80 .Pp
  81 The
  82 .Fn pthread_mutexattr_destroy
  83 function destroys
  84 .Fa attr .
  85 .Pp
  86 The
  87 .Fn pthread_mutexattr_set*
  88 functions set the attribute that corresponds to each function name.
  89 .Pp
  90 The
  91 .Fn pthread_mutexattr_get*
  92 functions copy the value of the attribute that corresponds to each function name
  93 to the location pointed to by the second function parameter.
  94 .Sh RETURN VALUES
  95 If successful, these functions return 0.
  96 Otherwise, an error number is returned to indicate the error.
  97 .Sh ERRORS
  98 The
  99 .Fn pthread_mutexattr_init
 100 function will fail if:
 101 .Bl -tag -width Er
 102 .It Bq Er ENOMEM
 103 Out of memory.
 104 .El
 105 .Pp
 106 The
 107 .Fn pthread_mutexattr_destroy
 108 function will fail if:
 109 .Bl -tag -width Er
 110 .It Bq Er EINVAL
 111 Invalid value for
 112 .Fa attr .
 113 .El
 114 .Pp
 115 The
 116 .Fn pthread_mutexattr_setprioceiling
 117 function will fail if:
 118 .Bl -tag -width Er
 119 .It Bq Er EINVAL
 120 Invalid value for
 121 .Fa attr ,
 122 or invalid value for
 123 .Fa prioceiling .
 124 .El
 125 .Pp
 126 The
 127 .Fn pthread_mutexattr_getprioceiling
 128 function will fail if:
 129 .Bl -tag -width Er
 130 .It Bq Er EINVAL
 131 Invalid value for
 132 .Fa attr .
 133 .El
 134 .Pp
 135 The
 136 .Fn pthread_mutexattr_setprotocol
 137 function will fail if:
 138 .Bl -tag -width Er
 139 .It Bq Er EINVAL
 140 Invalid value for
 141 .Fa attr ,
 142 or invalid value for
 143 .Fa protocol .
 144 .El
 145 .Pp
 146 The
 147 .Fn pthread_mutexattr_getprotocol
 148 function will fail if:
 149 .Bl -tag -width Er
 150 .It Bq Er EINVAL
 151 Invalid value for
 152 .Fa attr .
 153 .El
 154 .Pp
 155 The
 156 .Fn pthread_mutexattr_settype
 157 function will fail if:
 158 .Bl -tag -width Er
 159 .It Bq Er EINVAL
 160 Invalid value for
 161 .Fa attr ,
 162 or invalid value for
 163 .Fa type .
 164 .El
 165 .Pp
 166 The
 167 .Fn pthread_mutexattr_gettype
 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_mutexattr_setrobust
 177 function will fail if:
 178 .Bl -tag -width Er
 179 .It Bq Er EINVAL
 180 Invalid value for
 181 .Fa attr ,
 182 or invalid value for
 183 .Fa robust .
 184 .El
 185 .Pp
 186 The
 187 .Fn pthread_mutexattr_getrobust
 188 function will fail if:
 189 .Bl -tag -width Er
 190 .It Bq Er EINVAL
 191 Invalid value for
 192 .Fa attr .
 193 .El
 194 .Sh SEE ALSO
 195 .Xr pthread_mutex_init 3
 196 .Sh STANDARDS
 197 The
 198 .Fn pthread_mutexattr_init
 199 and
 200 .Fn pthread_mutexattr_destroy
 201 functions conform to
 202 .St -p1003.1-96
 203 .Pp
 204 The
 205 .Fn pthread_mutexattr_setprioceiling ,
 206 .Fn pthread_mutexattr_getprioceiling ,
 207 .Fn pthread_mutexattr_setprotocol ,
 208 .Fn pthread_mutexattr_getprotocol ,
 209 .Fn pthread_mutexattr_settype ,
 210 and
 211 .Fn pthread_mutexattr_gettype
 212 functions conform to
 213 .St -susv2 .
 214 The
 215 .Fn pthread_mutexattr_setrobust
 216 and
 217 .Fn pthread_mutexattr_getrobust
 218 functions conform to
 219 .St -susv4 .