lib/libc/sys/_lwp_create.2

   1 .\"     $NetBSD: _lwp_create.2,v 1.4 2008/04/30 13:10:51 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Jason R. Thorpe of Wasabi Systems, Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd January 13, 2003
  31 .Dt _LWP_CREATE 2
  32 .Os
  33 .Sh NAME
  34 .Nm _lwp_create
  35 .Nd create a new light-weight process
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In lwp.h
  40 .Ft int
  41 .Fn _lwp_create "ucontext_t *context" "unsigned long flags" "lwpid_t *new_lwp"
  42 .Sh DESCRIPTION
  43 .Fn _lwp_create
  44 causes creation of a new light-weight process, or LWP, and adds it to the
  45 current process.
  46 The
  47 .Fa context
  48 argument specifies the initial execution context for the new LWP including
  49 signal mask, stack, and machine registers.
  50 .Pp
  51 The following flags affect the creation of the new LWP:
  52 .Bl -tag -width LWP_SUSPENDED
  53 .It LWP_DETACHED
  54 The LWP is created detached.
  55 The resources associated with a detached LWP will be automatically
  56 reclaimed by the system when the LWP exits.
  57 Otherwise, a terminated LWP's resources will not be reclaimed until
  58 its status is reported to another LWP via
  59 .Xr _lwp_wait 2 .
  60 .It LWP_SUSPENDED
  61 The LWP is created suspended, and will not begin execution until
  62 it is resumed by another LWP via
  63 .Xr _lwp_continue 2 .
  64 .\" __LWP_ASLWP is not yet implemented by the NetBSD kernel.
  65 .El
  66 .Pp
  67 The LWP ID of the new LWP is stored in the location pointed to by
  68 .Fa new_lwp .
  69 .Sh RETURN VALUES
  70 Upon successful completion,
  71 .Fn _lwp_create
  72 returns a value of 0.
  73 Otherwise, an error code is returned to indicate the error.
  74 .Sh ERRORS
  75 .Fn _lwp_create
  76 will fail and no LWP will be created if:
  77 .Bl -tag -width [EAGAIN]
  78 .It Bq Er EAGAIN
  79 The system-imposed limit on the total
  80 number of LWPs under execution would be exceeded.
  81 This limit is configuration-dependent.
  82 .It Bq Er ENOMEM
  83 There is insufficient swap space for the new LWP.
  84 .It Bq Er EFAULT
  85 The address pointed to by
  86 .Fa context
  87 or
  88 .Fa new_lwp
  89 is outside the process's allocated address space.
  90 .El
  91 .Sh SEE ALSO
  92 .Xr _lwp_continue 2 ,
  93 .Xr _lwp_exit 2 ,
  94 .Xr _lwp_wait 2 ,
  95 .Xr _lwp_makecontext 3
  96 .Sh HISTORY
  97 The
  98 .Fn _lwp_create
  99 system call first appeared in
 100 .Nx 2.0 .