1.\" $OpenBSD: __tfork_thread.3,v 1.4 2016/05/11 21:52:49 deraadt Exp $ 2.\" 3.\" Copyright (c) 2011 Philip Guenther <guenther@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 11 2016 $ 18.Dt __TFORK_THREAD 3 19.Os 20.Sh NAME 21.Nm __tfork_thread , 22.Nm __tfork 23.Nd create a new kernel thread in the current process 24.Sh SYNOPSIS 25.In unistd.h 26.Bd -literal 27struct __tfork { 28 void *tf_tcb; /* TCB address for new thread */ 29 pid_t *tf_tid; /* where to write child's thread ID */ 30 void *tf_stack; /* stack address for new thread */ 31}; 32.Ed 33.Pp 34.Ft pid_t 35.Fn __tfork_thread "const struct __tfork *params" "size_t psize" "void (*startfunc)(void *)" "void *startarg" 36.Ft pid_t 37.Fn __tfork "const struct __tfork *params" "size_t psize" 38.Sh DESCRIPTION 39The 40.Fn __tfork_thread 41function creates a new kernel thread in the current process. 42The new thread starts by calling 43.Fa startfunc , 44passing 45.Fa startarg 46as the only argument. 47If 48.Fa startfunc 49returns, the thread will exit. 50.Pp 51The 52.Fa params 53argument provides parameters used by the kernel during thread creation. 54The new thread's thread control block (TCB) address is set to 55.Em tf_tcb . 56If 57.Em tf_tid 58is not NULL, the new thread's thread ID is returned to the user at that 59address, with the guarantee that this is done before returning to 60userspace in either the calling thread or the new thread. 61If 62.Em tf_stack 63is not NULL, the new thread's stack is initialized to start at that address. 64On hppa that is the lowest address used; 65on other architectures that is the address after the highest address used. 66.Pp 67The 68.Fa psize 69argument provides the size of the 70.Vt "struct __tfork" 71passed via the 72.Fa params 73argument. 74.Pp 75The underlying system call used to create the thread is 76.Fn __tfork . 77Because the new thread returns without a stack frame, 78the syscall cannot be directly used from C and is therefore not 79provided as a function. 80However, the syscall may show up in the output of 81.Xr kdump 1 . 82.Sh RETURN VALUES 83Upon successful completion, 84.Fn __tfork_thread 85returns in the calling thread the thread ID of new thread. 86The 87.Fn __tfork 88syscall itself, on success, returns a value of 0 in the new thread 89and returns the thread ID of the new thread to the calling thread. 90Otherwise, a value of -1 is returned, no thread is created, and the 91global variable 92.Va errno 93is set to indicate an error. 94.Sh ERRORS 95.Fn __tfork_thread 96and 97.Fn __tfork 98will fail and no thread will be created if: 99.Bl -tag -width Er 100.It Bq Er ENOMEM 101Cannot allocate memory. 102The new process image required more memory than was allowed by the hardware or 103by system-imposed memory management constraints. 104A lack of swap space is normally temporary; however, a lack of core is not. 105Soft limits may be increased to their corresponding hard limits. 106.It Bq Er EINVAL 107Invalid argument. 108Some invalid argument was supplied. 109.It Bq Er EAGAIN 110Resource temporarily unavailable. 111The system-imposed limit on the total 112number of threads under execution would be exceeded. 113This limit is configuration-dependent. 114.It Bq Er EAGAIN 115Resource temporarily unavailable. 116The system-imposed limit 117.Dv MAXUPRC 118on the total number of threads under execution by a single user would be 119exceeded. 120.Dv MAXUPRC 121is currently defined in 122.In sys/param.h 123as 124.Dv CHILD_MAX , 125which is currently defined as 80 in 126.In sys/syslimits.h . 127.El 128.Sh STANDARDS 129The 130.Fn __tfork_thread 131function and 132.Fn __tfork 133syscall are specific to 134.Ox 135and should not be used in portable applications. 136.Sh HISTORY 137The 138.Fn __tfork_thread 139function and 140.Fn __tfork 141syscall appeared in 142.Ox 5.1 . 143