1.\" $NetBSD: pthread_create.3,v 1.5 2008/05/02 18:11:04 martin Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 14.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 15.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 17.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 20.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 21.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 22.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 23.\" POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. 26.\" All rights reserved. 27.\" 28.\" Redistribution and use in source and binary forms, with or without 29.\" modification, are permitted provided that the following conditions 30.\" are met: 31.\" 1. Redistributions of source code must retain the above copyright 32.\" notice, this list of conditions and the following disclaimer. 33.\" 2. Redistributions in binary form must reproduce the above copyright 34.\" notice, this list of conditions and the following disclaimer in the 35.\" documentation and/or other materials provided with the distribution. 36.\" 3. All advertising materials mentioning features or use of this software 37.\" must display the following acknowledgement: 38.\" This product includes software developed by John Birrell. 39.\" 4. Neither the name of the author nor the names of any co-contributors 40.\" may be used to endorse or promote products derived from this software 41.\" without specific prior written permission. 42.\" 43.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 44.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 45.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 46.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 47.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 48.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 49.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 51.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 52.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 53.\" SUCH DAMAGE. 54.\" 55.\" $FreeBSD: src/lib/libpthread/man/pthread_create.3,v 1.16 2002/09/16 19:29:28 mini Exp $ 56.\" 57.Dd January 30, 2003 58.Dt PTHREAD_CREATE 3 59.Os 60.Sh NAME 61.Nm pthread_create 62.Nd create a new thread 63.Sh LIBRARY 64.Lb libpthread 65.Sh SYNOPSIS 66.In pthread.h 67.Ft int 68.Fn pthread_create "pthread_t * restrict thread" "const pthread_attr_t * restrict attr" "void *(*start_routine)(void *)" "void * restrict arg" 69.Sh DESCRIPTION 70The 71.Fn pthread_create 72function is used to create a new thread, with attributes specified by 73.Fa attr , 74within a process. 75If 76.Fa attr 77is 78.Dv NULL , 79the default attributes are used. 80If the attribute object pointed to by 81.Fa attr 82are modified later, the thread's attributes are not affected. 83Upon 84successful completion 85.Fn pthread_create 86will store the ID of the created thread in the location specified by 87.Fa thread . 88.Pp 89The thread is created executing 90.Fa start_routine 91with 92.Fa arg 93as its sole argument. 94If the 95.Fa start_routine 96returns, the effect is as if there was an implicit call to 97.Fn pthread_exit 98using the return value of 99.Fa start_routine 100as the exit status. 101Note that the thread in which 102.Fn main 103was originally invoked differs from this. 104When it returns from 105.Fn main , 106the effect is as if there was an implicit call to 107.Fn exit 108using the return value of 109.Fn main 110as the exit status. 111.Pp 112The signal state of the new thread is initialized as: 113.Bl -bullet -offset indent 114.It 115The signal mask is inherited from the creating thread. 116.It 117The set of signals pending for the new thread is empty. 118.El 119.Sh RETURN VALUES 120If successful, the 121.Fn pthread_create 122function will return zero. 123Otherwise an error number will be returned to 124indicate the error. 125.Sh ERRORS 126.Fn pthread_create 127shall fail if: 128.Bl -tag -width Er 129.It Bq Er EAGAIN 130The system lacks the necessary resources to create another thread, or 131the system-imposed limit on the total number of threads in a process 132.Dv PTHREAD_THREADS_MAX 133would be exceeded. 134.It Bq Er EINVAL 135The value specified by 136.Fa attr 137is invalid. 138.El 139.Sh SEE ALSO 140.Xr fork 2 , 141.Xr pthread_cleanup_pop 3 , 142.Xr pthread_cleanup_push 3 , 143.Xr pthread_exit 3 , 144.Xr pthread_join 3 145.Sh STANDARDS 146.Fn pthread_create 147conforms to 148.St -p1003.1-96 . 149