1*15c5c5f4Suwe.\" $NetBSD: _lwp_create.2,v 1.11 2022/12/04 16:17:50 uwe Exp $ 23fdac2b8Sthorpej.\" 33fdac2b8Sthorpej.\" Copyright (c) 2003 The NetBSD Foundation, Inc. 43fdac2b8Sthorpej.\" All rights reserved. 53fdac2b8Sthorpej.\" 63fdac2b8Sthorpej.\" This code is derived from software contributed to The NetBSD Foundation 73fdac2b8Sthorpej.\" by Jason R. Thorpe of Wasabi Systems, Inc. 83fdac2b8Sthorpej.\" 93fdac2b8Sthorpej.\" Redistribution and use in source and binary forms, with or without 103fdac2b8Sthorpej.\" modification, are permitted provided that the following conditions 113fdac2b8Sthorpej.\" are met: 123fdac2b8Sthorpej.\" 1. Redistributions of source code must retain the above copyright 133fdac2b8Sthorpej.\" notice, this list of conditions and the following disclaimer. 143fdac2b8Sthorpej.\" 2. Redistributions in binary form must reproduce the above copyright 153fdac2b8Sthorpej.\" notice, this list of conditions and the following disclaimer in the 163fdac2b8Sthorpej.\" documentation and/or other materials provided with the distribution. 173fdac2b8Sthorpej.\" 183fdac2b8Sthorpej.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 193fdac2b8Sthorpej.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 203fdac2b8Sthorpej.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 213fdac2b8Sthorpej.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 223fdac2b8Sthorpej.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 233fdac2b8Sthorpej.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 243fdac2b8Sthorpej.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 253fdac2b8Sthorpej.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 263fdac2b8Sthorpej.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 273fdac2b8Sthorpej.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 283fdac2b8Sthorpej.\" POSSIBILITY OF SUCH DAMAGE. 293fdac2b8Sthorpej.\" 305ec33a07Schristos.Dd April 21, 2017 313fdac2b8Sthorpej.Dt _LWP_CREATE 2 323fdac2b8Sthorpej.Os 333fdac2b8Sthorpej.Sh NAME 343fdac2b8Sthorpej.Nm _lwp_create 353fdac2b8Sthorpej.Nd create a new light-weight process 363fdac2b8Sthorpej.Sh LIBRARY 373fdac2b8Sthorpej.Lb libc 383fdac2b8Sthorpej.Sh SYNOPSIS 39472351e1Swiz.In lwp.h 403fdac2b8Sthorpej.Ft int 413fdac2b8Sthorpej.Fn _lwp_create "ucontext_t *context" "unsigned long flags" "lwpid_t *new_lwp" 423fdac2b8Sthorpej.Sh DESCRIPTION 433fdac2b8Sthorpej.Fn _lwp_create 443fdac2b8Sthorpejcauses creation of a new light-weight process, or LWP, and adds it to the 453fdac2b8Sthorpejcurrent process. 463fdac2b8SthorpejThe 473fdac2b8Sthorpej.Fa context 483fdac2b8Sthorpejargument specifies the initial execution context for the new LWP including 493fdac2b8Sthorpejsignal mask, stack, and machine registers. 505ec33a07SchristosThe signal stack of the newly created light-weight process is reset to 515ec33a07Schristosdisabled. 52626fac18SandvarIf this context specifies invalid register values (for example privilege 53e16cbc38Sandvarescalation by setting machine dependent bits forbidden for user processes), 54*15c5c5f4Suweor does not specify cpu register values 55*15c5c5f4Suwe.Fa ( uc_flags 56*15c5c5f4Suwedoes not have the 57*15c5c5f4Suwe.Dv _UC_CPU 58*15c5c5f4Suwebit set), the call will fail and errno will be set to 5949e10846Suwe.Er EINVAL . 603fdac2b8Sthorpej.Pp 613fdac2b8SthorpejThe following flags affect the creation of the new LWP: 62*15c5c5f4Suwe.Bl -tag -width Dv 63*15c5c5f4Suwe.It Dv LWP_DETACHED 643fdac2b8SthorpejThe LWP is created detached. 653fdac2b8SthorpejThe resources associated with a detached LWP will be automatically 663fdac2b8Sthorpejreclaimed by the system when the LWP exits. 673fdac2b8SthorpejOtherwise, a terminated LWP's resources will not be reclaimed until 683fdac2b8Sthorpejits status is reported to another LWP via 693fdac2b8Sthorpej.Xr _lwp_wait 2 . 70*15c5c5f4Suwe.It Dv LWP_SUSPENDED 713fdac2b8SthorpejThe LWP is created suspended, and will not begin execution until 723fdac2b8Sthorpejit is resumed by another LWP via 733fdac2b8Sthorpej.Xr _lwp_continue 2 . 743fdac2b8Sthorpej.\" __LWP_ASLWP is not yet implemented by the NetBSD kernel. 753fdac2b8Sthorpej.El 763fdac2b8Sthorpej.Pp 773fdac2b8SthorpejThe LWP ID of the new LWP is stored in the location pointed to by 783fdac2b8Sthorpej.Fa new_lwp . 793fdac2b8Sthorpej.Sh RETURN VALUES 80*15c5c5f4Suwe.Rv -std _lwp_create 813fdac2b8Sthorpej.Sh ERRORS 823fdac2b8Sthorpej.Fn _lwp_create 833fdac2b8Sthorpejwill fail and no LWP will be created if: 84*15c5c5f4Suwe.Bl -tag -width Er 853fdac2b8Sthorpej.It Bq Er EAGAIN 863fdac2b8SthorpejThe system-imposed limit on the total 873fdac2b8Sthorpejnumber of LWPs under execution would be exceeded. 883fdac2b8SthorpejThis limit is configuration-dependent. 893fdac2b8Sthorpej.It Bq Er EFAULT 903fdac2b8SthorpejThe address pointed to by 913fdac2b8Sthorpej.Fa context 923fdac2b8Sthorpejor 933fdac2b8Sthorpej.Fa new_lwp 943fdac2b8Sthorpejis outside the process's allocated address space. 956c3cc552Smartin.It Bq Er EINVAL 96*15c5c5f4SuweThe 97*15c5c5f4Suwe.Vt ucontext_t 98*15c5c5f4Suwepassed is invalid. 99014a9825Swiz.It Bq Er ENOMEM 100014a9825SwizThere is insufficient swap space for the new LWP. 1013fdac2b8Sthorpej.El 1023fdac2b8Sthorpej.Sh SEE ALSO 1033fdac2b8Sthorpej.Xr _lwp_continue 2 , 1043fdac2b8Sthorpej.Xr _lwp_exit 2 , 1053fdac2b8Sthorpej.Xr _lwp_wait 2 , 1063fdac2b8Sthorpej.Xr _lwp_makecontext 3 1073fdac2b8Sthorpej.Sh HISTORY 1083fdac2b8SthorpejThe 1093fdac2b8Sthorpej.Fn _lwp_create 1103fdac2b8Sthorpejsystem call first appeared in 1113fdac2b8Sthorpej.Nx 2.0 . 112