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