1.\" $OpenBSD: __tfork_thread.3,v 1.1 2014/07/10 13:46:31 guenther 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: July 10 2014 $ 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 TID */ 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 PID is returned to the user at that 59address, with the guarantee that this is done before returning to 60userspace in either the current 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 and hppa64, 65that is the lowest address used; 66on other architectures that is the address after the highest address used. 67.Pp 68The 69.Fa psize 70argument provides the size of the 71.Vt "struct __tfork" 72passed via the 73.Fa params 74argument. 75.Pp 76The underlying system call used to create the thread is 77.Fn __tfork . 78Because the new thread returns without a stack frame, 79the syscall cannot be directly used from C and is therefore not 80provided as a function. 81However, the syscall may show up in the output of 82.Xr kdump 1 . 83.Sh RETURN VALUES 84Upon successful completion, 85.Fn __tfork_thread 86returns in the current thread the PID of new thread. 87The 88.Fn __tfork 89syscall itself, on success, returns a value of 0 in the new thread 90and returns the PID of the new thread to the current thread. 91Otherwise, a value of -1 is returned, no thread is created, and the 92global variable 93.Va errno 94is set to indicate an error. 95.Sh ERRORS 96.Fn __tfork_thread 97and 98.Fn __tfork 99will fail and no thread will be created if: 100.Bl -tag -width Er 101.It Bq Er ENOMEM 102Cannot allocate memory. 103The new process image required more memory than was allowed by the hardware or 104by system-imposed memory management constraints. 105A lack of swap space is normally temporary; however, a lack of core is not. 106Soft limits may be increased to their corresponding hard limits. 107.It Bq Er EINVAL 108Invalid argument. 109Some invalid argument was supplied. 110.It Bq Er EAGAIN 111Resource temporarily unavailable. 112The system-imposed limit on the total 113number of threads under execution would be exceeded. 114This limit is configuration-dependent. 115.It Bq Er EAGAIN 116Resource temporarily unavailable. 117The system-imposed limit 118.Dv MAXUPRC 119on the total number of threads under execution by a single user would be 120exceeded. 121.Dv MAXUPRC 122is currently defined in 123.Aq Pa sys/param.h 124as 125.Dv CHILD_MAX , 126which is currently defined as 80 in 127.Aq Pa sys/syslimits.h . 128.El 129.Sh STANDARDS 130The 131.Fn __tfork_thread 132function and 133.Fn __tfork 134syscall are specific to 135.Ox 136and should not be used in portable applications. 137.Sh HISTORY 138The 139.Fn __tfork_thread 140function and 141.Fn __tfork 142syscall appeared in 143.Ox 5.1 . 144