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