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 PLWP_GETSPYMASTER 3PROC 16.Os 17.Sh NAME 18.Nm Plwp_getspymaster 19.Nd get agent LWP spy master information 20.Sh LIBRARY 21.Lb libproc 22.Sh SYNOPSIS 23.In libproc.h 24.Ft int 25.Fo Plwp_getspymaster 26.Fa "struct ps_prochandle *P" 27.Fa "lwpid_t lwpid" 28.Fa "psinfo_t *ps" 29.Fc 30.Sh DESCRIPTION 31The 32.Fn Plwp_getspymaster 33function returns information about the spy master that corresponds to 34the agent LWP for the thread 35.Fa lwpid 36in the process handle 37.Fa P . 38.Pp 39The agent LWP allows another process to inject actions into the target process. 40When an agent LWP is created, it leverages an existing thread in the process and 41it also creates a record of whom created the agent, which is called the spy 42master. 43For more information on the agent LWP and the spy master, see 44.Xr proc 4 . 45.Pp 46If the thread identified 47.Fa lwpid 48has an agent LWP, the corresponding ps information 49.Po see 50.Xr proc 4 51for the definition of the 52.Sy psinfo_t 53.Pc 54will be filled into 55.Fa ps . 56.Pp 57Note, process handles that correspond to a file, created by 58.Xr Pgrab_file 3PROC , 59cannot have an agent LWP created for them and thus cannot have any spy 60master information. 61In addition, core files from older releases may not have any data on the spy 62master. 63.Sh RETURN VALUES 64Upon successful completion, the 65.Fn Plwp_getspymaster 66returns 67.Sy 0 68and updates 69.Fa ps . 70Otherwise, it returns 71.Sy -1 , 72sets 73.Sy errno , 74and 75.Fa ps 76is not modified. 77.Sh ERRORS 78For a full list of possible errors also see the 79.Sy DIAGNOSTICS 80section in 81.Xr proc 4 . 82.Pp 83The 84.Fn Plwp_getpsinfo 85function will fail if: 86.Bl -tag -width Er 87.It Er ENODATA 88.Fa P 89refers to a file handle obtained through 90.Xr Pgrab_file 3PROC 91or 92.Fa P 93does not have any information about the spy master. 94.It Er EINVAL 95The process handle 96.Fa P 97refers to a core file and the specified thread does not exist. 98.Pp 99The thread, 100.Fa lwpid 101does not have an active agent, 102.Dv PR_AGENT 103is not set in the 104.Sy pr_flags 105member of the thread's status information. 106.It Er ENOENT 107The process handle 108.Fa P 109refers to an active process and the specified thread does not exist. 110.El 111.Sh INTERFACE STABILITY 112.Sy Uncommitted 113.Sh MT-LEVEL 114See 115.Sy LOCKING 116in 117.Xr libproc 3LIB . 118.Sh SEE ALSO 119.Xr libproc 3LIB , 120.Xr proc 4 121