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