[apple/libc.git] / pthreads / pthread_create.3

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