usr/src/man/man3cpc/pctx_capture.3cpc

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PCTX_CAPTURE 3CPC "May 13, 2003"
   7 .SH NAME
   8 pctx_capture, pctx_create, pctx_run, pctx_release \- process context library
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR... ] \fIfile\fR... \(milpctx [ \fIlibrary\fR... ]
  13 #include <libpctx.h>
  14
  15 \fBtypedef void\fR \fB(pctx_errfn_t)\fR(\fBconst char *\fR\fIfn\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBpctx_t *\fR\fBpctx_create\fR(\fBconst char *\fR\fIfilename\fR, \fBchar *const *\fR\fIargv\fR, \fBvoid *\fR\fIarg\fR,
  21      \fBint\fR \fIverbose\fR, \fBpctx_errfn_t *\fR\fIerrfn\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBpctx_t *\fR\fBpctx_capture\fR(\fBpid_t\fR \fIpid\fR, \fBvoid *\fR\fIarg\fR, \fBint\fR \fIverbose\fR,
  27      \fBpctx_errfn_t *\fR\fIerrfn\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBint\fR \fBpctx_run\fR(\fBpctx_t *\fR\fIpctx\fR, \fBuint_t\fR \fIsample\fR, \fBuint_t\fR \fInsamples\fR,
  33      \fBint (*\fR\fItick\fR)(pctx *, \fBpid_t, id_t, void *));\fR
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBvoid\fR \fBpctx_release\fR(\fBpctx_t *\fR\fIpctx\fR);
  39 .fi
  40
  41 .SH DESCRIPTION
  42 .sp
  43 .LP
  44 This family of functions allows a controlling process (the process that invokes
  45 them) to create or capture controlled processes.  The functions allow the
  46 occurrence of various events of interest in the controlled process to cause the
  47 controlled process to be stopped, and to cause callback routines to be invoked
  48 in the controlling process.
  49 .SS "\fBpctx_create()\fR and \fBpctx_capture()\fR"
  50 .sp
  51 .LP
  52 There are two ways a process can be acquired by the process context functions.
  53 First, a named application can be invoked with the usual \fIargv\fR[] array
  54 using \fBpctx_create()\fR, which forks the caller and \fBexec\fRs the
  55 application in the child. Alternatively, an existing process can be captured by
  56 its process \fBID\fR using \fBpctx_capture()\fR.
  57 .sp
  58 .LP
  59 Both functions accept a pointer to an opaque handle, \fIarg\fR; this is saved
  60 and treated as a caller-private handle that is passed to the other functions in
  61 the library.  Both functions accept a pointer to a \fBprintf\fR(3C)-like error
  62 routine \fIerrfn\fR; a default version is provided if \fINULL\fR is specified.
  63 .sp
  64 .LP
  65 A freshly-created process is created stopped; similarly, a process that has
  66 been successfully captured is stopped by the act of capturing it, thereby
  67 allowing the caller to specify the handlers that should be called when various
  68 events occur in the controlled process.  The set of handlers is listed on the
  69 \fBpctx_set_events\fR(3CPC) manual page.
  70 .SS "\fBpctx_run()\fR"
  71 .sp
  72 .LP
  73 Once the callback handlers have been set with \fBpctx_set_events()\fR, the
  74 application can be set running using \fBpctx_run()\fR. This function starts the
  75 event handling loop; it returns only when either the process has exited, the
  76 number of time samples has expired, or an error has occurred (for example, if
  77 the controlling process is not privileged, and the controlled process has
  78 \fBexec\fR-ed a setuid program).
  79 .sp
  80 .LP
  81 Every \fIsample\fR milliseconds the process is stopped and the \fItick\fR(\|)
  82 routine is called so that, for example, the performance counters can be sampled
  83 by the caller. No periodic sampling is performed if \fIsample\fR is 0.
  84 .SS "\fBpctx_release()\fR"
  85 .sp
  86 .LP
  87 Once  \fBpctx_run()\fR has returned, the process can be released and the
  88 underlying storage freed using \fBpctx_release()\fR. Releasing the process will
  89 either allow the controlled process to continue (in the case of an existing
  90 captured process and its children) or kill the process (if it and its children
  91 were created using \fBpctx_create()\fR).
  92 .SH RETURN VALUES
  93 .sp
  94 .LP
  95 Upon successful completion, \fBpctx_capture()\fR and \fBpctx_create()\fR return
  96 a valid handle.  Otherwise, the functions print a diagnostic message and return
  97 \fINULL\fR.
  98 .sp
  99 .LP
 100 Upon successful completion, \fBpctx_run()\fR returns \fB0\fR with the
 101 controlled process either stopped or exited (if the controlled process has
 102 invoked \fBexit\fR(2).) If an error has occurred (for example, if the
 103 controlled process has \fBexec\fR-ed a set-\fBID\fR executable, if certain
 104 callbacks have returned error indications, or if the process was unable to
 105 respond to \fBproc\fR(4) requests) an error message is printed and the function
 106 returns \(mi1.
 107 .SH USAGE
 108 .sp
 109 .LP
 110 Within an event handler in the controlling process, the controlled process can
 111 be made to perform various system calls on its behalf. No system calls are
 112 directly supported in this version of the API, though system calls are executed
 113 by the \fBcpc_pctx\fR family of interfaces in \fBlibcpc\fR such as
 114 \fBcpc_pctx_bind_event\fR(3CPC). A specially created agent \fBLWP\fR is used to
 115 execute these system calls in the controlled process. See \fBproc\fR(4) for
 116 more details.
 117 .sp
 118 .LP
 119 While executing the event handler functions, the library arranges for the
 120 signals \fBSIGTERM\fR, \fBSIGQUIT\fR, \fBSIGABRT\fR, and \fBSIGINT\fR to be
 121 blocked to reduce the likelihood of a keyboard signal killing the controlling
 122 process prematurely, thereby leaving the controlled process permanently stopped
 123 while the agent \fBLWP\fR is still alive inside the controlled process.
 124 .SH ATTRIBUTES
 125 .sp
 126 .LP
 127 See \fBattributes\fR(5) for descriptions of the following attributes:
 128 .sp
 129
 130 .sp
 131 .TS
 132 box;
 133 c | c
 134 l | l .
 135 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 136 _
 137 Interface Stability     Evolving
 138 _
 139 MT-Level        Unsafe
 140 .TE
 141
 142 .SH SEE ALSO
 143 .sp
 144 .LP
 145 \fBfork\fR(2), \fBcpc\fR(3CPC), \fBpctx_set_events\fR(3CPC),
 146 \fBlibpctx\fR(3LIB), \fBproc\fR(4), \fBattributes\fR(5)