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 November 4, 2006 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 libpthread 41.Lb libthr 42.Sh SYNOPSIS 43.In pthread.h 44.Ft int 45.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" 46.Sh DESCRIPTION 47The 48.Fn pthread_create 49function is used to create a new thread, with attributes specified by 50.Fa attr , 51within a process. 52If 53.Fa attr 54is 55.Dv NULL , 56the default attributes are used. 57If the attributes specified by 58.Fa attr 59are modified later, the thread's attributes are not affected. 60Upon 61successful completion 62.Fn pthread_create 63will store the ID of the created thread in the location specified by 64.Fa thread . 65.Pp 66The thread is created executing 67.Fa start_routine 68with 69.Fa arg 70as its sole argument. 71If the 72.Fa start_routine 73returns, the effect is as if there was an implicit call to 74.Fn pthread_exit 75using the return value of 76.Fa start_routine 77as the exit status. 78Note that the thread in which 79.Fn main 80was originally invoked differs from this. 81When it returns from 82.Fn main , 83the effect is as if there was an implicit call to 84.Fn exit 85using the return value of 86.Fn main 87as the exit status. 88.Pp 89The signal state of the new thread is initialized as: 90.Bl -bullet -offset indent 91.It 92The signal mask is inherited from the creating thread. 93.It 94The set of signals pending for the new thread is empty. 95.El 96.Sh RETURN VALUES 97If successful, the 98.Fn pthread_create 99function will return zero. 100Otherwise an error number will be returned to 101indicate the error. 102.Sh ERRORS 103The 104.Fn pthread_create 105function will fail if: 106.Bl -tag -width Er 107.It Bq Er EAGAIN 108The system lacked the necessary resources to create another thread, or 109the system-imposed limit on the total number of threads in a process 110[PTHREAD_THREADS_MAX] would be exceeded. 111.It Bq Er EPERM 112The caller does not have appropriate permission to set the required scheduling 113parameters or scheduling policy. 114.It Bq Er EINVAL 115The value specified by 116.Fa attr 117is invalid. 118.El 119.Sh SEE ALSO 120.Xr fork 2 , 121.Xr pthread_attr 3 , 122.Xr pthread_cleanup_pop 3 , 123.Xr pthread_cleanup_push 3 , 124.Xr pthread_exit 3 , 125.Xr pthread_join 3 126.Sh STANDARDS 127The 128.Fn pthread_create 129function conforms to 130.St -p1003.1-96 . 131