| blob | 0e317de4626ddaa988a99b8af626e051562b4370 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1991, 1992, 1994, The X/Open Company Ltd.
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH PTHREAD_CREATE 3C "Mar 23, 2005"
48 .SH NAME
49 pthread_create \- create a thread
50 .SH SYNOPSIS
51 .LP
52 .nf
53 cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
54 #include <pthread.h>
56 \fBint\fR \fBpthread_create\fR(\fBpthread_t *restrict\fR \fIthread\fR,
57 \fBconst pthread_attr_t *restrict\fR \fIattr\fR,
58 \fBvoid *(*\fR\fIstart_routine\fR)(void*), \fBvoid *restrict\fR \fIarg\fR);
59 .fi
61 .SH DESCRIPTION
62 .sp
63 .LP
64 The \fBpthread_create()\fR function is used to create a new thread, with
65 attributes specified by \fIattr\fR, within a process. If \fIattr\fR is
66 \fINULL,\fR the default attributes are used. (See \fBpthread_attr_init\fR(3C)).
67 If the attributes specified by \fIattr\fR are modified later, the thread's
68 attributes are not affected. Upon successful completion, \fBpthread_create()\fR
69 stores the \fBID\fR of the created thread in the location referenced by
70 \fIthread\fR.
71 .sp
72 .LP
73 The thread is created executing \fIstart_routine\fR with \fIarg\fR as its sole
74 argument. If the \fIstart_routine\fR returns, the effect is as if there was an
75 implicit call to \fBpthread_exit()\fR using the return value of
76 \fIstart_routine\fR as the exit status. Note that the thread in which
77 \fBmain()\fR was originally invoked differs from this. When it returns from
78 \fBmain()\fR, the effect is as if there was an implicit call to \fBexit()\fR
79 using the return value of \fBmain()\fR as the exit status.
80 .sp
81 .LP
82 The signal state of the new thread is initialised as follows:
83 .RS +4
84 .TP
85 .ie t \(bu
86 .el o
87 The signal mask is inherited from the creating thread.
88 .RE
89 .RS +4
90 .TP
91 .ie t \(bu
92 .el o
93 The set of signals pending for the new thread is empty.
94 .RE
95 .sp
96 .LP
97 Default thread creation:
98 .sp
99 .in +2
100 .nf
101 pthread_t tid;
102 void *start_func(void *), *arg;
104 pthread_create(&tid, NULL, start_func, arg);
105 .fi
106 .in -2
108 .sp
109 .LP
110 This would have the same effect as:
111 .sp
112 .in +2
113 .nf
114 \fBpthread_attr_t attr;
116 pthread_attr_init(&attr); /* initialize attr with default */
117 /* attributes */
118 pthread_create(&tid, &attr, start_func, arg);\fR
119 .fi
120 .in -2
122 .sp
123 .LP
124 User-defined thread creation: To create a thread that is scheduled on a
125 system-wide basis, use:
126 .sp
127 .in +2
128 .nf
129 pthread_attr_init(&attr); /* initialize attr with default */
130 /* attributes */
131 pthread_attr_setscope(&attr, PTHREAD_SCOPE_SYSTEM);
132 /* system-wide contention */
133 pthread_create(&tid, &attr, start_func, arg);
134 .fi
135 .in -2
137 .sp
138 .LP
139 To customize the attributes for POSIX threads, see \fBpthread_attr_init\fR(3C).
140 .sp
141 .LP
142 A new thread created with \fBpthread_create()\fR uses the stack specified by
143 the \fIstackaddr\fR attribute, and the stack continues for the number of bytes
144 specified by the \fIstacksize\fR attribute. By default, the stack size is 1
145 megabyte for 32-bit processes and 2 megabyte for 64-bit processes (see
146 \fBpthread_attr_setstacksize\fR(3C)). If the default is used for both the
147 \fIstackaddr\fR and \fIstacksize\fR attributes, \fBpthread_create()\fR creates
148 a stack for the new thread with at least 1 megabyte for 32-bit processes and 2
149 megabyte for 64-bit processes. (For customizing stack sizes, see \fBNOTES\fR).
150 .sp
151 .LP
152 If \fBpthread_create()\fR fails, no new thread is created and the contents of
153 the location referenced by \fIthread\fR are undefined.
154 .SH RETURN VALUES
155 .sp
156 .LP
157 If successful, the \fBpthread_create()\fR function returns \fB0\fR. Otherwise,
158 an error number is returned to indicate the error.
159 .SH ERRORS
160 .sp
161 .LP
162 The \fBpthread_create()\fR function will fail if:
163 .sp
164 .ne 2
165 .na
166 \fB\fBEAGAIN\fR\fR
167 .ad
168 .RS 10n
169 The system lacked the necessary resources to create another thread, or the
170 system-imposed limit on the total number of threads in a process
171 \fBPTHREAD_THREADS_MAX\fR would be exceeded.
172 .RE
174 .sp
175 .ne 2
176 .na
177 \fB\fBEINVAL\fR\fR
178 .ad
179 .RS 10n
180 The value specified by \fIattr\fR is invalid.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fBEPERM\fR\fR
187 .ad
188 .RS 10n
189 The caller does not have appropriate permission to set the required scheduling
190 parameters or scheduling policy.
191 .RE
193 .SH EXAMPLES
194 .LP
195 \fBExample 1 \fRExample of concurrency with multithreading
196 .sp
197 .LP
198 The following is an example of concurrency with multithreading. Since POSIX
199 threads and Solaris threads are fully compatible even within the same process,
200 this example uses \fBpthread_create()\fR if you execute \fBa.out 0\fR, or
201 \fBthr_create()\fR if you execute \fBa.out 1\fR.
203 .sp
204 .LP
205 Five threads are created that simultaneously perform a time-consuming function,
206 \fBsleep(\fR10\fB)\fR. If the execution of this process is timed, the results
207 will show that all five individual calls to sleep for ten-seconds completed in
208 about ten seconds, even on a uniprocessor. If a single-threaded process calls
209 \fBsleep(\fR10\fB)\fR five times, the execution time will be about 50-seconds.
211 .sp
212 .LP
213 The command-line to time this process is:
215 .sp
216 .ne 2
217 .na
218 \fBPOSIX threading\fR
219 .ad
220 .RS 21n
221 /usr/bin/time a.out 0
222 .RE
224 .sp
225 .ne 2
226 .na
227 \fBSolaris threading\fR
228 .ad
229 .RS 21n
230 /usr/bin/time a.out 1
231 .RE
233 .sp
234 .in +2
235 .nf
236 /* cc thisfile.c -lthread -lpthread */
237 #define _REENTRANT /* basic 3-lines for threads */
238 #include <pthread.h>
239 #include <thread.h>
241 #define NUM_THREADS 5
242 #define SLEEP_TIME 10
244 void *sleeping(void *); /* thread routine */
245 int i;
246 thread_t tid[NUM_THREADS]; /* array of thread IDs */
248 int
249 main(int argc, char *argv[])
250 {
251 if (argc == 1) {
252 printf("use 0 as arg1 to use pthread_create(\|)\en");
253 printf("or use 1 as arg1 to use thr_create(\|)\en");
254 return (1);
255 }
257 switch (*argv[1]) {
258 case '0': /* POSIX */
259 for ( i = 0; i < NUM_THREADS; i++)
260 pthread_create(&tid[i], NULL, sleeping,
261 (void *)SLEEP_TIME);
262 for ( i = 0; i < NUM_THREADS; i++)
263 pthread_join(tid[i], NULL);
264 break;
266 case '1': /* Solaris */
267 for ( i = 0; i < NUM_THREADS; i++)
268 thr_create(NULL, 0, sleeping, (void *)SLEEP_TIME, 0,
269 &tid[i]);
270 while (thr_join(0, NULL, NULL) == 0)
271 ;
272 break;
273 } /* switch */
274 printf("main(\|) reporting that all %d threads have
275 terminated\en", i);
276 return (0);
277 } /* main */
279 void *
280 sleeping(void *arg)
281 {
282 int sleep_time = (int)arg;
283 printf("thread %d sleeping %d seconds ...\en", thr_self(\|),
284 sleep_time);
285 sleep(sleep_time);
286 printf("\enthread %d awakening\en", thr_self(\|));
287 return (NULL);
288 }
289 .fi
290 .in -2
292 .sp
293 .LP
294 If \fBmain()\fR had not waited for the completion of the other threads (using
295 \fBpthread_join\fR(3C) or \fBthr_join\fR(3C)), it would have continued to
296 process concurrently until it reached the end of its routine and the entire
297 process would have exited prematurely. See \fBexit\fR(2).
299 .SH ATTRIBUTES
300 .sp
301 .LP
302 See \fBattributes\fR(5) for descriptions of the following attributes:
303 .sp
305 .sp
306 .TS
307 box;
308 c | c
309 l | l .
310 ATTRIBUTE TYPE ATTRIBUTE VALUE
311 _
312 Interface Stability Standard
313 _
314 MT-Level MT-Safe
315 .TE
317 .SH SEE ALSO
318 .sp
319 .LP
320 \fBfork\fR(2), \fBpthread_attr_init\fR(3C), \fBpthread_cancel\fR(3C),
321 \fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), \fBsysconf\fR(3C),
322 \fBattributes\fR(5), \fBstandards\fR(5)
323 .SH NOTES
324 .sp
325 .LP
326 Multithreaded application threads execute independently of each other, so their
327 relative behavior is unpredictable. Therefore, it is possible for the thread
328 executing \fBmain()\fR to finish before all other user application threads. The
329 \fBpthread_join\fR(3C)function, on the other hand, must specify the terminating
330 thread (IDs) for which it will wait.
331 .sp
332 .LP
333 A user-specified stack size must be greater than the value
334 \fBPTHREAD_STACK_MIN\fR. A minimum stack size may not accommodate the stack
335 frame for the user thread function \fIstart_func\fR. If a stack size is
336 specified, it must accommodate \fIstart_func\fR requirements and the functions
337 that it may call in turn, in addition to the minimum requirement.
338 .sp
339 .LP
340 It is usually very difficult to determine the runtime stack requirements for a
341 thread. \fBPTHREAD_STACK_MIN\fR specifies how much stack storage is required to
342 execute a \fINULL\fR \fIstart_func\fR. The total runtime requirements for stack
343 storage are dependent on the storage required to do runtime linking, the amount
344 of storage required by library runtimes (as \fBprintf()\fR) that your thread
345 calls. Since these storage parameters are not known before the program runs, it
346 is best to use default stacks. If you know your runtime requirements or decide
347 to use stacks that are larger than the default, then it makes sense to specify
348 your own stacks.