share/man/man3proc/Plwp_getspymaster.3proc

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