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