Merge pthread_mutex_trylock(3) into pthread_mutex_lock(3) and document

pthread_mutex_timedlock() in that same page

ok fgsch@, brad@, as well as jmc@, who also fixed a bunch of nits

3 files changed, 108 insertions, 90 deletions

diff --git a/lib/libpthread/man/Makefile.inc b/lib/libpthread/man/Makefile.inc
index 9ea0ea7317c..6045248c2d2 100644
--- a/lib/libpthread/man/Makefile.inc
+++ b/lib/libpthread/man/Makefile.inc
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile.inc,v 1.26 2010/11/07 20:18:22 deraadt Exp $
+# $OpenBSD: Makefile.inc,v 1.27 2012/02/24 04:58:22 guenther Exp $
 # $FreeBSD: Makefile.inc,v 1.6 1999/08/28 00:03:02 peter Exp $
 
 # POSIX thread man files
@@ -37,7 +37,6 @@ MAN+=	\
 	pthread_mutex_destroy.3 \
 	pthread_mutex_init.3 \
 	pthread_mutex_lock.3 \
-	pthread_mutex_trylock.3 \
 	pthread_mutex_unlock.3 \
 	pthread_once.3 \
 	pthread_rwlock_destroy.3 \
@@ -91,6 +90,8 @@ MLINKS+=flockfile.3 funlockfile.3 \
 	pthread_attr_setstacksize.3 pthread_attr_getstacksize.3 \
 	pthread_attr_setguardsize.3 pthread_attr_getguardsize.3 \
 	pthread_attr_setdetachstate.3 pthread_attr_getdetachstate.3 \
+	pthread_mutex_lock.3 pthread_mutex_timedlock.3 \
+	pthread_mutex_lock.3 pthread_mutex_trylock.3 \
 	pthread_mutexattr.3 pthread_mutexattr_init.3 \
 	pthread_mutexattr.3 pthread_mutexattr_destroy.3 \
 	pthread_mutexattr.3 pthread_mutexattr_getprioceiling.3 \
diff --git a/lib/libpthread/man/pthread_mutex_lock.3 b/lib/libpthread/man/pthread_mutex_lock.3
index 3c9226ebe8f..22c9a909025 100644
--- a/lib/libpthread/man/pthread_mutex_lock.3
+++ b/lib/libpthread/man/pthread_mutex_lock.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pthread_mutex_lock.3,v 1.9 2007/07/26 08:03:05 jmc Exp $
+.\" $OpenBSD: pthread_mutex_lock.3,v 1.10 2012/02/24 04:58:22 guenther Exp $
 .\"
 .\" Copyright (c) 1997 Brian Cully <shmit@kublai.com>
 .\" All rights reserved.
@@ -29,46 +29,138 @@
 .\"
 .\" $FreeBSD: pthread_mutex_lock.3,v 1.5 1999/08/28 00:03:07 peter Exp $
 .\"
-.Dd $Mdocdate: July 26 2007 $
+.Dd $Mdocdate: February 24 2012 $
 .Dt PTHREAD_MUTEX_LOCK 3
 .Os
 .Sh NAME
-.Nm pthread_mutex_lock
+.Nm pthread_mutex_lock ,
+.Nm pthread_mutex_timedlock ,
+.Nm pthread_mutex_trylock
 .Nd lock a mutex
 .Sh SYNOPSIS
 .Fd #include <pthread.h>
 .Ft int
 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
+.Ft int
+.Fn pthread_mutex_timedlock "pthread_mutex_t *mutex" "const struct timespec *abstime"
+.Ft int
+.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 .Sh DESCRIPTION
 The
 .Fn pthread_mutex_lock
 function locks
 .Fa mutex .
-If the mutex is already locked, the calling thread will block until the
+If the mutex is currently locked by another thread,
+the calling thread will block until the
 mutex becomes available.
+.Pp
+If the mutex is currently locked by the calling thread,
+then the behavior depends on the type of the mutex.
+If
+.Fa mutex
+is of type
+.Dv PTHREAD_MUTEX_NORMAL ,
+then the calling thread will deadlock and never return from
+.Fn pthread_mutex_lock .
+If
+.Fa mutex
+is of type
+.Dv PTHREAD_MUTEX_ERRORCHECK ,
+then
+.Er EDEADLK
+is immediately returned.
+If
+.Fa mutex
+is of type
+.Dv PTHREAD_MUTEX_RECURSIVE ,
+then the recursion count on the mutex is incremented.
+.Pp
+The
+.Fn pthread_mutex_timedlock
+function locks
+.Fa mutex
+like
+.Fn pthread_mutex_lock
+except that it will not block or deadlock past the system time
+specified in
+.Fa abstime .
+If that time is reached without being able to lock
+.Fa mutex ,
+then it returns
+.Er ETIMEDOUT .
+.Pp
+The
+.Fn pthread_mutex_trylock
+function locks
+.Fa mutex
+like
+.Fn pthread_mutex_lock
+except that if
+.Fa mutex
+is locked by another thread,
+or is locked by the calling thread and is not of type
+.Dv PTHREAD_MUTEX_RECURSIVE ,
+then it will immediately return
+.Er EBUSY .
 .Sh RETURN VALUES
 If successful,
