From 7370b57376c64ef47f24f52e87992c763ad681a1 Mon Sep 17 00:00:00 2001 From: "Federico G. Schwindt" Date: Mon, 28 Jan 2002 19:24:04 +0000 Subject: sem_XXX(3) manpages; better now that never. From FreeBSD. --- lib/libc_r/man/Makefile.inc | 15 ++++-- lib/libc_r/man/sem_destroy.3 | 82 ++++++++++++++++++++++++++++++++ lib/libc_r/man/sem_getvalue.3 | 74 +++++++++++++++++++++++++++++ lib/libc_r/man/sem_init.3 | 99 +++++++++++++++++++++++++++++++++++++++ lib/libc_r/man/sem_open.3 | 82 ++++++++++++++++++++++++++++++++ lib/libc_r/man/sem_post.3 | 71 ++++++++++++++++++++++++++++ lib/libc_r/man/sem_wait.3 | 87 ++++++++++++++++++++++++++++++++++ lib/libpthread/man/Makefile.inc | 15 ++++-- lib/libpthread/man/sem_destroy.3 | 82 ++++++++++++++++++++++++++++++++ lib/libpthread/man/sem_getvalue.3 | 74 +++++++++++++++++++++++++++++ lib/libpthread/man/sem_init.3 | 99 +++++++++++++++++++++++++++++++++++++++ lib/libpthread/man/sem_open.3 | 82 ++++++++++++++++++++++++++++++++ lib/libpthread/man/sem_post.3 | 71 ++++++++++++++++++++++++++++ lib/libpthread/man/sem_wait.3 | 87 ++++++++++++++++++++++++++++++++++ 14 files changed, 1014 insertions(+), 6 deletions(-) create mode 100644 lib/libc_r/man/sem_destroy.3 create mode 100644 lib/libc_r/man/sem_getvalue.3 create mode 100644 lib/libc_r/man/sem_init.3 create mode 100644 lib/libc_r/man/sem_open.3 create mode 100644 lib/libc_r/man/sem_post.3 create mode 100644 lib/libc_r/man/sem_wait.3 create mode 100644 lib/libpthread/man/sem_destroy.3 create mode 100644 lib/libpthread/man/sem_getvalue.3 create mode 100644 lib/libpthread/man/sem_init.3 create mode 100644 lib/libpthread/man/sem_open.3 create mode 100644 lib/libpthread/man/sem_post.3 create mode 100644 lib/libpthread/man/sem_wait.3 (limited to 'lib') diff --git a/lib/libc_r/man/Makefile.inc b/lib/libc_r/man/Makefile.inc index a2bebc43b48..b1d5c870444 100644 --- a/lib/libc_r/man/Makefile.inc +++ b/lib/libc_r/man/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.12 2001/12/07 15:47:44 fgsch Exp $ +# $OpenBSD: Makefile.inc,v 1.13 2002/01/28 19:24:03 fgsch Exp $ # $FreeBSD: Makefile.inc,v 1.6 1999/08/28 00:03:02 peter Exp $ # POSIX thread man files @@ -52,10 +52,16 @@ MAN+= \ pthread_single_np.3 \ pthread_suspend_np.3 \ pthread_testcancel.3 + sem_destroy.3 \ + sem_getvalue.3 \ + sem_init.3 \ + sem_open.3 \ + sem_post.3 \ + sem_wait.3 \ MAN+= pthreads.3 \ - flockfile.3 \ sigwait.3 \ + flockfile.3 \ getc_unlocked.3 \ putc_unlocked.3 @@ -84,5 +90,8 @@ MLINKS+=flockfile.3 funlockfile.3 \ pthread_schedparam.3 pthread_getschedparam.3 \ pthread_schedparam.3 pthread_setschedparam.3 \ pthread_testcancel.3 pthread_setcancelstate.3 \ - pthread_testcancel.3 pthread_setcanceltype.3 + pthread_testcancel.3 pthread_setcanceltype.3 \ + sem_open.3 sem_close.3 \ + sem_open.3 sem_unlink.3 \ + sem_wait.3 sem_trywait.3 diff --git a/lib/libc_r/man/sem_destroy.3 b/lib/libc_r/man/sem_destroy.3 new file mode 100644 index 00000000000..57acf57f418 --- /dev/null +++ b/lib/libc_r/man/sem_destroy.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: sem_destroy.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_destroy.3,v 1.9 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_DESTROY 3 +.Os +.Sh NAME +.Nm sem_destroy +.Nd destroy an unnamed semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_destroy "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_destroy +function destroys the unnamed semaphore pointed to by +.Fa sem . +After a successful call to +.Fn sem_destroy , +.Fa sem +is unuseable until re-initialized by another call to +.Fn sem_init . +.Sh RETURN VALUES +.Rv -std sem_destroy +.Sh ERRORS +.Fn sem_destroy +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.It Bq Er EBUSY +There are currently threads blocked on the semaphore that +.Fa sem +points to. +.El +.Sh SEE ALSO +.Xr sem_init 3 +.Sh STANDARDS +.Fn sem_destroy +conforms to +.St -p1003.1-96 . +.Pp +POSIX does not define the behavior of +.Fn sem_destroy +if called while there are threads blocked on +.Fa sem , +but this implementation is guaranteed to return -1 and set +.Va errno +to +.Er EBUSY +if there are threads blocked on +.Fa sem . diff --git a/lib/libc_r/man/sem_getvalue.3 b/lib/libc_r/man/sem_getvalue.3 new file mode 100644 index 00000000000..4b76fddd9ac --- /dev/null +++ b/lib/libc_r/man/sem_getvalue.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: sem_getvalue.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_getvalue.3,v 1.9 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_GETVALUE 3 +.Os +.Sh NAME +.Nm sem_getvalue +.Nd get the value of a semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_getvalue "sem_t *sem" "int *sval" +.Sh DESCRIPTION +The +.Fn sem_getvalue +function sets the variable pointed to by +.Fa sval +to the current value of the semaphore pointed to by +.Fa sem , +as of the time that the call to +.Fn sem_getvalue +is actually run. +.Sh RETURN VALUES +.Rv -std sem_getvalue +.Sh ERRORS +.Fn sem_getvalue +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Sh SEE ALSO +.Xr sem_post 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_getvalue +conforms to +.St -p1003.1-96 . +.Pp +The value of the semaphore is never negative, even if there are threads blocked +on the semaphore. POSIX is somewhat ambiguous in its wording with regard to +what the value of the semaphore should be if there are blocked waiting threads, +but this behavior is conformant, given the wording of the specification. diff --git a/lib/libc_r/man/sem_init.3 b/lib/libc_r/man/sem_init.3 new file mode 100644 index 00000000000..9098d907822 --- /dev/null +++ b/lib/libc_r/man/sem_init.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: sem_init.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_init.3,v 1.11 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_INIT 3 +.Os +.Sh NAME +.Nm sem_init +.Nd initialize an unnamed semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_init "sem_t *sem" "int pshared" "unsigned int value" +.Sh DESCRIPTION +The +.Fn sem_init +function initializes the unnamed semaphore pointed to by +.Fa sem +to have the value +.Fa value . +A non-zero value for +.Fa pshared +specifies a shared semaphore that can be used by multiple processes, which this +implementation is not capable of. +.Pp +Following a successful call to +.Fn sem_init , +.Fa sem +can be used as an argument in subsequent calls to +.Fa sem_wait , +.Fa sem_trywait , +.Fa sem_post , +and +.Fa sem_destroy . +.Fa sem +is no longer valid after a successful call to +.Fa sem_destroy . +.Sh RETURN VALUES +.Rv -std sem_init +.Sh ERRORS +.Fn sem_init +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa value +exceeds SEM_VALUE_MAX. +.It Bq Er ENOSPC +Memory allocation error. +.It Bq Er EPERM +Unable to initialize a shared semaphore. +.El +.Sh SEE ALSO +.Xr sem_destroy 3 , +.Xr sem_post 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_init +conforms to +.St -p1003.1-96 . +.Pp +This implementation does not support shared semaphores, and reports this fact +by setting +.Va errno +to +.Er EPERM . +This is perhaps a stretch of the intention of POSIX, but is +compliant, with the caveat that +.Fn sem_init +always reports a permissions error when an attempt to create a shared semaphore +is made. diff --git a/lib/libc_r/man/sem_open.3 b/lib/libc_r/man/sem_open.3 new file mode 100644 index 00000000000..de447dd4c3e --- /dev/null +++ b/lib/libc_r/man/sem_open.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: sem_open.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_open.3,v 1.7 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_OPEN 3 +.Os +.Sh NAME +.Nm sem_open , +.Nm sem_close , +.Nm sem_unlink +.Nd named semaphore operations +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft sem_t * +.Fn sem_open "const char *name" "int oflag" "..." +.Ft int +.Fn sem_close "sem_t *sem" +.Ft int +.Fn sem_unlink "const char *name" +.Sh DESCRIPTION +The +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +functions are not supported by this implementation. +.Sh RETURN VALUES +.Fn sem_open +returns SEM_FAILED and sets +.Va errno +to indicate an error. +.Fn sem_close +and +.Fn sem_unlink +return -1 and set +.Va errno +to indicate an error. +.Sh ERRORS +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +will fail: +.Bl -tag -width Er +.It Bq Er ENOSYS +Function not supported by this implementation. +.El +.Sh STANDARDS +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +conform to +.St -p1003.1-96 . diff --git a/lib/libc_r/man/sem_post.3 b/lib/libc_r/man/sem_post.3 new file mode 100644 index 00000000000..fb57cc7c125 --- /dev/null +++ b/lib/libc_r/man/sem_post.3 @@ -0,0 +1,71 @@ +.\" $OpenBSD: sem_post.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_post.3,v 1.10 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_POST 3 +.Os +.Sh NAME +.Nm sem_post +.Nd increment (unlock) a semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_post "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_post +function increments (unlocks) the semaphore pointed to by +.Fa sem . +If there are threads blocked on the semaphore when +.Fn sem_post +is called, then the highest priority thread that has been blocked the longest on +the semaphore will be allowed to return from +.Fn sem_wait . +.Pp +.Fn sem_post +is signal-reentrant and may be called within signal handlers. +.Sh RETURN VALUES +.Rv -std sem_post +.Sh ERRORS +.Fn sem_post +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Sh SEE ALSO +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_post +conforms to +.St -p1003.1-96 . diff --git a/lib/libc_r/man/sem_wait.3 b/lib/libc_r/man/sem_wait.3 new file mode 100644 index 00000000000..7df51f07092 --- /dev/null +++ b/lib/libc_r/man/sem_wait.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: sem_wait.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_wait.3,v 1.8 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_WAIT 3 +.Os +.Sh NAME +.Nm sem_wait , +.Nm sem_trywait +.Nd decrement (lock) a semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_wait "sem_t *sem" +.Ft int +.Fn sem_trywait "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_wait +function decrements (locks) the semaphore pointed to by +.Fa sem , +but blocks if the value of +.Fa sem +is zero, until the value is non-zero and the value can be decremented. +.Pp +The +.Fn sem_trywait +function decrements (locks) the semaphore pointed to by +.Fa sem +only if the value is non-zero. Otherwise, the semaphore is not decremented and +an error is returned. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn sem_wait +and +.Fn sem_trywait +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Pp +Additionally, +.Fn sem_trywait +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The semaphore value was zero, and thus could not be decremented. +.El +.Sh SEE ALSO +.Xr sem_post 3 +.Sh STANDARDS +.Fn sem_wait +and +.Fn sem_trywait +conform to +.St -p1003.1-96 . diff --git a/lib/libpthread/man/Makefile.inc b/lib/libpthread/man/Makefile.inc index a2bebc43b48..b1d5c870444 100644 --- a/lib/libpthread/man/Makefile.inc +++ b/lib/libpthread/man/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.12 2001/12/07 15:47:44 fgsch Exp $ +# $OpenBSD: Makefile.inc,v 1.13 2002/01/28 19:24:03 fgsch Exp $ # $FreeBSD: Makefile.inc,v 1.6 1999/08/28 00:03:02 peter Exp $ # POSIX thread man files @@ -52,10 +52,16 @@ MAN+= \ pthread_single_np.3 \ pthread_suspend_np.3 \ pthread_testcancel.3 + sem_destroy.3 \ + sem_getvalue.3 \ + sem_init.3 \ + sem_open.3 \ + sem_post.3 \ + sem_wait.3 \ MAN+= pthreads.3 \ - flockfile.3 \ sigwait.3 \ + flockfile.3 \ getc_unlocked.3 \ putc_unlocked.3 @@ -84,5 +90,8 @@ MLINKS+=flockfile.3 funlockfile.3 \ pthread_schedparam.3 pthread_getschedparam.3 \ pthread_schedparam.3 pthread_setschedparam.3 \ pthread_testcancel.3 pthread_setcancelstate.3 \ - pthread_testcancel.3 pthread_setcanceltype.3 + pthread_testcancel.3 pthread_setcanceltype.3 \ + sem_open.3 sem_close.3 \ + sem_open.3 sem_unlink.3 \ + sem_wait.3 sem_trywait.3 diff --git a/lib/libpthread/man/sem_destroy.3 b/lib/libpthread/man/sem_destroy.3 new file mode 100644 index 00000000000..57acf57f418 --- /dev/null +++ b/lib/libpthread/man/sem_destroy.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: sem_destroy.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_destroy.3,v 1.9 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_DESTROY 3 +.Os +.Sh NAME +.Nm sem_destroy +.Nd destroy an unnamed semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_destroy "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_destroy +function destroys the unnamed semaphore pointed to by +.Fa sem . +After a successful call to +.Fn sem_destroy , +.Fa sem +is unuseable until re-initialized by another call to +.Fn sem_init . +.Sh RETURN VALUES +.Rv -std sem_destroy +.Sh ERRORS +.Fn sem_destroy +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.It Bq Er EBUSY +There are currently threads blocked on the semaphore that +.Fa sem +points to. +.El +.Sh SEE ALSO +.Xr sem_init 3 +.Sh STANDARDS +.Fn sem_destroy +conforms to +.St -p1003.1-96 . +.Pp +POSIX does not define the behavior of +.Fn sem_destroy +if called while there are threads blocked on +.Fa sem , +but this implementation is guaranteed to return -1 and set +.Va errno +to +.Er EBUSY +if there are threads blocked on +.Fa sem . diff --git a/lib/libpthread/man/sem_getvalue.3 b/lib/libpthread/man/sem_getvalue.3 new file mode 100644 index 00000000000..4b76fddd9ac --- /dev/null +++ b/lib/libpthread/man/sem_getvalue.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: sem_getvalue.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_getvalue.3,v 1.9 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_GETVALUE 3 +.Os +.Sh NAME +.Nm sem_getvalue +.Nd get the value of a semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_getvalue "sem_t *sem" "int *sval" +.Sh DESCRIPTION +The +.Fn sem_getvalue +function sets the variable pointed to by +.Fa sval +to the current value of the semaphore pointed to by +.Fa sem , +as of the time that the call to +.Fn sem_getvalue +is actually run. +.Sh RETURN VALUES +.Rv -std sem_getvalue +.Sh ERRORS +.Fn sem_getvalue +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Sh SEE ALSO +.Xr sem_post 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_getvalue +conforms to +.St -p1003.1-96 . +.Pp +The value of the semaphore is never negative, even if there are threads blocked +on the semaphore. POSIX is somewhat ambiguous in its wording with regard to +what the value of the semaphore should be if there are blocked waiting threads, +but this behavior is conformant, given the wording of the specification. diff --git a/lib/libpthread/man/sem_init.3 b/lib/libpthread/man/sem_init.3 new file mode 100644 index 00000000000..9098d907822 --- /dev/null +++ b/lib/libpthread/man/sem_init.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: sem_init.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_init.3,v 1.11 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_INIT 3 +.Os +.Sh NAME +.Nm sem_init +.Nd initialize an unnamed semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_init "sem_t *sem" "int pshared" "unsigned int value" +.Sh DESCRIPTION +The +.Fn sem_init +function initializes the unnamed semaphore pointed to by +.Fa sem +to have the value +.Fa value . +A non-zero value for +.Fa pshared +specifies a shared semaphore that can be used by multiple processes, which this +implementation is not capable of. +.Pp +Following a successful call to +.Fn sem_init , +.Fa sem +can be used as an argument in subsequent calls to +.Fa sem_wait , +.Fa sem_trywait , +.Fa sem_post , +and +.Fa sem_destroy . +.Fa sem +is no longer valid after a successful call to +.Fa sem_destroy . +.Sh RETURN VALUES +.Rv -std sem_init +.Sh ERRORS +.Fn sem_init +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa value +exceeds SEM_VALUE_MAX. +.It Bq Er ENOSPC +Memory allocation error. +.It Bq Er EPERM +Unable to initialize a shared semaphore. +.El +.Sh SEE ALSO +.Xr sem_destroy 3 , +.Xr sem_post 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_init +conforms to +.St -p1003.1-96 . +.Pp +This implementation does not support shared semaphores, and reports this fact +by setting +.Va errno +to +.Er EPERM . +This is perhaps a stretch of the intention of POSIX, but is +compliant, with the caveat that +.Fn sem_init +always reports a permissions error when an attempt to create a shared semaphore +is made. diff --git a/lib/libpthread/man/sem_open.3 b/lib/libpthread/man/sem_open.3 new file mode 100644 index 00000000000..de447dd4c3e --- /dev/null +++ b/lib/libpthread/man/sem_open.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: sem_open.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_open.3,v 1.7 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_OPEN 3 +.Os +.Sh NAME +.Nm sem_open , +.Nm sem_close , +.Nm sem_unlink +.Nd named semaphore operations +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft sem_t * +.Fn sem_open "const char *name" "int oflag" "..." +.Ft int +.Fn sem_close "sem_t *sem" +.Ft int +.Fn sem_unlink "const char *name" +.Sh DESCRIPTION +The +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +functions are not supported by this implementation. +.Sh RETURN VALUES +.Fn sem_open +returns SEM_FAILED and sets +.Va errno +to indicate an error. +.Fn sem_close +and +.Fn sem_unlink +return -1 and set +.Va errno +to indicate an error. +.Sh ERRORS +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +will fail: +.Bl -tag -width Er +.It Bq Er ENOSYS +Function not supported by this implementation. +.El +.Sh STANDARDS +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +conform to +.St -p1003.1-96 . diff --git a/lib/libpthread/man/sem_post.3 b/lib/libpthread/man/sem_post.3 new file mode 100644 index 00000000000..fb57cc7c125 --- /dev/null +++ b/lib/libpthread/man/sem_post.3 @@ -0,0 +1,71 @@ +.\" $OpenBSD: sem_post.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_post.3,v 1.10 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_POST 3 +.Os +.Sh NAME +.Nm sem_post +.Nd increment (unlock) a semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_post "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_post +function increments (unlocks) the semaphore pointed to by +.Fa sem . +If there are threads blocked on the semaphore when +.Fn sem_post +is called, then the highest priority thread that has been blocked the longest on +the semaphore will be allowed to return from +.Fn sem_wait . +.Pp +.Fn sem_post +is signal-reentrant and may be called within signal handlers. +.Sh RETURN VALUES +.Rv -std sem_post +.Sh ERRORS +.Fn sem_post +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Sh SEE ALSO +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_post +conforms to +.St -p1003.1-96 . diff --git a/lib/libpthread/man/sem_wait.3 b/lib/libpthread/man/sem_wait.3 new file mode 100644 index 00000000000..7df51f07092 --- /dev/null +++ b/lib/libpthread/man/sem_wait.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: sem_wait.3,v 1.1 2002/01/28 19:24:03 fgsch Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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: src/lib/libc_r/man/sem_wait.3,v 1.8 2001/10/01 16:09:09 ru Exp $ +.Dd February 15, 2000 +.Dt SEM_WAIT 3 +.Os +.Sh NAME +.Nm sem_wait , +.Nm sem_trywait +.Nd decrement (lock) a semaphore +.\" .Sh LIBRARY +.\" .Lb libc_r +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_wait "sem_t *sem" +.Ft int +.Fn sem_trywait "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_wait +function decrements (locks) the semaphore pointed to by +.Fa sem , +but blocks if the value of +.Fa sem +is zero, until the value is non-zero and the value can be decremented. +.Pp +The +.Fn sem_trywait +function decrements (locks) the semaphore pointed to by +.Fa sem +only if the value is non-zero. Otherwise, the semaphore is not decremented and +an error is returned. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn sem_wait +and +.Fn sem_trywait +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Pp +Additionally, +.Fn sem_trywait +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The semaphore value was zero, and thus could not be decremented. +.El +.Sh SEE ALSO +.Xr sem_post 3 +.Sh STANDARDS +.Fn sem_wait +and +.Fn sem_trywait +conform to +.St -p1003.1-96 . -- cgit v1.2.3