_lwp_create(2) _lwp_create(2)
NAME
_lwp_create - create a new LWP associated with the current
process
SYNOPSIS
#include <sys/types.h>
#include <sys/lwp.h>
#include <uncontext.h>
int _lwp_create(ucontext_t *context, unsigned long flags,
lwpid_t *new_lwp);
Parameters
context pointer to the new LWP's context
flags attributes for the new LWP
new_lwp pointer to the identifier for the new LWP, set by
_lwp_create
DESCRIPTION
_lwp_create creates an independent lightweight process (LWP).
A stack area must have been allocated by user code before this
function is called. The stack area must be reclaimed by user
code after termination of the LWP.
_lwp_create may fail if the process is being traced via
ptrace.
The new LWP's scheduling class and priority are inherited from
its creator.
context Parameter
The context parameter is a pointer to the new LWP's context.
The new LWP's signal mask is set from the ucontext, with no
signals pending. Any per-LWP timers are cleared in the new
LWP.
flags Parameter
The flags parameter specifies attributes for the new LWP. Two
flags are defined:
LWP_DETACHED create the new LWP in the detached state. This
means that the LWP resources can be reclaimed
as soon as the LWP terminates - the DETACHED
state is a recycling hint to the
implementation.
Copyright 1994 Novell, Inc. Page 1
_lwp_create(2) _lwp_create(2)
LWP_SUSPENDED create the new LWP in a suspended state. This
state is orthogonal to all other stopped
states, and requires a call to _lwp_continue
before the created LWP can start its actual
execution.
new_lwp Parameter
_lwp_create sets the location pointed to by new_lwp to the
unique identifier that can be used to refer to the newly-
created LWP in subsequent function calls. Since an
implementation may recycle LWP identifiers, care should be
used in the application of lwpid_t values.
Return Values
_lwp_create returns zero for success and an error number on
failure, as described below.
Errors
If any of the following conditions is detected, _lwp_create
returns the corresponding value:
EFAULT The parameter context points to an illegal address.
EAGAIN A system limit would be exceeded if this call were
completed successfully, for example, a limit on
number of LWPs per real user ID would be exceeded.
EINVAL The process is being traced via ptrace.
A SIGSEGV may be generated instead of an EFAULT error
indication.
USAGE
Unlike threads, the start function called for _lwp_create
returns void. This means that there is no return value
available through _lwp_wait, and that less information from an
LWP context needs to be retained past _lwp_exit.
The kernel is not responsible for LWP stack allocation and
cleanup, so the responsibility for storage management is with
the user. The stack is allocated at user level, and should be
freed at or near the call of _lwp_exit.
Caching stacks of consistent size in user space should be a
useful performance enhancement for threads packages and other
applications that use LWPs directly.
Copyright 1994 Novell, Inc. Page 2
_lwp_create(2) _lwp_create(2)
A detached LWP works well for a bound and detached thread,
automatically cleaning up after thr_exit. This mechanism also
allows for automatic shrinking of the pool of parked LWPs.
Examples
context = malloc(sizeof(*context));
stackbase = malloc(stacksize);
_lwp_makecontext(&context, func, arg, private, stackbase, stacksize);
new = _lwp_create(&context, 0L, &newid);
REFERENCES
_lwp_continue(2), _lwp_exit(2), _lwp_getprivate(2),
_lwp_makecontext(2), _lwp_setprivate(2), _lwp_suspend(2),
getcontext(2), makecontext(3C), ucontext(5)
NOTICES
Lightweight processes (LWPs) are internal interfaces and are
subject to change. Their use should be avoided.
Copyright 1994 Novell, Inc. Page 3