illumos: manual page: Lgrab.3proc

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

Uncommitted

MT-LEVEL
MT-Safe