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