lib/libc/sys/_lwp_create.2

   1 .\"     $NetBSD: _lwp_create.2,v 1.5 2012/05/21 14:15:16 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 If this context specifies invalid register values (for example priviledge
  51 escalation by setting machine dependend bits forbidden for user processes),
  52 or does not specify cpu register values (uc_flags does not have the
  53 _UC_CPU bit set), the call will fail and errno will be set to EINVAL.
  54 .Pp
  55 The following flags affect the creation of the new LWP:
  56 .Bl -tag -width LWP_SUSPENDED
  57 .It LWP_DETACHED
  58 The LWP is created detached.
  59 The resources associated with a detached LWP will be automatically
  60 reclaimed by the system when the LWP exits.
  61 Otherwise, a terminated LWP's resources will not be reclaimed until
  62 its status is reported to another LWP via
  63 .Xr _lwp_wait 2 .
  64 .It LWP_SUSPENDED
  65 The LWP is created suspended, and will not begin execution until
  66 it is resumed by another LWP via
  67 .Xr _lwp_continue 2 .
  68 .\" __LWP_ASLWP is not yet implemented by the NetBSD kernel.
  69 .El
  70 .Pp
  71 The LWP ID of the new LWP is stored in the location pointed to by
  72 .Fa new_lwp .
  73 .Sh RETURN VALUES
  74 Upon successful completion,
  75 .Fn _lwp_create
  76 returns a value of 0.
  77 Otherwise, a value of -1 is returned and errno is set to one of the values
  78 documented below.
  79 .Sh ERRORS
  80 .Fn _lwp_create
  81 will fail and no LWP will be created if:
  82 .Bl -tag -width [EAGAIN]
  83 .It Bq Er EAGAIN
  84 The system-imposed limit on the total
  85 number of LWPs under execution would be exceeded.
  86 This limit is configuration-dependent.
  87 .It Bq Er ENOMEM
  88 There is insufficient swap space for the new LWP.
  89 .It Bq Er EFAULT
  90 The address pointed to by
  91 .Fa context
  92 or
  93 .Fa new_lwp
  94 is outside the process's allocated address space.
  95 .It Bq Er EINVAL
  96 The ucontext_t passed is invalid.
  97 .El
  98 .Sh SEE ALSO
  99 .Xr _lwp_continue 2 ,
 100 .Xr _lwp_exit 2 ,
 101 .Xr _lwp_wait 2 ,
 102 .Xr _lwp_makecontext 3
 103 .Sh HISTORY
 104 The
 105 .Fn _lwp_create
 106 system call first appeared in
 107 .Nx 2.0 .