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