1.\" Copyright (c) 2007 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by Simon 'corecode' Schubert <corecode@fs.ei.tum.de> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.Dd January 14, 2017 34.Dt LWP_CREATE 2 35.Os 36.Sh NAME 37.Nm lwp_create , 38.Nm lwp_create2 39.Nd spawn a new lwp 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/lwp.h 44.Ft int 45.Fn lwp_create "struct lwp_params *params" 46.Ft int 47.Fn lwp_create2 "struct lwp_params *params" "const cpumask_t *mask" 48.Sh DESCRIPTION 49The 50.Fn lwp_create 51and the 52.Fn lwp_create2 53function spawn a new lwp in the current process. 54In a way, 55.Fn lwp_create 56and 57.Fn lwp_create2 58are similar to 59.Xr fork 2 . 60However, 61.Fn lwp_create 62and 63.Fn lwp_create2 64do not return twice as parent and child. 65Instead, the new lwp will execute a function provided by the 66.Fa params 67argument which is a pointer to a 68.Vt struct lwp_params . 69.Bd -literal 70struct lwp_params { 71 void (*func)(void *); /* Function to start execution */ 72 void *arg; /* Parameter to this function */ 73 void *stack; /* Stack address to use */ 74 lwpid_t *tid1; /* Address to copy out new tid */ 75 lwpid_t *tid2; /* Same */ 76}; 77.Ed 78.Pp 79A function pointer 80.Fa func 81specifies the function to be executed in the new lwp. 82It is the duty of 83.Fn func 84to correctly terminate execution of the lwp, either by calling 85.Xr extexit 2 86or 87.Xr exit 3 . 88If 89.Fn func 90returns, behavior is unspecified. 91The only argument passed to 92.Fn func 93is 94.Fa arg . 95.Pp 96The new lwp starts with its stack frame set to 97.Fa stack . 98Note that both 99.Fa func 100and 101.Fa stack 102are mandatory. 103If either is invalid, behavior is 104unspecified. 105.Pp 106The fields 107.Fa tid1 108and 109.Fa tid2 110point to variables where the tid of the new lwp shall be stored. 111Two parameters are provided so that storage for both parent 112and child can be specified separately. 113Setting any of these to NULL causes the respective tid not to be copied out. 114.Pp 115The 116.Fa mask 117argument to 118.Fn lwp_create2 119specifies the new lwp's CPU affinity mask. 120.Va NULL 121means no special CPU affinity settings. 122.Sh RETURN VALUES 123.Rv -std 124.Sh SEE ALSO 125.Xr extexit 2 , 126.Xr rfork 2 , 127.Xr exit 3 128.Sh HISTORY 129The 130.Fn lwp_create 131function first appeared in 132.Dx 1.9 . 133The 134.Fn lwp_create2 135function first appeared in 136.Dx 4.7 . 137