libpthread-218.1.3.tar.gz

[apple/libpthread.git] / man / pthread_mutexattr.3

diff --git a/man/pthread_mutexattr.3 b/man/pthread_mutexattr.3
index 9f6ac0cbc65a156a35b6d30308bb7e665943214d..13e0861e834db636571c007cada52badbc9512dd 100644 (file)
--- a/man/pthread_mutexattr.3
+++ b/man/pthread_mutexattr.3
@@ -1,6 +1,6 @@
-.\" $NetBSD: pthread_mutexattr.3,v 1.3 2003/07/04 08:36:06 wiz Exp $
+.\" $NetBSD: pthread_mutexattr.3,v 1.11 2010/07/08 22:46:34 jruoho Exp $

 .\"
 .\"

-.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc.

 .\" All rights reserved.
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" All rights reserved.
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions


@@ -10,9 +10,6 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.

-.\" 3. Neither the name of The NetBSD Foundation nor the names of its
-.\"    contributors may be used to endorse or promote products derived
-.\"    from this software without specific prior written permission.

 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR


@@ -52,90 +49,51 @@
 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"

-.\" $FreeBSD: src/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $
-.Dd January 30, 2003
+.\" $FreeBSD$
+.Dd July 9, 2010

 .Dt PTHREAD_MUTEXATTR 3
 .Os
 .Sh NAME
 .Dt PTHREAD_MUTEXATTR 3
 .Os
 .Sh NAME

-.Nm pthread_mutexattr_destroy ,
-.Nm pthread_mutexattr_getprioceiling ,
-.Nm pthread_mutexattr_getprotocol ,
-.Nm pthread_mutexattr_gettype ,

 .Nm pthread_mutexattr_init ,
 .Nm pthread_mutexattr_init ,

+.Nm pthread_mutexattr_destroy ,

 .Nm pthread_mutexattr_setprioceiling ,
 .Nm pthread_mutexattr_setprioceiling ,

+.Nm pthread_mutexattr_getprioceiling ,

 .Nm pthread_mutexattr_setprotocol ,
 .Nm pthread_mutexattr_setprotocol ,

-.Nm pthread_mutexattr_settype
+.Nm pthread_mutexattr_getprotocol ,
+.Nm pthread_mutexattr_settype ,
+.Nm pthread_mutexattr_gettype

 .Nd mutex attribute operations
 .Sh SYNOPSIS
 .Nd mutex attribute operations
 .Sh SYNOPSIS

-.Fd #include <pthread.h>
+.In pthread.h

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_destroy
-.Fa "pthread_mutexattr_t *attr"
-.Fc
+.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_getprioceiling
-.Fa "const pthread_mutexattr_t *restrict attr"
-.Fa "int *restrict prioceiling"
-.Fc
-.\" To match the SUS, this should be:
-.\" .Ft int
-.\" .Fo pthread_mutexattr_getprioceiling
-.\" .Fa "pthread_mutexattr_t *restrict attr"
-.\" .Fa "int *restrict prioceiling"
-.\" .Fc
+.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_getprotocol
-.Fa "const pthread_mutexattr_t *restrict attr"
-.Fa "int *restrict protocol"
-.Fc
-.\" To match the SUS, this should be:
-.\" .Ft int
-.\" .Fo pthread_mutexattr_getprotocol
-.\" .Fa "pthread_mutexattr_t *restrict attr"
-.\" .Fa "int *restrict protocol"
-.\" .Fc
+.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_gettype
-.Fa "const pthread_mutexattr_t *restrict attr"
-.Fa "int *restrict type"
-.Fc
-.\" To match the SUS, this should be:
-.\" .Ft int
-.\" .Fo pthread_mutexattr_gettype
-.\" .Fa "pthread_mutexattr_t *restrict attr"
-.\" .Fa "int *restrict type"
-.\" .Fc
+.Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling"

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_init
-.Fa "pthread_mutexattr_t *attr"
-.Fc
+.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_setprioceiling
-.Fa "pthread_mutexattr_t *attr"
-.Fa "int prioceiling"
-.Fc
+.Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_setprotocol
-.Fa "pthread_mutexattr_t *attr"
-.Fa "int protocol"
-.Fc
+.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"

 .Ft int
 .Ft int

-.Fo pthread_mutexattr_settype
-.Fa "pthread_mutexattr_t *attr"
-.Fa "int type"
-.Fc
+.Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"

 .Sh DESCRIPTION
 Mutex attributes are used to specify parameters to
 .Fn pthread_mutex_init .
 .Sh DESCRIPTION
 Mutex attributes are used to specify parameters to
 .Fn pthread_mutex_init .

-One attribute object can be used in multiple calls to
-.Fn pthread_mutex_init ,
+Like with thread attributes,
+one attribute object can be used in multiple calls to
+.Xr pthread_mutex_init 3 ,

 with or without modifications between calls.
 .Pp
 The
 .Fn pthread_mutexattr_init
 function initializes
 .Fa attr
 with or without modifications between calls.
 .Pp
 The
 .Fn pthread_mutexattr_init
 function initializes
 .Fa attr

