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