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.\" $DragonFly: src/lib/libc/sys/lwp_create.2,v 1.2 2007/03/13 10:16:56 swildner Exp $ 34.\" 35.Dd January 14, 2017 36.Dt LWP_CREATE 2 37.Os 38.Sh NAME 39.Nm lwp_create, 40.Nm lwp_create2 41.Nd spawn a new lwp 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/lwp.h 46.Ft int 47.Fn lwp_create "struct lwp_params *params" 48.Ft int 49.Fn lwp_create2 "struct lwp_params *params" "const cpumask_t *mask" 50.Sh DESCRIPTION 51The 52.Fn lwp_create 53and the 54.Fn lwp_create2 55function spawn a new lwp in the current process. 56In a way, 57.Fn lwp_create 58and 59.Fn lwp_create2 60are similar to 61.Xr fork 2 . 62However, 63.Fn lwp_create 64and 65.Fn lwp_create2 66do not return twice as parent and child. 67Instead, the new lwp will execute a function provided by the 68.Fa params 69argument which is a pointer to a 70.Vt struct lwp_params . 71.Bd -literal 72struct lwp_params { 73 void (*func)(void *); /* Function to start execution */ 74 void *arg; /* Parameter to this function */ 75 void *stack; /* Stack address to use */ 76 lwpid_t *tid1; /* Address to copy out new tid */ 77 lwpid_t *tid2; /* Same */ 78}; 79.Ed 80.Pp 81A function pointer 82.Fa func 83specifies the function to be executed in the new lwp. 84It is the duty of 85.Fn func 86to correctly terminate execution of the lwp, either by calling 87.Xr extexit 2 88or 89.Xr exit 3 . 90If 91.Fn func 92returns, behavior is unspecified. 93The only argument passed to 94.Fn func 95is 96.Fa arg . 97.Pp 98The new lwp starts with its stack frame set to 99.Fa stack . 100Note that both 101.Fa func 102and 103.Fa stack 104are mandatory. 105If either is invalid, behavior is 106unspecified. 107.Pp 108The fields 109.Fa tid1 110and 111.Fa tid2 112point to variables where the tid of the new lwp shall be stored. 113Two parameters are provided so that storage for both parent 114and child can be specified separately. 115Setting any of these to NULL causes the respective tid not to be copied out. 116.Pp 117The 118.Fa mask 119argument to 120.Fn lwp_create2 121specifies the new lwp's CPU affinity mask. 122.Va NULL 123means no special CPU affinity settings. 124.Sh RETURN VALUES 125.Rv -std 126.Sh SEE ALSO 127.Xr extexit 2 , 128.Xr rfork 2 , 129.Xr exit 3 130.Sh HISTORY 131The 132.Fn lwp_create 133function first appeared in 134.Dx 1.9 . 135The 136.Fn lwp_create2 137function first appeared in 138.Dx 4.7 . 139