-with all of the default mutex attributes.
+with all the default mutex attributes.

 .Pp
 The
 .Fn pthread_mutexattr_destroy
 .Pp
 The
 .Fn pthread_mutexattr_destroy


@@ -144,60 +102,63 @@ function destroys
 .Pp
 The
 .Fn pthread_mutexattr_settype
 .Pp
 The
 .Fn pthread_mutexattr_settype

-function sets the mutex type value of the attribute.  Valid mutex types are:
-.Dv PTHREAD_MUTEX_NORMAL ,
-.Dv PTHREAD_MUTEX_ERRORCHECK ,
-.Dv PTHREAD_MUTEX_RECURSIVE ,
-and
-.Dv PTHREAD_MUTEX_DEFAULT .
-The default mutex type for
-.Fn pthread_mutexattr_init
-is
-.Dv PTHREAD_MUTEX_DEFAULT .
-.Pp
-.Dv PTHREAD_MUTEX_NORMAL
-mutexes do not check for usage errors.
-.Dv PTHREAD_MUTEX_NORMAL
-mutexes will deadlock if reentered, and result in undefined behavior if a
-locked mutex is unlocked by another thread.  Attempts to unlock an already
-unlocked
+functions set the mutex
+.Fa type
+value of the attribute.
+Valid mutex types are:
+.Bl -tag -width "XXX" -offset 2n
+.It Dv PTHREAD_MUTEX_NORMAL
+This type of mutex does not check for usage errors.
+It will deadlock if reentered, and result in undefined behavior if a
+locked mutex is unlocked by another thread.
+Attempts to unlock an already unlocked

 .Dv PTHREAD_MUTEX_NORMAL
 mutex will result in undefined behavior.
 .Dv PTHREAD_MUTEX_NORMAL
 mutex will result in undefined behavior.

-.Pp
-.Dv PTHREAD_MUTEX_ERRORCHECK
-mutexes do check for usage errors.
+.It Dv PTHREAD_MUTEX_ERRORCHECK
+These mutexes do check for usage errors.

 If an attempt is made to relock a
 .Dv PTHREAD_MUTEX_ERRORCHECK
 mutex without first dropping the lock, an error will be returned.
 If a thread attempts to unlock a
 .Dv PTHREAD_MUTEX_ERRORCHECK
 If an attempt is made to relock a
 .Dv PTHREAD_MUTEX_ERRORCHECK
 mutex without first dropping the lock, an error will be returned.
 If a thread attempts to unlock a
 .Dv PTHREAD_MUTEX_ERRORCHECK

-mutex that is locked by another thread, an error will be returned.  If a
-thread attempts to unlock a
+mutex that is locked by another thread, an error will be returned.
+If a thread attempts to unlock a

 .Dv PTHREAD_MUTEX_ERRORCHECK
 thread that is unlocked, an error will be returned.
 .Dv PTHREAD_MUTEX_ERRORCHECK
 thread that is unlocked, an error will be returned.

-.Pp
-.Dv PTHREAD_MUTEX_RECURSIVE
-mutexes allow recursive locking.
+.It Dv PTHREAD_MUTEX_RECURSIVE
+These mutexes allow recursive locking.

 An attempt to relock a
 .Dv PTHREAD_MUTEX_RECURSIVE
 An attempt to relock a
 .Dv PTHREAD_MUTEX_RECURSIVE

-mutex that is already locked by the same thread succeeds.  An equivalent
-number of
+mutex that is already locked by the same thread succeeds.
+An equivalent number of

 .Xr pthread_mutex_unlock 3
 .Xr pthread_mutex_unlock 3

-calls are needed before the mutex will wake another thread waiting on this
-lock.  If a thread attempts to unlock a
+calls are needed before the mutex will wake another thread waiting
+on this lock.
+If a thread attempts to unlock a

 .Dv PTHREAD_MUTEX_RECURSIVE
 .Dv PTHREAD_MUTEX_RECURSIVE

-mutex that is locked by another thread, an error will be returned.  If a thread attemps to unlock a
+mutex that is locked by another thread, an error will be returned.
+If a thread attempts to unlock a

 .Dv PTHREAD_MUTEX_RECURSIVE
 thread that is unlocked, an error will be returned.
 .Pp
 .Dv PTHREAD_MUTEX_RECURSIVE
 thread that is unlocked, an error will be returned.
 .Pp

-.Dv PTHREAD_MUTEX_DEFAULT
-mutexes result in undefined behavior if reentered.
+It is advised that
+.Dv PTHREAD_MUTEX_RECURSIVE
+mutexes are not used with condition variables.
+This is because of the implicit unlocking done by
+.Xr pthread_cond_wait 3
+and
+.Xr pthread_cond_timedwait 3 .
+.It Dv PTHREAD_MUTEX_DEFAULT
+Also this type of mutex will cause undefined behavior if reentered.

 Unlocking a
 .Dv PTHREAD_MUTEX_DEFAULT
 Unlocking a
 .Dv PTHREAD_MUTEX_DEFAULT

