| blob | d8b8ae70708922dc88bd472107eeb80dc160e33b |
1 .\" $NetBSD: pthread_create.3,v 1.4 2005/03/21 17:55:07 kleink 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 January 30, 2003
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 .Ft int
68 .Fn pthread_create "pthread_t * restrict thread" "const pthread_attr_t * restrict attr" "void *(*start_routine)(void *)" "void * restrict arg"
69 .Sh DESCRIPTION
70 The
71 .Fn pthread_create
72 function is used to create a new thread, with attributes specified by
73 .Fa attr ,
74 within a process.
75 If
76 .Fa attr
77 is
78 .Dv NULL ,
79 the default attributes are used.
80 If the attribute object pointed to by
81 .Fa attr
82 are modified later, the thread's attributes are not affected.
83 Upon
84 successful completion
85 .Fn pthread_create
86 will store the ID of the created thread in the location specified by
87 .Fa thread .
88 .Pp
89 The thread is created executing
90 .Fa start_routine
91 with
92 .Fa arg
93 as its sole argument.
94 If the
95 .Fa start_routine
96 returns, the effect is as if there was an implicit call to
97 .Fn pthread_exit
98 using the return value of
99 .Fa start_routine
100 as the exit status.
101 Note that the thread in which
102 .Fn main
103 was originally invoked differs from this.
104 When it returns from
105 .Fn main ,
106 the effect is as if there was an implicit call to
107 .Fn exit
108 using the return value of
109 .Fn main
110 as the exit status.
111 .Pp
112 The signal state of the new thread is initialized as:
113 .Bl -bullet -offset indent
114 .It
115 The signal mask is inherited from the creating thread.
116 .It
117 The set of signals pending for the new thread is empty.
118 .El
119 .Sh RETURN VALUES
120 If successful, the
121 .Fn pthread_create
122 function will return zero.
123 Otherwise an error number will be returned to
124 indicate the error.
125 .Sh ERRORS
126 .Fn pthread_create
127 shall fail if:
128 .Bl -tag -width Er
129 .It Bq Er EAGAIN
130 The system lacks the necessary resources to create another thread, or
131 the system-imposed limit on the total number of threads in a process
132 .Dv PTHREAD_THREADS_MAX
133 would be exceeded.
134 .It Bq Er EINVAL
135 The value specified by
136 .Fa attr
137 is invalid.
138 .El
139 .Sh SEE ALSO
140 .Xr fork 2 ,
141 .Xr pthread_cleanup_pop 3 ,
142 .Xr pthread_cleanup_push 3 ,
143 .Xr pthread_exit 3 ,
144 .Xr pthread_join 3
145 .Sh STANDARDS
146 .Fn pthread_create
147 conforms to
148 .St -p1003.1-96 .