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