lib/libpthread/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: src/share/man/man3/pthread_mutexattr.3,v 1.13 2007/10/22 10:08:00 ru Exp $
  29 .\" $DragonFly: src/lib/libc_r/man/pthread_mutexattr.3,v 1.2 2003/06/17 04:26:48 dillon Exp $
  30 .Dd July 10, 2009
  31 .Dt PTHREAD_MUTEXATTR 3
  32 .Os
  33 .Sh NAME
  34 .Nm pthread_mutexattr_init ,
  35 .Nm pthread_mutexattr_destroy ,
  36 .Nm pthread_mutexattr_setprioceiling ,
  37 .Nm pthread_mutexattr_getprioceiling ,
  38 .Nm pthread_mutexattr_setprotocol ,
  39 .Nm pthread_mutexattr_getprotocol ,
  40 .Nm pthread_mutexattr_settype ,
  41 .Nm pthread_mutexattr_gettype
  42 .Nd mutex attribute operations
  43 .Sh LIBRARY
  44 .Lb libpthread
  45 .Sh SYNOPSIS
  46 .In pthread.h
  47 .Ft int
  48 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
  49 .Ft int
  50 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
  51 .Ft int
  52 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
  53 .Ft int
  54 .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling"
  55 .Ft int
  56 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
  57 .Ft int
  58 .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
  59 .Ft int
  60 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
  61 .Ft int
  62 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
  63 .Sh DESCRIPTION
  64 Mutex attributes are used to specify parameters to
  65 .Fn pthread_mutex_init .
  66 One attribute object can be used in multiple calls to
  67 .Fn pthread_mutex_init ,
  68 with or without modifications between calls.
  69 .Pp
  70 The
  71 .Fn pthread_mutexattr_init
  72 function initializes
  73 .Fa attr
  74 with all the default mutex attributes.
  75 .Pp
  76 The
  77 .Fn pthread_mutexattr_destroy
  78 function destroys
  79 .Fa attr .
  80 .Pp
  81 The
  82 .Fn pthread_mutexattr_set*
  83 functions set the attribute that corresponds to each function name.
  84 .Pp
  85 The
  86 .Fn pthread_mutexattr_get*
  87 functions copy the value of the attribute that corresponds to each function name
  88 to the location pointed to by the second function parameter.
  89 .Sh RETURN VALUES
  90 If successful, these functions return 0.
  91 Otherwise, an error number is returned to indicate the error.
  92 .Sh ERRORS
  93 The
  94 .Fn pthread_mutexattr_init
  95 function will fail if:
  96 .Bl -tag -width Er
  97 .It Bq Er ENOMEM
  98 Out of memory.
  99 .El
 100 .Pp
 101 The
 102 .Fn pthread_mutexattr_destroy
 103 function will fail if:
 104 .Bl -tag -width Er
 105 .It Bq Er EINVAL
 106 Invalid value for
 107 .Fa attr .
 108 .El
 109 .Pp
 110 The
 111 .Fn pthread_mutexattr_setprioceiling
 112 function will fail if:
 113 .Bl -tag -width Er
 114 .It Bq Er EINVAL
 115 Invalid value for
 116 .Fa attr ,
 117 or invalid value for
 118 .Fa prioceiling .
 119 .El
 120 .Pp
 121 The
 122 .Fn pthread_mutexattr_getprioceiling
 123 function will fail if:
 124 .Bl -tag -width Er
 125 .It Bq Er EINVAL
 126 Invalid value for
 127 .Fa attr .
 128 .El
 129 .Pp
 130 The
 131 .Fn pthread_mutexattr_setprotocol
 132 function will fail if:
 133 .Bl -tag -width Er
 134 .It Bq Er EINVAL
 135 Invalid value for
 136 .Fa attr ,
 137 or invalid value for
 138 .Fa protocol .
 139 .El
 140 .Pp
 141 The
 142 .Fn pthread_mutexattr_getprotocol
 143 function will fail if:
 144 .Bl -tag -width Er
 145 .It Bq Er EINVAL
 146 Invalid value for
 147 .Fa attr .
 148 .El
 149 .Pp
 150 The
 151 .Fn pthread_mutexattr_settype
 152 function will fail if:
 153 .Bl -tag -width Er
 154 .It Bq Er EINVAL
 155 Invalid value for
 156 .Fa attr ,
 157 or invalid value for
 158 .Fa type .
 159 .El
 160 .Pp
 161 The
 162 .Fn pthread_mutexattr_gettype
 163 function will fail if:
 164 .Bl -tag -width Er
 165 .It Bq Er EINVAL
 166 Invalid value for
 167 .Fa attr .
 168 .El
 169 .Sh SEE ALSO
 170 .Xr pthread_mutex_init 3
 171 .Sh STANDARDS
 172 The
 173 .Fn pthread_mutexattr_init
 174 and
 175 .Fn pthread_mutexattr_destroy
 176 functions conform to
 177 .St -p1003.1-96 .
 178 .Pp
 179 The
 180 .Fn pthread_mutexattr_setprioceiling ,
 181 .Fn pthread_mutexattr_getprioceiling ,
 182 .Fn pthread_mutexattr_setprotocol ,
 183 .Fn pthread_mutexattr_getprotocol ,
 184 .Fn pthread_mutexattr_settype ,
 185 and
 186 .Fn pthread_mutexattr_gettype
 187 functions conform to
 188 .St -susv2 .