mirror/freebsd
1
0
Fork 0
mirror of https://git.FreeBSD.org/src.git synced 2025-01-06 13:09:50 +00:00
Code Issues Releases Activity

Add man pages for the sem_*() functions.

Browse Source 
Approved by:	jkh
This commit is contained in:
Jason Evans 2000-02-16 19:31:53 +00:00
parent 945111e5a7
commit b0a1b4f809
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=57260
20 changed files with 1535 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
lib/libc/gen/sem_destroy.3 Normal file
View File

@ -0,0 +1,83 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_DESTROY 3
.Os
.Sh NAME
.Nm sem_destroy
.Nd destroy an unnamed semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_destroy
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.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 EBUSY if there are threads blocked on
.Fa sem .

77
lib/libc/gen/sem_getvalue.3 Normal file
View File

@ -0,0 +1,77 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_GETVALUE 3
.Os
.Sh NAME
.Nm sem_getvalue
.Nd get the value of a semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_getvalue
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3
.Sh STANDARDS
.Fn sem_getvalue
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.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.

100
lib/libc/gen/sem_init.3 Normal file
View File

@ -0,0 +1,100 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_INIT 3
.Os
.Sh NAME
.Nm sem_init
.Nd initialize an unnamed semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_init
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3 ,
.Xr sem_post 3 ,
.Xr sem_destroy
.Sh STANDARDS
.Fn sem_init
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.Pp
This implementation does not support shared semaphores, and reports this fact
by setting
.Va errno
to 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.

80
lib/libc/gen/sem_open.3 Normal file
View File

@ -0,0 +1,80 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.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 SYNOPSIS
.Fd #include <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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

71
lib/libc/gen/sem_post.3 Normal file
View File

@ -0,0 +1,71 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_POST 3
.Os
.Sh NAME
.Nm sem_post
.Nd increment (unlock) a semaphore
.Sh SYNOPSIS
.Fd #include <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 .
.Sh RETURN VALUES
If successful,
.Fn sem_post
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3
.Sh STANDARDS
.Fn sem_post
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

92
lib/libc/gen/sem_wait.3 Normal file
View File

@ -0,0 +1,92 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_WAIT 3
.Os
.Sh NAME
.Nm sem_wait ,
.Nm sem_trywait
.Nd decrement (lock) a semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_wait
and
.Fn sem_trywait
return 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

17
lib/libc_r/man/Makefile.inc
View File

@ -4,7 +4,8 @@
.PATH: ${.CURDIR}/man
MAN3+= pthread_cleanup_pop.3 \
MAN3+= pthread_cancel.3 \
pthread_cleanup_pop.3 \
pthread_cleanup_push.3 \
pthread_cond_broadcast.3 \
pthread_cond_destroy.3 \
@ -12,7 +13,6 @@ MAN3+= pthread_cleanup_pop.3 \
pthread_cond_signal.3 \
pthread_cond_timedwait.3 \
pthread_cond_wait.3 \
pthread_cancel.3 \
pthread_create.3 \
pthread_detach.3 \
pthread_equal.3 \
@ -38,7 +38,16 @@ MAN3+= pthread_cleanup_pop.3 \
pthread_rwlockattr_setpshared.3 \
pthread_self.3 \
pthread_setspecific.3 \
pthread_testcancel.3
pthread_testcancel.3 \
sem_destroy.3 \
sem_getvalue.3 \
sem_init.3 \
sem_open.3 \
sem_post.3 \
sem_wait.3
MLINKS+= pthread_cancel.3 pthread_setcancelstate.3 \
pthread_cancel.3 pthread_getcancelstate.3
pthread_cancel.3 pthread_getcancelstate.3 \
sem_open.3 sem_close.3 \
sem_open.3 sem_unlink.3 \
sem_wait.3 sem_trywait.3

83
lib/libc_r/man/sem_destroy.3 Normal file
View File

@ -0,0 +1,83 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_DESTROY 3
.Os
.Sh NAME
.Nm sem_destroy
.Nd destroy an unnamed semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_destroy
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.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 EBUSY if there are threads blocked on
.Fa sem .

77
lib/libc_r/man/sem_getvalue.3 Normal file
View File

@ -0,0 +1,77 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_GETVALUE 3
.Os
.Sh NAME
.Nm sem_getvalue
.Nd get the value of a semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_getvalue
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3
.Sh STANDARDS
.Fn sem_getvalue
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.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.

100
lib/libc_r/man/sem_init.3 Normal file
View File

@ -0,0 +1,100 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_INIT 3
.Os
.Sh NAME
.Nm sem_init
.Nd initialize an unnamed semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_init
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3 ,
.Xr sem_post 3 ,
.Xr sem_destroy
.Sh STANDARDS
.Fn sem_init
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.Pp
This implementation does not support shared semaphores, and reports this fact
by setting
.Va errno
to 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.