-.Fn pthread_mutex_lock
+.Fn pthread_mutex_lock ,
+.Fn pthread_mutex_timedlock ,
+and
+.Fn pthread_mutex_trylock
 will return zero, otherwise an error number will be returned to
 indicate the error.
 .Sh ERRORS
-.Fn pthread_mutex_lock
+.Fn pthread_mutex_lock ,
+.Fn pthread_mutex_timedlock ,
+and
+.Fn pthread_mutex_trylock
 will fail if:
 .Bl -tag -width Er
 .It Bq Er EINVAL
 The value specified by
 .Fa mutex
 is invalid.
+.It Bq Er EAGAIN
+The mutex is of type
+.Dv PTHREAD_MUTEX_RECURSIVE
+and the maximum recursion count has been reached.
+.El
+.Pp
+In addition,
+.Fn pthread_mutex_lock
+and
+.Fn pthread_mutex_timedlock
+may return the following error:
+.Bl -tag -width Er
 .It Bq Er EDEADLK
-A deadlock would occur if the thread blocked waiting for
-.Fa mutex .
+The mutex is of type
+.Dv PTHREAD_MUTEX_ERRORCHECK
+and is already locked by the calling thread.
+.El
+.Pp
+.Fn pthread_mutex_timedlock
+may return the following error:
+.Bl -tag -width Er
+.It Bq Er ETIMEDOUT
+The mutex could not be locked and the specified time was reached.
+.El
+.Pp
+.Fn pthread_mutex_trylock
+may return the following error:
+.Bl -tag -width Er
+.It Bq Er EBUSY
+The mutex could not be locked because it was already locked.
 .El
 .Sh SEE ALSO
 .Xr pthread_mutex_destroy 3 ,
 .Xr pthread_mutex_init 3 ,
-.Xr pthread_mutex_trylock 3 ,
-.Xr pthread_mutex_unlock 3
+.Xr pthread_mutex_unlock 3 ,
+.Xr pthread_mutexattr_settype 3
 .Sh STANDARDS
-.Fn pthread_mutex_lock
-conforms to
-.St -p1003.1-96 .
+.Fn pthread_mutex_lock ,
+.Fn pthread_mutex_timedlock ,
+and
+.Fn pthread_mutex_trylock
+conform to
+.St -p1003.1-2008 .
diff --git a/lib/libpthread/man/pthread_mutex_trylock.3 b/lib/libpthread/man/pthread_mutex_trylock.3
deleted file mode 100644
index 6b21f030f56..00000000000
--- a/lib/libpthread/man/pthread_mutex_trylock.3
+++ /dev/null
@@ -1,75 +0,0 @@
-.\" $OpenBSD: pthread_mutex_trylock.3,v 1.8 2007/05/31 19:19:37 jmc Exp $
-.\"
-.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com>
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 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 author nor the names of any co-contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\" $FreeBSD: pthread_mutex_trylock.3,v 1.5 1999/08/28 00:03:08 peter Exp $
-.\"
-.Dd $Mdocdate: May 31 2007 $
-.Dt PTHREAD_MUTEX_TRYLOCK 3
-.Os
-.Sh NAME
-.Nm pthread_mutex_trylock
-.Nd attempt to lock a mutex without blocking
-.Sh SYNOPSIS
-.Fd #include <pthread.h>
-.Ft int
-.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
-.Sh DESCRIPTION
-The
-.Fn pthread_mutex_trylock
-function locks
-.Fa mutex .
-If the mutex is already locked,
-.Fn pthread_mutex_trylock
-will not block waiting for the mutex, but will return an error condition.
-.Sh RETURN VALUES
-If successful,
-.Fn pthread_mutex_trylock
-will return zero, otherwise an error number will be returned to
-indicate the error.
-.Sh ERRORS
-.Fn pthread_mutex_trylock
-will fail if:
-.Bl -tag -width Er
-.It Bq Er EINVAL
-The value specified by
-.Fa mutex
-is invalid.
-.It Bq Er EBUSY
-.Fa mutex
-is already locked.
-.El
-.Sh SEE ALSO
-.Xr pthread_mutex_destroy 3 ,
-.Xr pthread_mutex_init 3 ,
-.Xr pthread_mutex_lock 3 ,
-.Xr pthread_mutex_unlock 3
-.Sh STANDARDS
-.Fn pthread_mutex_trylock
-conforms to
-.St -p1003.1-96 .