Annotation of src/lib/libc/sys/_lwp_create.2, Revision 1.9
1.9 ! andvar 1: .\" $NetBSD: _lwp_create.2,v 1.8 2021/07/31 20:51:32 andvar Exp $
1.2 thorpej 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: .\"
1.6 christos 30: .Dd April 21, 2017
1.2 thorpej 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
1.3 wiz 39: .In lwp.h
1.2 thorpej 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.
1.6 christos 50: The signal stack of the newly created light-weight process is reset to
51: disabled.
1.9 ! andvar 52: If this context specifies invalid register values (for example privilege
1.8 andvar 53: escalation by setting machine dependent bits forbidden for user processes),
1.5 martin 54: or does not specify cpu register values (uc_flags does not have the
55: _UC_CPU bit set), the call will fail and errno will be set to EINVAL.
1.2 thorpej 56: .Pp
57: The following flags affect the creation of the new LWP:
58: .Bl -tag -width LWP_SUSPENDED
59: .It LWP_DETACHED
60: The LWP is created detached.
61: The resources associated with a detached LWP will be automatically
62: reclaimed by the system when the LWP exits.
63: Otherwise, a terminated LWP's resources will not be reclaimed until
64: its status is reported to another LWP via
65: .Xr _lwp_wait 2 .
66: .It LWP_SUSPENDED
67: The LWP is created suspended, and will not begin execution until
68: it is resumed by another LWP via
69: .Xr _lwp_continue 2 .
70: .\" __LWP_ASLWP is not yet implemented by the NetBSD kernel.
71: .El
72: .Pp
73: The LWP ID of the new LWP is stored in the location pointed to by
74: .Fa new_lwp .
75: .Sh RETURN VALUES
76: Upon successful completion,
77: .Fn _lwp_create
78: returns a value of 0.
1.5 martin 79: Otherwise, a value of -1 is returned and errno is set to one of the values
80: documented below.
1.2 thorpej 81: .Sh ERRORS
82: .Fn _lwp_create
83: will fail and no LWP will be created if:
1.7 wiz 84: .Bl -tag -width 10n
1.2 thorpej 85: .It Bq Er EAGAIN
86: The system-imposed limit on the total
87: number of LWPs under execution would be exceeded.
88: This limit is configuration-dependent.
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.
1.5 martin 95: .It Bq Er EINVAL
96: The ucontext_t passed is invalid.
1.7 wiz 97: .It Bq Er ENOMEM
98: There is insufficient swap space for the new LWP.
1.2 thorpej 99: .El
100: .Sh SEE ALSO
101: .Xr _lwp_continue 2 ,
102: .Xr _lwp_exit 2 ,
103: .Xr _lwp_wait 2 ,
104: .Xr _lwp_makecontext 3
105: .Sh HISTORY
106: The
107: .Fn _lwp_create
108: system call first appeared in
109: .Nx 2.0 .
CVSweb <webmaster@jp.NetBSD.org>