LGRAB(3PROC) Process Control Library Functions LGRAB(3PROC)

Lgrabobtain a handle to control a thread

Process Control Library (libproc, -lproc)

#include <libproc.h>

struct ps_lwphandle *
Lgrab(struct ps_prochandle *P, lwpid_t lwpid, int *perr);

The () 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 routines. The lwpid can be obtained from the member of the structure.

The perr argument must point to a valid pointer that will be used to store an error code in the event that () 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 () 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.

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.

The Lgrab() function will fail if:

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.
The thread identified by lwpid does not exist or has already become a zombie.
An unanticipated system error occurred while trying to create the handle. When this occurs, then the value of is meaningful. See errno(3C) for more information and Intro(2) for the list of possible errors.

errno(3C), libproc(3LIB), Lfree(3PROC), Lgrab_error(3PROC), proc(5)

November 27, 2023 OmniOS