-mutex locked by another thread will result in undefined behavior.  Attempts to unlock an already
-unlocked
+mutex locked by another thread will result in undefined behavior.
+Attempts to unlock an already unlocked

 .Dv PTHREAD_MUTEX_DEFAULT
 mutex will result in undefined behavior.
 .Dv PTHREAD_MUTEX_DEFAULT
 mutex will result in undefined behavior.

+This is the default mutex type for
+.Fn pthread_mutexaddr_init .
+.El

 .Pp
 .Fn pthread_mutexattr_gettype
 functions copy the type value of the attribute to the location pointed to by the second parameter.
 .Pp
 .Fn pthread_mutexattr_gettype
 functions copy the type value of the attribute to the location pointed to by the second parameter.


@@ -214,23 +175,26 @@ to the location pointed to by the second function parameter.
 If successful, these functions return 0.
 Otherwise, an error number is returned to indicate the error.
 .Sh ERRORS
 If successful, these functions return 0.
 Otherwise, an error number is returned to indicate the error.
 .Sh ERRORS

+The

 .Fn pthread_mutexattr_init
 .Fn pthread_mutexattr_init

-will fail if:
+function shall fail if:

 .Bl -tag -width Er
 .It Bq Er ENOMEM
 Out of memory.
 .El
 .Pp
 .Bl -tag -width Er
 .It Bq Er ENOMEM
 Out of memory.
 .El
 .Pp

+The

 .Fn pthread_mutexattr_destroy
 .Fn pthread_mutexattr_destroy

-will fail if:
+function will fail if:

 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Fa attr .
 .El
 .Pp
 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Fa attr .
 .El
 .Pp

+The

 .Fn pthread_mutexattr_setprioceiling
 .Fn pthread_mutexattr_setprioceiling

-will fail if:
+function will fail if:

 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for


@@ -239,16 +203,18 @@ or invalid value for
 .Fa prioceiling .
 .El
 .Pp
 .Fa prioceiling .
 .El
 .Pp

+The

 .Fn pthread_mutexattr_getprioceiling
 .Fn pthread_mutexattr_getprioceiling

-will fail if:
+function will fail if:

 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Fa attr .
 .El
 .Pp
 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Fa attr .
 .El
 .Pp

+The

 .Fn pthread_mutexattr_setprotocol
 .Fn pthread_mutexattr_setprotocol

-will fail if:
+function will fail if:

 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for


@@ -257,26 +223,30 @@ or invalid value for
 .Fa protocol .
 .El
 .Pp
 .Fa protocol .
 .El
 .Pp

+The

 .Fn pthread_mutexattr_getprotocol
 .Fn pthread_mutexattr_getprotocol

-will fail if:
+function will fail if:

 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Fa attr .
 .El
 .Pp
 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Fa attr .
 .El
 .Pp

+The

 .Fn pthread_mutexattr_settype
 .Fn pthread_mutexattr_settype

-will fail if:
+function shall fail if:

 .Bl -tag -width Er
 .It Bq Er EINVAL
 .Bl -tag -width Er
 .It Bq Er EINVAL

-Invalid value for
-.Fa attr ,
-or invalid value for
-.Fa type .
+The value specified either by
+.Fa type
+or
+.Fa attr
+is invalid.

 .El
 .Pp
 .El
 .Pp

+The

 .Fn pthread_mutexattr_gettype
 .Fn pthread_mutexattr_gettype

-will fail if:
+function will fail if:

 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for
 .Bl -tag -width Er
 .It Bq Er EINVAL
 Invalid value for


@@ -285,12 +255,14 @@ Invalid value for
 .Sh SEE ALSO
 .Xr pthread_mutex_init 3
 .Sh STANDARDS
 .Sh SEE ALSO
 .Xr pthread_mutex_init 3
 .Sh STANDARDS

+The

 .Fn pthread_mutexattr_init
 and
 .Fn pthread_mutexattr_destroy
 .Fn pthread_mutexattr_init
 and
 .Fn pthread_mutexattr_destroy

-conform to
+functions conform to

 .St -p1003.1-96
 .Pp
 .St -p1003.1-96
 .Pp

+The

 .Fn pthread_mutexattr_setprioceiling ,
 .Fn pthread_mutexattr_getprioceiling ,
 .Fn pthread_mutexattr_setprotocol ,
 .Fn pthread_mutexattr_setprioceiling ,
 .Fn pthread_mutexattr_getprioceiling ,
 .Fn pthread_mutexattr_setprotocol ,


@@ -298,5 +270,5 @@ conform to
 .Fn pthread_mutexattr_settype ,
 and
 .Fn pthread_mutexattr_gettype
 .Fn pthread_mutexattr_settype ,
 and
 .Fn pthread_mutexattr_gettype

-conform to
+functions conform to

 .St -susv2
 .St -susv2