1*f14fb602SLionel Sambuc.\" $NetBSD: _lwp_create.2,v 1.5 2012/05/21 14:15:16 martin Exp $ 22fe8fb19SBen Gras.\" 32fe8fb19SBen Gras.\" Copyright (c) 2003 The NetBSD Foundation, Inc. 42fe8fb19SBen Gras.\" All rights reserved. 52fe8fb19SBen Gras.\" 62fe8fb19SBen Gras.\" This code is derived from software contributed to The NetBSD Foundation 72fe8fb19SBen Gras.\" by Jason R. Thorpe of Wasabi Systems, Inc. 82fe8fb19SBen Gras.\" 92fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without 102fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions 112fe8fb19SBen Gras.\" are met: 122fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright 132fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer. 142fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright 152fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer in the 162fe8fb19SBen Gras.\" documentation and/or other materials provided with the distribution. 172fe8fb19SBen Gras.\" 182fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 192fe8fb19SBen Gras.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 202fe8fb19SBen Gras.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 212fe8fb19SBen Gras.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 222fe8fb19SBen Gras.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 232fe8fb19SBen Gras.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 242fe8fb19SBen Gras.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 252fe8fb19SBen Gras.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 262fe8fb19SBen Gras.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 272fe8fb19SBen Gras.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 282fe8fb19SBen Gras.\" POSSIBILITY OF SUCH DAMAGE. 292fe8fb19SBen Gras.\" 302fe8fb19SBen Gras.Dd January 13, 2003 312fe8fb19SBen Gras.Dt _LWP_CREATE 2 322fe8fb19SBen Gras.Os 332fe8fb19SBen Gras.Sh NAME 342fe8fb19SBen Gras.Nm _lwp_create 352fe8fb19SBen Gras.Nd create a new light-weight process 362fe8fb19SBen Gras.Sh LIBRARY 372fe8fb19SBen Gras.Lb libc 382fe8fb19SBen Gras.Sh SYNOPSIS 392fe8fb19SBen Gras.In lwp.h 402fe8fb19SBen Gras.Ft int 412fe8fb19SBen Gras.Fn _lwp_create "ucontext_t *context" "unsigned long flags" "lwpid_t *new_lwp" 422fe8fb19SBen Gras.Sh DESCRIPTION 432fe8fb19SBen Gras.Fn _lwp_create 442fe8fb19SBen Grascauses creation of a new light-weight process, or LWP, and adds it to the 452fe8fb19SBen Grascurrent process. 462fe8fb19SBen GrasThe 472fe8fb19SBen Gras.Fa context 482fe8fb19SBen Grasargument specifies the initial execution context for the new LWP including 492fe8fb19SBen Grassignal mask, stack, and machine registers. 50*f14fb602SLionel SambucIf this context specifies invalid register values (for example priviledge 51*f14fb602SLionel Sambucescalation by setting machine dependend bits forbidden for user processes), 52*f14fb602SLionel Sambucor does not specify cpu register values (uc_flags does not have the 53*f14fb602SLionel Sambuc_UC_CPU bit set), the call will fail and errno will be set to EINVAL. 542fe8fb19SBen Gras.Pp 552fe8fb19SBen GrasThe following flags affect the creation of the new LWP: 562fe8fb19SBen Gras.Bl -tag -width LWP_SUSPENDED 572fe8fb19SBen Gras.It LWP_DETACHED 582fe8fb19SBen GrasThe LWP is created detached. 592fe8fb19SBen GrasThe resources associated with a detached LWP will be automatically 602fe8fb19SBen Grasreclaimed by the system when the LWP exits. 612fe8fb19SBen GrasOtherwise, a terminated LWP's resources will not be reclaimed until 622fe8fb19SBen Grasits status is reported to another LWP via 632fe8fb19SBen Gras.Xr _lwp_wait 2 . 642fe8fb19SBen Gras.It LWP_SUSPENDED 652fe8fb19SBen GrasThe LWP is created suspended, and will not begin execution until 662fe8fb19SBen Grasit is resumed by another LWP via 672fe8fb19SBen Gras.Xr _lwp_continue 2 . 682fe8fb19SBen Gras.\" __LWP_ASLWP is not yet implemented by the NetBSD kernel. 692fe8fb19SBen Gras.El 702fe8fb19SBen Gras.Pp 712fe8fb19SBen GrasThe LWP ID of the new LWP is stored in the location pointed to by 722fe8fb19SBen Gras.Fa new_lwp . 732fe8fb19SBen Gras.Sh RETURN VALUES 742fe8fb19SBen GrasUpon successful completion, 752fe8fb19SBen Gras.Fn _lwp_create 762fe8fb19SBen Grasreturns a value of 0. 77*f14fb602SLionel SambucOtherwise, a value of -1 is returned and errno is set to one of the values 78*f14fb602SLionel Sambucdocumented below. 792fe8fb19SBen Gras.Sh ERRORS 802fe8fb19SBen Gras.Fn _lwp_create 812fe8fb19SBen Graswill fail and no LWP will be created if: 822fe8fb19SBen Gras.Bl -tag -width [EAGAIN] 832fe8fb19SBen Gras.It Bq Er EAGAIN 842fe8fb19SBen GrasThe system-imposed limit on the total 852fe8fb19SBen Grasnumber of LWPs under execution would be exceeded. 862fe8fb19SBen GrasThis limit is configuration-dependent. 872fe8fb19SBen Gras.It Bq Er ENOMEM 882fe8fb19SBen GrasThere is insufficient swap space for the new LWP. 892fe8fb19SBen Gras.It Bq Er EFAULT 902fe8fb19SBen GrasThe address pointed to by 912fe8fb19SBen Gras.Fa context 922fe8fb19SBen Grasor 932fe8fb19SBen Gras.Fa new_lwp 942fe8fb19SBen Grasis outside the process's allocated address space. 95*f14fb602SLionel Sambuc.It Bq Er EINVAL 96*f14fb602SLionel SambucThe ucontext_t passed is invalid. 972fe8fb19SBen Gras.El 982fe8fb19SBen Gras.Sh SEE ALSO 992fe8fb19SBen Gras.Xr _lwp_continue 2 , 1002fe8fb19SBen Gras.Xr _lwp_exit 2 , 1012fe8fb19SBen Gras.Xr _lwp_wait 2 , 1022fe8fb19SBen Gras.Xr _lwp_makecontext 3 1032fe8fb19SBen Gras.Sh HISTORY 1042fe8fb19SBen GrasThe 1052fe8fb19SBen Gras.Fn _lwp_create 1062fe8fb19SBen Grassystem call first appeared in 1072fe8fb19SBen Gras.Nx 2.0 . 108