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