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