share/man/man3proc/Pcreate_agent.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 PCREATE_AGENT 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pcreate_agent
  19 .Nd create the agent LWP
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft int
  24 .Fo Pcreate_agent
  25 .Fa "struct ps_prochandle *P"
  26 .Fc
  27 .Sh DESCRIPTION
  28 The
  29 .Fn Pcreate_agent
  30 function creates the agent LWP in the process represented by the handle
  31 .Fa P .
  32 The agent LWP is used as a means to force system calls to be invoked on
  33 the controlled process.
  34 For more information on the agent LWP, see
  35 .Xr proc 4 .
  36 .Pp
  37 The agent LWP cannot be created for process handles corresponding to
  38 core files, zombie processes, processes that have yet to run, and ELF
  39 objects.
  40 .Pp
  41 The
  42 .Fn Pcreate_agent
  43 function is reentrant.
  44 It may be entered recursively.
  45 The act of creating the agent LWP will cause the process to be stopped.
  46 For every call to the
  47 .Fn Pcreate_agent
  48 function, a corresponding call to
  49 .Xr Pdestroy_agent 3PROC
  50 is required.
  51 .Sh RETURN VALUES
  52 Upon successful completion, the
  53 .Fn Pcreate_agent
  54 function returns
  55 .Sy 0
  56 and creates the agent LWP.
  57 Otherwise,
  58 .Sy -1
  59 is returned,
  60 .Sy errno
  61 is set to indicate the error, and the agent LWP is not created.
  62 .Sh ERRORS
  63 The
  64 .Fn Pcreate_agent
  65 function will fail if:
  66 .Bl -tag -width Er
  67 .It Er ENOENT
  68 The process referred to by
  69 .Fa P
  70 is a core file, zombie, ELF object, or has not begun execution.
  71 .El
  72 .Pp
  73 Note, it is possible for other error numbers to be returned.
  74 If they are, they represent unanticipated failure.
  75 .Sh INTERFACE STABILITY
  76 .Sy Uncommitted
  77 .Sh MT-LEVEL
  78 See
  79 .Sy LOCKING
  80 in
  81 .Xr libproc 3LIB .
  82 .Sh SEE ALSO
  83 .Xr libproc 3LIB ,
  84 .Xr Pdestroy_agent 3PROC ,
  85 .Xr proc 4