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