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