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