Add manual for function sem_timedwait().

Reviewed by: ru, deischen

2 files changed, 123 insertions, 1 deletions

diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index ea4366295a82..968b318c5f7f 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/lib/libc/gen/Makefile.inc
@@ -59,7 +59,7 @@ MAN+=	alarm.3 arc4random.3 \
 	nice.3 nlist.3 pause.3 popen.3 pselect.3 psignal.3 pwcache.3 \
 	raise.3 rand48.3 readpassphrase.3 rfork_thread.3 \
 	scandir.3 sem_destroy.3 sem_getvalue.3 sem_init.3 \
-	sem_open.3 sem_post.3 sem_wait.3 \
+	sem_open.3 sem_post.3 sem_timedwait.3 sem_wait.3 \
 	setjmp.3 setmode.3 setproctitle.3 \
 	siginterrupt.3 signal.3 sigsetops.3 sleep.3 \
 	statvfs.3 stringlist.3 \
diff --git a/lib/libc/gen/sem_timedwait.3 b/lib/libc/gen/sem_timedwait.3
new file mode 100644
index 000000000000..9481c90802d7
--- /dev/null
+++ b/lib/libc/gen/sem_timedwait.3
@@ -0,0 +1,122 @@
+.\" Copyright (c) 2008, David Xu <davidxu@freebsd.org> 
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
+.\"
+.\" Portions of this text are reprinted and reproduced in electronic form
+.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
+.\" Portable Operating System Interface (POSIX), The Open Group Base
+.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
+.\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
+.\" event of any discrepancy between this version and the original IEEE and
+.\" The Open Group Standard, the original IEEE and The Open Group Standard is
+.\" the referee document.  The original Standard can be obtained online at
+.\"	http://www.opengroup.org/unix/online.html.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd March 3, 2008
+.Dt SEM_TIMEDWAIT 3
+.Os
+.Sh NAME
+.Nm sem_timedwait
+.Nd "lock a semaphore"
+.Sh LIBRARY
+.Lb libpthread
+.Sh SYNOPSIS
+.In semaphore.h
+.Ft int
+.Fn sem_timedwait "sem_t *sem" "const struct timespec *abs_timeout"
+.Sh DESCRIPTION
+The
+.Fn sem_timedwait
+function locks the semaphore referenced by
+.Fa sem ,
+as in the
+.Xr sem_wait 3
+function.
+However, if the semaphore cannot be locked without waiting for
+another process or thread to unlock the semaphore by performing
+a
+.Xr sem_post 3
+function, this wait will be terminated when the specified timeout expires.
+.Pp
+The timeout will expire when the absolute time specified by
+.Fa abs_timeout
+passes, as measured by the clock on which timeouts are based (that is,
+when the value of that clock equals or exceeds
+.Fa abs_timeout ) ,
+or if the
+absolute time specified by
+.Fa abs_timeout
+has already been passed at the time of the call.
+.Pp
+Note that the timeout is based on the
+.Dv CLOCK_REALTIME
+clock.
+.Pp
+The validity of the
+.Fa abs_timeout
+is not checked if the semaphore can be locked immediately.
+.Sh RETURN VALUES
+The
+.Fn sem_timedwait
+function returns zero if the calling process successfully performed the
+semaphore lock operation on the semaphore designated by
+.Fa sem .
+If the call was unsuccessful, the state of the semaphore is unchanged,
+and the function returns a value of \-1 and sets the global variable
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn sem_timedwait
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The
+.Fa sem
+argument does not refer to a valid semaphore, or the process or thread would
+have blocked, and the
+.Fa abs_timeout
+parameter specified a nanoseconds field value less than zero or greater than
+or equal to 1000 million.
+.It Bq Er ETIMEDOUT
+The semaphore could not be locked before the specified timeout expired.
+.It Bq Er EINTR
+A signal interrupted this function.
+.El
+.Sh SEE ALSO
+.Xr semctl 2 ,
+.Xr semget 2 ,
+.Xr semop 2
+.Xr sem_post 3 ,
+.Xr sem_trywait 3 ,
+.Xr sem_wait 3
+.Sh STANDARDS
+The
+.Fn sem_timedwait
+function conforms to
+.St -p1003.1-2004 .
+.Sh HISTORY
+The function first appeared in 
+.Fx 5.0 .