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