1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" 14.Dd November 27, 2023 15.Dt LGRAB 3PROC 16.Os 17.Sh NAME 18.Nm Lgrab 19.Nd obtain a handle to control a thread 20.Sh LIBRARY 21.Lb libproc 22.Sh SYNOPSIS 23.In libproc.h 24.Ft "struct ps_lwphandle *" 25.Fo Lgrab 26.Fa "struct ps_prochandle *P" 27.Fa "lwpid_t lwpid" 28.Fa "int *perr" 29.Fc 30.Sh DESCRIPTION 31The 32.Fn Lgrab 33function obtains a control handle to the thread identified by 34.Fa lwpid 35residing under the process 36.Fa P . 37This handle is then passed as argument to other 38.Sy libproc 39routines. 40The 41.Fa lwpid 42can be obtained from the 43.Sy pr_lwpid 44member of the 45.Sy lwpstatus_t 46structure. 47.Pp 48The 49.Fa perr 50argument must point to a valid pointer that will be used to store an 51error code in the event that 52.Fn Lgrab 53is unable to successfully obtain a handle to the process. 54The possible errors are defined below in the 55.Sx ERRORS 56section. 57The code may be transformed into a human readable string through the use of 58.Xr Lgrab_error 3PROC . 59.Pp 60The handle to the thread is valid until the 61.Xr Lfree 3PROC 62function is called, which also releases associated resources from the handle. 63Only a single handle to a specific thread may exist at any time. 64If the handle already exists and another caller attempts to grab 65that thread, it will result in an error. 66The caller must call 67.Fn Lfree 68before releasing the handle associated with 69.Fa P . 70.Pp 71Unlike grabbing a process, grabbing a thread does not change the current 72state of the thread. 73If it is running, it will remain running. 74If it is stopped, it will remain stopped. 75.Sh RETURN VALUES 76Upon successful completion, the 77.Fn Lgrab 78function returns a pointer to the control handle for the specified thread. 79Otherwise, the 80.Dv NULL 81pointer is returned and 82.Fa perr 83is set to indicate the error. 84.Sh ERRORS 85The 86.Fn Lgrab 87function will fail if: 88.Bl -tag -width Er 89.It Er G_BUSY 90Another handle already exists for the thread identified by 91.Fa lwpid . 92The handle need not exist in the current process and may exist in 93another process. 94.It Er G_NOPROC 95The thread identified by 96.Fa lwpid 97does not exist or has already become a zombie. 98.It Er G_STRANGE 99An unanticipated system error occurred while trying to create the handle. 100When this occurs, then the value of 101.Sy errno 102is meaningful. 103See 104.Xr errno 3C 105for more information and 106.Xr Intro 2 107for the list of possible errors. 108.El 109.Sh INTERFACE STABILITY 110.Sy Uncommitted 111.Sh MT-LEVEL 112.Sy MT-Safe 113.Sh SEE ALSO 114.Xr errno 3C , 115.Xr libproc 3LIB , 116.Xr Lfree 3PROC , 117.Xr Lgrab_error 3PROC , 118.Xr proc 5 119