80
lib/libc_r/man/sem_open.3 Normal file
View File

@ -0,0 +1,80 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.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 SYNOPSIS
.Fd #include <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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

71
lib/libc_r/man/sem_post.3 Normal file
View File

@ -0,0 +1,71 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_POST 3
.Os
.Sh NAME
.Nm sem_post
.Nd increment (unlock) a semaphore
.Sh SYNOPSIS
.Fd #include <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 .
.Sh RETURN VALUES
If successful,
.Fn sem_post
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3
.Sh STANDARDS
.Fn sem_post
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

92
lib/libc_r/man/sem_wait.3 Normal file
View File

@ -0,0 +1,92 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_WAIT 3
.Os
.Sh NAME
.Nm sem_wait ,
.Nm sem_trywait
.Nd decrement (lock) a semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_wait
and
.Fn sem_trywait
return 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

17
lib/libpthread/man/Makefile.inc
View File

@ -4,7 +4,8 @@
.PATH: ${.CURDIR}/man
MAN3+= pthread_cleanup_pop.3 \
MAN3+= pthread_cancel.3 \
pthread_cleanup_pop.3 \
pthread_cleanup_push.3 \
pthread_cond_broadcast.3 \
pthread_cond_destroy.3 \
@ -12,7 +13,6 @@ MAN3+= pthread_cleanup_pop.3 \
pthread_cond_signal.3 \
pthread_cond_timedwait.3 \
pthread_cond_wait.3 \
pthread_cancel.3 \
pthread_create.3 \
pthread_detach.3 \
pthread_equal.3 \
@ -38,7 +38,16 @@ MAN3+= pthread_cleanup_pop.3 \
pthread_rwlockattr_setpshared.3 \
pthread_self.3 \
pthread_setspecific.3 \
pthread_testcancel.3
pthread_testcancel.3 \
sem_destroy.3 \
sem_getvalue.3 \
sem_init.3 \
sem_open.3 \
sem_post.3 \
sem_wait.3
MLINKS+= pthread_cancel.3 pthread_setcancelstate.3 \
pthread_cancel.3 pthread_getcancelstate.3
pthread_cancel.3 pthread_getcancelstate.3 \
sem_open.3 sem_close.3 \
sem_open.3 sem_unlink.3 \
sem_wait.3 sem_trywait.3

83
lib/libpthread/man/sem_destroy.3 Normal file
View File

@ -0,0 +1,83 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_DESTROY 3
.Os
.Sh NAME
.Nm sem_destroy
.Nd destroy an unnamed semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_destroy
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.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 EBUSY if there are threads blocked on
.Fa sem .

77
lib/libpthread/man/sem_getvalue.3 Normal file
View File

@ -0,0 +1,77 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_GETVALUE 3
.Os
.Sh NAME
.Nm sem_getvalue
.Nd get the value of a semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_getvalue
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3
.Sh STANDARDS
.Fn sem_getvalue
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.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.

100
lib/libpthread/man/sem_init.3 Normal file
View File

@ -0,0 +1,100 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_INIT 3
.Os
.Sh NAME
.Nm sem_init
.Nd initialize an unnamed semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_init
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3 ,
.Xr sem_post 3 ,
.Xr sem_destroy
.Sh STANDARDS
.Fn sem_init
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.
.Pp
This implementation does not support shared semaphores, and reports this fact
by setting
.Va errno
to 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.

80
lib/libpthread/man/sem_open.3 Normal file
View File

@ -0,0 +1,80 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.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 SYNOPSIS
.Fd #include <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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

71
lib/libpthread/man/sem_post.3 Normal file
View File

@ -0,0 +1,71 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_POST 3
.Os
.Sh NAME
.Nm sem_post
.Nd increment (unlock) a semaphore
.Sh SYNOPSIS
.Fd #include <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 .
.Sh RETURN VALUES
If successful,
.Fn sem_post
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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_wait 3 ,
.Xr sem_trywait 3
.Sh STANDARDS
.Fn sem_post
conforms to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.

92
lib/libpthread/man/sem_wait.3 Normal file
View File

@ -0,0 +1,92 @@
.\" Copyright (C) 2000 Jason Evans <jasone@canonware.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(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$
.Dd February 15, 2000
.Dt SEM_WAIT 3
.Os
.Sh NAME
.Nm sem_wait ,
.Nm sem_trywait
.Nd decrement (lock) a semaphore
.Sh SYNOPSIS
.Fd #include <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
If successful,
.Fn sem_wait
and
.Fn sem_trywait
return 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the type of
error.
.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 ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1 1996 Edition.