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