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 March 12, 2007 36.Dt LWP_CREATE 2 37.Os 38.Sh NAME 39.Nm lwp_create 40.Nd spawn a new lwp 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In unistd.h 45.Ft int 46.Fn lwp_create "struct lwp_params *params" 47.Sh DESCRIPTION 48The 49.Fn lwp_create 50function spawns a new lwp in the current process. 51In a way, 52.Fn lwp_create 53is similar to 54.Xr fork 2 . 55However, 56.Fn lwp_create 57does not return twice as parent and child. 58Instead, the new lwp will execute a function provided by the 59.Fa params 60argument which is a pointer to a 61.Vt struct lwp_params . 62.Bd -literal 63struct lwp_params { 64 void (*func)(void *); /* Function to start execution */ 65 void *arg; /* Parameter to this function */ 66 void *stack; /* Stack address to use */ 67 lwpid_t *tid1; /* Address to copy out new tid */ 68 lwpid_t *tid2; /* Same */ 69}; 70.Ed 71.Pp 72A function pointer 73.Fa func 74specifies the function to be executed in the new lwp. 75It is the duty of 76.Fn func 77to correctly terminate execution of the lwp, either by calling 78.Xr extexit 2 79or 80.Xr exit 3 . 81If 82.Fn func 83returns, behavior is unspecified. 84The only argument passed to 85.Fn func 86is 87.Fa arg . 88.Pp 89The new lwp starts with its stack frame set to 90.Fa stack . 91Note that both 92.Fa func 93and 94.Fa stack 95are mandatory. 96If either is invalid, behavior is 97unspecified. 98.Pp 99The fields 100.Fa tid1 101and 102.Fa tid2 103point to variables where the tid of the new lwp shall be stored. 104Two parameters are provided so that storage for both parent 105and child can be specified separately. 106Setting any of these to NULL causes the respective tid not to be copied out. 107.Sh RETURN VALUES 108.Rv -std 109.Sh SEE ALSO 110.Xr extexit 2 , 111.Xr rfork 2 , 112.Xr exit 3 113.Sh HISTORY 114The 115.Fn lwp_create 116function first appeared in 117.Dx 1.9 . 118