xref: /titanic_50/usr/src/man/man3c/thrd_create.3c (revision dcdfe824b3dff2df12578b936adf1daf000aa129)
1*dcdfe824SRobert Mustacchi.\"
2*dcdfe824SRobert Mustacchi.\" This file and its contents are supplied under the terms of the
3*dcdfe824SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0.
4*dcdfe824SRobert Mustacchi.\" You may only use this file in accordance with the terms of version
5*dcdfe824SRobert Mustacchi.\" 1.0 of the CDDL.
6*dcdfe824SRobert Mustacchi.\"
7*dcdfe824SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this
8*dcdfe824SRobert Mustacchi.\" source.  A copy of the CDDL is also available via the Internet at
9*dcdfe824SRobert Mustacchi.\" http://www.illumos.org/license/CDDL.
10*dcdfe824SRobert Mustacchi.\"
11*dcdfe824SRobert Mustacchi.\"
12*dcdfe824SRobert Mustacchi.\" Copyright 2016 Joyent, Inc.
13*dcdfe824SRobert Mustacchi.\"
14*dcdfe824SRobert Mustacchi.Dd "Jan 13, 2015"
15*dcdfe824SRobert Mustacchi.Dt THRD_CREATE 3C
16*dcdfe824SRobert Mustacchi.Os
17*dcdfe824SRobert Mustacchi.Sh NAME
18*dcdfe824SRobert Mustacchi.Nm thrd_create
19*dcdfe824SRobert Mustacchi.Nd create a thread
20*dcdfe824SRobert Mustacchi.Sh SYNOPSIS
21*dcdfe824SRobert Mustacchi.In threads.h
22*dcdfe824SRobert Mustacchi.Vt "typedef int (*thrd_start_t)(void *);"
23*dcdfe824SRobert Mustacchi.Ft int
24*dcdfe824SRobert Mustacchi.Fo thrd_create
25*dcdfe824SRobert Mustacchi.Fa "thrd_t *thrdp"
26*dcdfe824SRobert Mustacchi.Fa "thrd_start_t func"
27*dcdfe824SRobert Mustacchi.Fa "void *arg"
28*dcdfe824SRobert Mustacchi.Fc
29*dcdfe824SRobert Mustacchi.Sh DESCRIPTION
30*dcdfe824SRobert MustacchiThe
31*dcdfe824SRobert Mustacchi.Fn thrd_create
32*dcdfe824SRobert Mustacchifunction creates a new thread of execution inside of the current
33*dcdfe824SRobert Mustacchiprocess and stores its identifier in
34*dcdfe824SRobert Mustacchi.Fa thrdp .
35*dcdfe824SRobert MustacchiEach thread operates concurrently within the process.
36*dcdfe824SRobert Mustacchi.Pp
37*dcdfe824SRobert MustacchiWhen a thread is created, it begins its execution at the function
38*dcdfe824SRobert Mustacchi.Fa func
39*dcdfe824SRobert Mustacchiwith the argument
40*dcdfe824SRobert Mustacchi.Fa arg .
41*dcdfe824SRobert MustacchiA created thread has access to all global data within a process;
42*dcdfe824SRobert Mustacchihowever, it has its own private stack. Currently 32-bit processes have a
43*dcdfe824SRobert Mustacchidefault stack of 1 megabyte, while 64-bit systems have a default stack
44*dcdfe824SRobert Mustacchisize of 2 megabytes. In addition, newly created threads inherit the
45*dcdfe824SRobert Mustacchisignal mask of the thread which created them; however, they do not
46*dcdfe824SRobert Mustacchiinherit any pending signals.
47*dcdfe824SRobert Mustacchi.Pp
48*dcdfe824SRobert MustacchiOnce created, a thread will continue to execute until either, it returns
49*dcdfe824SRobert Mustacchifrom its initial function, the thread explicitly calls
50*dcdfe824SRobert Mustacchi.Xr thrd_exit 3C ,
51*dcdfe824SRobert Mustacchior the process itself terminates, such as with a call to
52*dcdfe824SRobert Mustacchi.Xr exit 2 .
53*dcdfe824SRobert MustacchiWhen the initial function returns, it behaves as though a call to
54*dcdfe824SRobert Mustacchi.Xr thrd_exit
55*dcdfe824SRobert Mustacchiwas made, and, if the thread has not been detached with a call to
56*dcdfe824SRobert Mustacchi.Xr thrd_detach,
57*dcdfe824SRobert Mustacchithe exit status remains available and the corresponding thread ID will
58*dcdfe824SRobert Mustacchinot be reused until a process calls
59*dcdfe824SRobert Mustacchi.Xr thrd_join 3C .
60*dcdfe824SRobert MustacchiThis is similar to how a parent must call
61*dcdfe824SRobert Mustacchi.Xr wait 2 ,
62*dcdfe824SRobert Mustacchito clean up a child process that has terminated.
63*dcdfe824SRobert Mustacchi.Pp
64*dcdfe824SRobert MustacchiFor a richer interface interface with more control over aspects of the
65*dcdfe824SRobert Mustacchinewly created thread, such as stack size, stack placement, and the like,
66*dcdfe824SRobert Mustacchisee
67*dcdfe824SRobert Mustacchi.Xr thr_create 3C
68*dcdfe824SRobert Mustacchiand
69*dcdfe824SRobert Mustacchi.Xr pthread_create 3C .
70*dcdfe824SRobert Mustacchi.Sh RETURN VALUES
71*dcdfe824SRobert MustacchiUpon successful completion, the
72*dcdfe824SRobert Mustacchi.Fn thrd_create
73*dcdfe824SRobert Mustacchifunction returns
74*dcdfe824SRobert Mustacchi.Sy thrd_success .
75*dcdfe824SRobert MustacchiIf insufficient memory was available, then
76*dcdfe824SRobert Mustacchi.Sy thrd_nomem
77*dcdfe824SRobert Mustacchiis returned. Otherwise,
78*dcdfe824SRobert Mustacchi.Sy thrd_error
79*dcdfe824SRobert Mustacchiis returned, indicating that a non-memory related error.
80*dcdfe824SRobert Mustacchi.Sh INTERFACE STABILITY
81*dcdfe824SRobert Mustacchi.Sy Standard
82*dcdfe824SRobert Mustacchi.Sh MT-LEVEL
83*dcdfe824SRobert Mustacchi.Sy MT-Safe
84*dcdfe824SRobert Mustacchi.Sh SEE ALSO
85*dcdfe824SRobert Mustacchi.Xr pthread_create 3C ,
86*dcdfe824SRobert Mustacchi.Xr thr_create 3C ,
87*dcdfe824SRobert Mustacchi.Xr thrd_detach 3C ,
88*dcdfe824SRobert Mustacchi.Xr thrd_join 3C ,
89*dcdfe824SRobert Mustacchi.Xr attributes 5 ,
90*dcdfe824SRobert Mustacchi.Xr threads 5
91