LGRAB(3PROC) Process Control Library Functions LGRAB(3PROC)
NAME
Lgrab - obtain a handle to control a thread
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#include <libproc.h> struct ps_lwphandle * Lgrab(
struct ps_prochandle *P,
lwpid_t lwpid,
int *perr);
DESCRIPTION
The
Lgrab() function obtains a control handle to the thread identified
by
lwpid residing under the process
P. This handle is then passed as
argument to other
libproc routines. The
lwpid can be obtained from the
pr_lwpid member of the
lwpstatus_t structure.
The
perr argument must point to a valid pointer that will be used to
store an error code in the event that
Lgrab() is unable to successfully
obtain a handle to the process. The possible errors are defined below
in the
ERRORS section. The code may be transformed into a human
readable string through the use of
Lgrab_error(3PROC).
The handle to the thread is valid until the
Lfree(3PROC) function is
called, which also releases associated resources from the handle. Only
a single handle to a specific thread may exist at any time. If the
handle already exists and another caller attempts to grab that thread,
it will result in an error. The caller must call
Lfree() before
releasing the handle associated with
P.
Unlike grabbing a process, grabbing a thread does not change the
current state of the thread. If it is running, it will remain running.
If it is stopped, it will remain stopped.
RETURN VALUES
Upon successful completion, the
Lgrab() function returns a pointer to
the control handle for the specified thread. Otherwise, the NULL
pointer is returned and
perr is set to indicate the error.
ERRORS
The
Lgrab() function will fail if:
G_BUSY Another handle already exists for the thread
identified by
lwpid. The handle need not exist in
the current process and may exist in another
process.
G_NOPROC The thread identified by
lwpid does not exist or has
already become a zombie.
G_STRANGE An unanticipated system error occurred while trying
to create the handle. When this occurs, then the
value of
errno is meaningful. See
errno(3C) for
more information and
Intro(2) for the list of
possible errors.
INTERFACE STABILITY
UncommittedMT-LEVEL MT-SafeSEE ALSO
errno(3C),
libproc(3LIB),
Lfree(3PROC),
Lgrab_error(3PROC),
proc(5)illumos November 27, 2023 illumos
