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