From 7350d1d3b2ec940c89a2b20f9d09985d9fd9e9d7 Mon Sep 17 00:00:00 2001 From: julian Date: Tue, 20 Aug 1996 08:22:01 +0000 Subject: Submitted by: John Birrell Here are the diffs for libc_r to get it one step closer to P1003.1c These make most of the thread/mutex/condvar structures opaque to the user. There are three functions which have been renamed with _np suffixes because they are extensions to P1003.1c (I did them for JAVA, which needs to suspend/resume threads and also start threads suspended). I've created a new header (pthread_np.h) for the non-POSIX stuff. The egrep tags stuff in /usr/src/lib/libc_r/Makefile that I uncommented doesn't work. I think its best to delete it. I don't think libc_r needs tags anyway, 'cause most of the source is in libc which does have tags. also: Here's the first batch of man pages for the thread functions. The diff to /usr/src/lib/libc_r/Makefile removes some stuff that was inherited from /usr/src/lib/libc/Makefile that should only be done with libc. also: I should have sent this diff with the pthread(3) man page. It allows people to type make -DWANT_LIBC_R world to get libc_r built with the rest of the world. I put this in the pthread(3) man page. The default is still not to build libc_r. also: The diff attached adds a pthread(3) man page to /usr/src/share/man/man3. The idea is that without libc_r installed, this man page will give people enough info to know that they have to build libc_r. --- lib/libc_r/man/Makefile.inc | 17 ++++++ lib/libc_r/man/pthread_create.3 | 109 +++++++++++++++++++++++++++++++++++ lib/libc_r/man/pthread_detach.3 | 79 +++++++++++++++++++++++++ lib/libc_r/man/pthread_equal.3 | 66 +++++++++++++++++++++ lib/libc_r/man/pthread_exit.3 | 99 +++++++++++++++++++++++++++++++ lib/libc_r/man/pthread_getspecific.3 | 80 +++++++++++++++++++++++++ lib/libc_r/man/pthread_join.3 | 100 ++++++++++++++++++++++++++++++++ lib/libc_r/man/pthread_key_create.3 | 98 +++++++++++++++++++++++++++++++ lib/libc_r/man/pthread_key_delete.3 | 92 +++++++++++++++++++++++++++++ lib/libc_r/man/pthread_once.3 | 100 ++++++++++++++++++++++++++++++++ lib/libc_r/man/pthread_self.3 | 59 +++++++++++++++++++ lib/libc_r/man/pthread_setspecific.3 | 91 +++++++++++++++++++++++++++++ 12 files changed, 990 insertions(+) create mode 100644 lib/libc_r/man/Makefile.inc create mode 100644 lib/libc_r/man/pthread_create.3 create mode 100644 lib/libc_r/man/pthread_detach.3 create mode 100644 lib/libc_r/man/pthread_equal.3 create mode 100644 lib/libc_r/man/pthread_exit.3 create mode 100644 lib/libc_r/man/pthread_getspecific.3 create mode 100644 lib/libc_r/man/pthread_join.3 create mode 100644 lib/libc_r/man/pthread_key_create.3 create mode 100644 lib/libc_r/man/pthread_key_delete.3 create mode 100644 lib/libc_r/man/pthread_once.3 create mode 100644 lib/libc_r/man/pthread_self.3 create mode 100644 lib/libc_r/man/pthread_setspecific.3 (limited to 'lib/libc_r/man') diff --git a/lib/libc_r/man/Makefile.inc b/lib/libc_r/man/Makefile.inc new file mode 100644 index 0000000..7d67fb8 --- /dev/null +++ b/lib/libc_r/man/Makefile.inc @@ -0,0 +1,17 @@ +# $Id$ + +# POSIX thread man files + +.PATH: ${.CURDIR}/man + +MAN3+= pthread_create.3 \ + pthread_detach.3 \ + pthread_equal.3 \ + pthread_exit.3 \ + pthread_getspecific.3 \ + pthread_join.3 \ + pthread_key_create.3 \ + pthread_key_delete.3 \ + pthread_once.3 \ + pthread_self.3 \ + pthread_setspecific.3 diff --git a/lib/libc_r/man/pthread_create.3 b/lib/libc_r/man/pthread_create.3 new file mode 100644 index 0000000..5ac24e8 --- /dev/null +++ b/lib/libc_r/man/pthread_create.3 @@ -0,0 +1,109 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_CREATE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_create +.Nd create a new thread +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" +.Sh DESCRIPTION +The +.Fn pthread_create +function is used to create a new thread, with attributes specified by +.Fa attr , +within a process. If +.Fa attr +is NULL, the default attributes are used. If the attributes specified by +.Fa attr +are modified later, the thread's attributes are not affected. Upon +successful completion +.Fn pthread_create +will store the ID of the created thread in the location specified by +.Fa thread . +.Pp +The thread is created executing +.Fa start_routine +with +.Fa arg +as its sole argument. If the +.Fa start_routine +returns, the effect is as if there was an implicit call to +.Fn pthread_exit +using the return value of +.Fa start_toutine +as the exit status. Note that the thread in which +.Fn main +was originally invoked differs from this. When it returns from +.Fn main , +the effect is as if there was an implicit call to +.Fn exit using the return value of +.Fn main +as the exit status. +.Pp +The signal state of the new thread is initialized as: +.Bl -bullet -offset indent +.It +The signal mask is inherited from the creating thread. +.It +The set of signals pending for the new thread is empty. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_create +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_create +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread, or +the system-imposed limit on the total number of threads in a process +[PTHREAD_THREADS_MAX] would be exceeded. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_exit 3 , +.Xr pthread_join 3 , +.Xr fork 2 +.Sh STANDARDS +.Fn pthread_create +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_detach.3 b/lib/libc_r/man/pthread_detach.3 new file mode 100644 index 0000000..d2a60dd --- /dev/null +++ b/lib/libc_r/man/pthread_detach.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_DETACH 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_detach +.Nd detach a thread +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_detach "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_detach +function is used to indicate to the implementation that storage for the +thread +.Fa thread +can be reclaimed when the thread terminates. If +.Fa thread +has not terminated, +.Fn pthread_detach +will not cause it to terminate. The effect of multiple +.Fn pthread_detach +calls on the same target thread is unspecified. +.Sh RETURN VALUES +If successful, the +.Fn pthread_detach +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_detach +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.El +.Pp +.Sh SEE ALSO +.Xr pthread_join 3 +.Sh STANDARDS +.Fn pthread_detach +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_equal.3 b/lib/libc_r/man/pthread_equal.3 new file mode 100644 index 0000000..3324855 --- /dev/null +++ b/lib/libc_r/man/pthread_equal.3 @@ -0,0 +1,66 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_EQUAL 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_equal +.Nd compare thread IDs +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_equal "pthread_t t1" "pthread_t t2" +.Sh DESCRIPTION +The +.Fn pthread_equal +function compares the thread IDs +.Fa t1 +and +.Fa t2 . +.Sh RETURN VALUES +The +.Fn pthread_equal +function will non-zero if the thread IDs +.Fa t1 +and +.Fa t2 +correspond to the same thread, otherwise it will return zero. +.Sh ERRORS +None. +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +.Fn pthread_equal +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_exit.3 b/lib/libc_r/man/pthread_exit.3 new file mode 100644 index 0000000..2b0799e --- /dev/null +++ b/lib/libc_r/man/pthread_exit.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_EXIT 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_exit +.Nd terminate the calling thread +.Sh SYNOPSIS +.Fd #include +.Ft void +.Fn pthread_exit "void *value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_exit +function terminates the calling thread and makes the value +.Fa value_ptr +available to any successful join with the terminating thread. Any +cancellation cleanup handlers that have been pushed and are not yet popped +are popped in the reverse order that they were pushed and then executed. +After all cancellation handlers have been executed, if the thread has any +thread-specific data, appropriate destructor functions are called in an +unspecified order. Thread termination does not release any application +visible process resources, including, but not limited to, mutexes and +file descriptors, nor does it perform any process level cleanup +actions, including, but not limited to, calling +.Fn atexit +routines that may exist. +.Pp +An implicit call to +.Fn pthread_exit +is made when a thread other than the thread in which +.Fn main +was first invoked returns from the start routine that was used to create +it. The function's return value serves as the thread's exit status. +.Pp +The behavior of +.Fn pthread_exit +is undefied if called from a cancellation handler or destructor function +that was invoked as the result of an implicit or explicit call to +.Fn pthread_exit . +.Pp +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. Thus, references to local variables +of the exiting thread should not be used for the +.Fn pthread_exit +.Fa value_ptr +parameter value. +.Pp +The process will exit with an exit status of 0 after the last thread has +been terminated. The behavior is as if the implementation called +.Fn exit +with a zero argument at thread termination time. +.Pp +.Sh RETURN VALUES +The +.Fn pthread_exit +function cannot return to its caller. +.Sh ERRORS +None. +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_join 3 , +.Xr exit 2, +.Xr _exit 2 +.Sh STANDARDS +.Fn pthread_exit +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_getspecific.3 b/lib/libc_r/man/pthread_getspecific.3 new file mode 100644 index 0000000..7df4de0 --- /dev/null +++ b/lib/libc_r/man/pthread_getspecific.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_GETSPECIFIC 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_getspecific +.Nd get a thread-specific data value +.Sh SYNOPSIS +.Fd #include +.Ft void * +.Fn pthread_getspecific "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_getspecific +function returns the value currently bound to the specified +.Fa key +on behalf of the calling thread. +.Pp +The effect of calling +.Fn pthread_getspecific +with a +.Fa key +value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +.Fn pthread_getspecific +may be called from a thread-specific data destructor function. +.Sh RETURN VALUES +The +.Fn pthread_getspecific +function will return the thread-specific data value associated with the given +.Fa key . +If no thread-specific data value is associated with +.Fa key , +then the value NULL is returned. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 +.Xr pthread_setspecific 3 +.Sh STANDARDS +.Fn pthread_getspecific +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_join.3 b/lib/libc_r/man/pthread_join.3 new file mode 100644 index 0000000..374b832 --- /dev/null +++ b/lib/libc_r/man/pthread_join.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_JOIN 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_join +.Nd wait for thread termination +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_join "pthread_t thread" "void **value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_join +function suspends execution of the calling thread until the target +.Fa thread +terminates unless the target +.Fa thread +has already terminated. +.Pp +On return from a successful +.Fn pthread_join +call with a non-NULL +.Fa value_ptr +argument, the value passed to +.Fn pthread_exit +by the terminating thread is stored in the location referenced by +.Fa value_ptr . +When a +.Fn pthread_join +returns successfully, the target thread has been terminated. The results +of multiple simultaneous calls to +.Fn pthread_join +specifying the same target thread are undefined. If the thread calling +.Fn pthread_join +is cancelled, then the target thread is not detached. +.Pp +A thread that has exited but remains unjoined counts against +[_POSIX_THREAD_THREADS_MAX]. +.Pp +.Sh RETURN VALUES +If successful, the +.Fn pthread_join +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_join +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.It Bq Er EDEADLK +A deadlock was detected or the value of +.Fa thread +specifies the calling thread. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr wait 2 +.Sh STANDARDS +.Fn pthread_join +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_key_create.3 b/lib/libc_r/man/pthread_key_create.3 new file mode 100644 index 0000000..1bcf9e0 --- /dev/null +++ b/lib/libc_r/man/pthread_key_create.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_KEY_CREATE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_key_create +.Nd thread-specific data key creation +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" +.Sh DESCRIPTION +The +.Fn pthread_key_create +function creates a thread-specific data key visible to all threads in the +process. Key values provided by +.Fn pthread_key_create +are opaque objects used to locate thread-specific data. Although the same +key value may be used by different threads, the values bound to the key +by +.Fn pthread_setspecific +are maintained on a per-thread basis and persist for the life of the calling +thread. +.Pp +Upon key creation, the value NULL is associated with the new key in all +active threads. Upon thread creation, the value NULL is associated with all +defined keys in the new thread. +.Pp +An optional destructor function may be associated with each key value. At +thread exit, if a key value has a non-NULL destructor pointer, and the +thread has a non-NULL value associated with the key, the function pointed +to is called with the current associated value as its sole argument. The +order of destructor calls is unspecified if more than one destructor exists +for a thread when it exits. +.Pp +If, after all the destructors have been called for all non-NULL values +with associated destructors, there are still some non-NULL values with +associated destructors, then the process is repeated. If, after at least +[PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for +outstanding non-NULL values, there are still some non-NULL values with +associated destructors, the implementation stops calling destructors. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_create +function will store the newly created key value at the location specified by +.Fa key +and returns zero. Otherwise an error number will be returned to indicate +the error. +.Sh ERRORS +.Fn pthread_key_create +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread-specific +data key, or the system-imposed limit on the total number of keys per process +[PTHREAD_KEYS_MAX] would be exceeded. +.It Bq Er ENOMEM +Insufficient memory exists to create the key. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_setspecific 3 , +.Xr pthread_key_delete 3 +.Sh STANDARDS +.Fn pthread_key_create +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_key_delete.3 b/lib/libc_r/man/pthread_key_delete.3 new file mode 100644 index 0000000..732c562 --- /dev/null +++ b/lib/libc_r/man/pthread_key_delete.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_KEY_DELETE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_key_delete +.Nd delete a thread-specific data key +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_key_delete +function deletes a thread-specific data key previously returned by +.Fn pthread_key_create . +The thread-specific data values associated with +.Fa key +need not be NULL at the time that +.Fn pthread_key_delete +is called. It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any threads; +this cleanup can be done either before or after +.Fn pthread_key_delete +is called. Any attempt to use +.Fa key +following the call to +.Fn pthread_key_delete +results in undefined behavior. +.Pp +The +.Fn pthread_key_delete +function is callable from within destructor functions. Destructor functions +are not invoked by +.Fn pthread_key_delete . +Any destructor function that may have been associated with +.Fa key +will no longer be called upon thread exit. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_delete +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_key_delete +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_getspecific 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +.Fn pthread_key_delete +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_once.3 b/lib/libc_r/man/pthread_once.3 new file mode 100644 index 0000000..9ade42f --- /dev/null +++ b/lib/libc_r/man/pthread_once.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_ONCE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_once +.Nd dynamic package initialization +.Sh SYNOPSIS +.Fd #include +.Pp +pthread_once +.Fa once_control += PTHREAD_ONCE_INIT; +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void *(*init_routine)(void)" +.Sh DESCRIPTION +The first call to +.Fn pthread_once +by any thread in a process, with a given +.Fa once_control , +will call the +.Fn init_routine +with no arguments. Subsequent calls to +.Fn pthread_once +with the same +.Fa once_control +will not call the +.Fn init_routine . +On return from +.Fn pthread_once , +it is guaranteed that +.Fn init_routine +has completed. The +.Fa once_control +parameter is used to determine whether the associated initialization +routine has been called. +.Pp +The function +.Fn pthread_once +is not a cancellation point. However, if +.Fn init_routine +is a cancellation point and is cancelled, the effect on +.Fa once_control is as if +.Fn pthread_once +was never called. +.Pp +The constant +.Fa PTHREAD_ONCE_INIT +is defined by header +.Aq Pa pthread.h . +.Pp +The behavior of +.Fn pthread_once +is undefined if +.Fa once_control +has automatic storage duration or is not initialized by +.Fa PTHREAD_ONCE_INIT . +.Pp +.Sh RETURN VALUES +If successful, the +.Fn pthread_once +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +None. +.Pp +.Sh STANDARDS +.Fn pthread_once +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_self.3 b/lib/libc_r/man/pthread_self.3 new file mode 100644 index 0000000..9ba0ee6 --- /dev/null +++ b/lib/libc_r/man/pthread_self.3 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_SELF 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_self +.Nd get the calling thread's ID +.Sh SYNOPSIS +.Fd #include +.Ft pthread_t +.Fn pthread_self "void" +.Sh DESCRIPTION +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh RETURN VALUES +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh ERRORS +None. +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 +.Sh STANDARDS +.Fn pthread_self +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/lib/libc_r/man/pthread_setspecific.3 b/lib/libc_r/man/pthread_setspecific.3 new file mode 100644 index 0000000..05b947f --- /dev/null +++ b/lib/libc_r/man/pthread_setspecific.3 @@ -0,0 +1,91 @@ +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_SETSPECIFIC 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_setspecific +.Nd set a thread-specific data value +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value" +.Sh DESCRIPTION +The +.Fn pthread_setspecific +function associates a thread-specific value with a +.Fa key +obtained via a previous call to +.Fn pthread_key_create . +Different threads man bind different values to the same key. These values are +typically pointers to blocks of dynamically allocated memory that have been +reserved for use by the calling thread. +.Pp +The effect of calling +.Fn pthread_setspecific +with a key value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +.Fn pthread_setspecific +may be called from a thread-specific data destructor function, however this +may result in lost storage or infinite loops. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setspecific +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_setspecific +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to associate the value with the +.Fa key . +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_getspecific 3 +.Sh STANDARDS +.Fn pthread_setspecific +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. -- cgit v1.1