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: src/lib/libc_r/man/pthread_create.3,v 1.9.2.5 2001/12/17 10:08:26 ru Exp $ 32.\" $DragonFly: src/lib/libc_r/man/pthread_create.3,v 1.2 2003/06/17 04:26:48 dillon Exp $ 33.\" 34.Dd April 15, 2009 35.Dt PTHREAD_CREATE 3 36.Os 37.Sh NAME 38.Nm pthread_create 39.Nd create a new thread 40.Sh LIBRARY 41.Lb libpthread 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 103.Fn pthread_create 104will fail if: 105.Bl -tag -width Er 106.It Bq Er EAGAIN 107The system lacked the necessary resources to create another thread, or 108the system-imposed limit on the total number of threads in a process 109[PTHREAD_THREADS_MAX] would be exceeded. 110.It Bq Er EINVAL 111The value specified by 112.Fa attr 113is invalid. 114.El 115.Sh SEE ALSO 116.Xr fork 2 , 117.Xr pthread_cleanup_pop 3 , 118.Xr pthread_cleanup_push 3 , 119.Xr pthread_exit 3 , 120.Xr pthread_join 3 121.Sh STANDARDS 122.Fn pthread_create 123conforms to 124.St -p1003.1-96 . 125