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/lib/libc_r/man/pthread_mutexattr.3,v 1.2.2.7 2002/12/29 16:35:35 schweikh Exp $
  29 .\" $DragonFly: src/lib/libc_r/man/pthread_mutexattr.3,v 1.2 2003/06/17 04:26:48 dillon Exp $
  30 .Dd April 15, 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 .Fn pthread_mutexattr_init
  94 will fail if:
  95 .Bl -tag -width Er
  96 .It Bq Er ENOMEM
  97 Out of memory.
  98 .El
  99 .Pp
 100 .Fn pthread_mutexattr_destroy
 101 will fail if:
 102 .Bl -tag -width Er
 103 .It Bq Er EINVAL
 104 Invalid value for
 105 .Fa attr .
 106 .El
 107 .Pp
 108 .Fn pthread_mutexattr_setprioceiling
 109 will fail if:
 110 .Bl -tag -width Er
 111 .It Bq Er EINVAL
 112 Invalid value for
 113 .Fa attr ,
 114 or invalid value for
 115 .Fa prioceiling .
 116 .El
 117 .Pp
 118 .Fn pthread_mutexattr_getprioceiling
 119 will fail if:
 120 .Bl -tag -width Er
 121 .It Bq Er EINVAL
 122 Invalid value for
 123 .Fa attr .
 124 .El
 125 .Pp
 126 .Fn pthread_mutexattr_setprotocol
 127 will fail if:
 128 .Bl -tag -width Er
 129 .It Bq Er EINVAL
 130 Invalid value for
 131 .Fa attr ,
 132 or invalid value for
 133 .Fa protocol .
 134 .El
 135 .Pp
 136 .Fn pthread_mutexattr_getprotocol
 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 .Fn pthread_mutexattr_settype
 145 will fail if:
 146 .Bl -tag -width Er
 147 .It Bq Er EINVAL
 148 Invalid value for
 149 .Fa attr ,
 150 or invalid value for
 151 .Fa type .
 152 .El
 153 .Pp
 154 .Fn pthread_mutexattr_gettype
 155 will fail if:
 156 .Bl -tag -width Er
 157 .It Bq Er EINVAL
 158 Invalid value for
 159 .Fa attr .
 160 .El
 161 .Sh SEE ALSO
 162 .Xr pthread_mutex_init 3
 163 .Sh STANDARDS
 164 .Fn pthread_mutexattr_init
 165 and
 166 .Fn pthread_mutexattr_destroy
 167 conform to
 168 .St -p1003.1-96
 169 .Pp
 170 .Fn pthread_mutexattr_setprioceiling ,
 171 .Fn pthread_mutexattr_getprioceiling ,
 172 .Fn pthread_mutexattr_setprotocol ,
 173 .Fn pthread_mutexattr_getprotocol ,
 174 .Fn pthread_mutexattr_settype ,
 175 and
 176 .Fn pthread_mutexattr_gettype
 177 conform to
 178 .St -susv2