1.\" $NetBSD: pthread_create.3,v 1.7 2010/07/09 08:51:28 jruoho 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 July 9, 2010 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. 80.Pp 81The attributes specified via 82.Fa attr 83are copied into the new thread. 84Any subsequent modifications to the attributes object 85.Fa attr 86points to will have no effect upon already-created threads. 87It is thus also safe to pass the same 88.Fa attr 89to multiple calls to 90.Fn pthread_create . 91.Pp 92Upon 93successful completion 94.Fn pthread_create 95will store the ID of the created thread in the location specified by 96.Fa thread . 97The thread is created executing 98.Fa start_routine 99with 100.Fa arg 101as its sole argument. 102.Pp 103If the 104.Fa start_routine 105returns, the effect is as if there was an implicit call to 106.Fn pthread_exit 107using the return value of 108.Fa start_routine 109as the exit status. 110Note that the thread in which 111.Fn main 112was originally invoked differs from this. 113When it returns from 114.Fn main , 115the effect is as if there was an implicit call to 116.Fn exit 117using the return value of 118.Fn main 119as the exit status. 120.Pp 121The signal state of the new thread is initialized as: 122.Bl -bullet -offset indent 123.It 124The signal mask is inherited from the creating thread. 125.It 126The set of signals pending for the new thread is empty. 127.El 128.Sh RETURN VALUES 129If successful, the 130.Fn pthread_create 131function will return zero. 132Otherwise an error number will be returned to 133indicate the error. 134.Sh ERRORS 135.Fn pthread_create 136shall fail if: 137.Bl -tag -width Er 138.It Bq Er EAGAIN 139The system lacks the necessary resources to create another thread, or 140the system-imposed limit on the total number of threads in a process 141.Dv PTHREAD_THREADS_MAX 142would be exceeded. 143.It Bq Er EINVAL 144The value specified by 145.Fa attr 146is invalid. 147.El 148.Sh SEE ALSO 149.Xr fork 2 , 150.Xr pthread_attr 3 , 151.Xr pthread_cleanup_pop 3 , 152.Xr pthread_cleanup_push 3 , 153.Xr pthread_exit 3 , 154.Xr pthread_join 3 155.Sh STANDARDS 156The function conforms to 157.St -p1003.1-2001 . 158