'\" te .\" Copyright (c) 2003, Sun Microsystems, Inc. .\" 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. .\" 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. .\" 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] .TH PCTX_CAPTURE 3CPC "May 13, 2003" .SH NAME pctx_capture, pctx_create, pctx_run, pctx_release \- process context library .SH SYNOPSIS .LP .nf cc [ \fIflag\fR... ] \fIfile\fR... \(milpctx [ \fIlibrary\fR... ] #include \fBtypedef void\fR \fB(pctx_errfn_t)\fR(\fBconst char *\fR\fIfn\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR); .fi .LP .nf \fBpctx_t *\fR\fBpctx_create\fR(\fBconst char *\fR\fIfilename\fR, \fBchar *const *\fR\fIargv\fR, \fBvoid *\fR\fIarg\fR, \fBint\fR \fIverbose\fR, \fBpctx_errfn_t *\fR\fIerrfn\fR); .fi .LP .nf \fBpctx_t *\fR\fBpctx_capture\fR(\fBpid_t\fR \fIpid\fR, \fBvoid *\fR\fIarg\fR, \fBint\fR \fIverbose\fR, \fBpctx_errfn_t *\fR\fIerrfn\fR); .fi .LP .nf \fBint\fR \fBpctx_run\fR(\fBpctx_t *\fR\fIpctx\fR, \fBuint_t\fR \fIsample\fR, \fBuint_t\fR \fInsamples\fR, \fBint (*\fR\fItick\fR)(pctx *, \fBpid_t, id_t, void *));\fR .fi .LP .nf \fBvoid\fR \fBpctx_release\fR(\fBpctx_t *\fR\fIpctx\fR); .fi .SH DESCRIPTION .sp .LP This family of functions allows a controlling process (the process that invokes them) to create or capture controlled processes. The functions allow the occurrence of various events of interest in the controlled process to cause the controlled process to be stopped, and to cause callback routines to be invoked in the controlling process. .SS "\fBpctx_create()\fR and \fBpctx_capture()\fR" .sp .LP There are two ways a process can be acquired by the process context functions. First, a named application can be invoked with the usual \fIargv\fR[] array using \fBpctx_create()\fR, which forks the caller and \fBexec\fRs the application in the child. Alternatively, an existing process can be captured by its process \fBID\fR using \fBpctx_capture()\fR. .sp .LP Both functions accept a pointer to an opaque handle, \fIarg\fR; this is saved and treated as a caller-private handle that is passed to the other functions in the library. Both functions accept a pointer to a \fBprintf\fR(3C)-like error routine \fIerrfn\fR; a default version is provided if \fINULL\fR is specified. .sp .LP A freshly-created process is created stopped; similarly, a process that has been successfully captured is stopped by the act of capturing it, thereby allowing the caller to specify the handlers that should be called when various events occur in the controlled process. The set of handlers is listed on the \fBpctx_set_events\fR(3CPC) manual page. .SS "\fBpctx_run()\fR" .sp .LP Once the callback handlers have been set with \fBpctx_set_events()\fR, the application can be set running using \fBpctx_run()\fR. This function starts the event handling loop; it returns only when either the process has exited, the number of time samples has expired, or an error has occurred (for example, if the controlling process is not privileged, and the controlled process has \fBexec\fR-ed a setuid program). .sp .LP Every \fIsample\fR milliseconds the process is stopped and the \fItick\fR(\|) routine is called so that, for example, the performance counters can be sampled by the caller. No periodic sampling is performed if \fIsample\fR is 0. .SS "\fBpctx_release()\fR" .sp .LP Once \fBpctx_run()\fR has returned, the process can be released and the underlying storage freed using \fBpctx_release()\fR. Releasing the process will either allow the controlled process to continue (in the case of an existing captured process and its children) or kill the process (if it and its children were created using \fBpctx_create()\fR). .SH RETURN VALUES .sp .LP Upon successful completion, \fBpctx_capture()\fR and \fBpctx_create()\fR return a valid handle. Otherwise, the functions print a diagnostic message and return \fINULL\fR. .sp .LP Upon successful completion, \fBpctx_run()\fR returns \fB0\fR with the controlled process either stopped or exited (if the controlled process has invoked \fBexit\fR(2).) If an error has occurred (for example, if the controlled process has \fBexec\fR-ed a set-\fBID\fR executable, if certain callbacks have returned error indications, or if the process was unable to respond to \fBproc\fR(5) requests) an error message is printed and the function returns \(mi1. .SH USAGE .sp .LP Within an event handler in the controlling process, the controlled process can be made to perform various system calls on its behalf. No system calls are directly supported in this version of the API, though system calls are executed by the \fBcpc_pctx\fR family of interfaces in \fBlibcpc\fR such as \fBcpc_pctx_bind_event\fR(3CPC). A specially created agent \fBLWP\fR is used to execute these system calls in the controlled process. See \fBproc\fR(5) for more details. .sp .LP While executing the event handler functions, the library arranges for the signals \fBSIGTERM\fR, \fBSIGQUIT\fR, \fBSIGABRT\fR, and \fBSIGINT\fR to be blocked to reduce the likelihood of a keyboard signal killing the controlling process prematurely, thereby leaving the controlled process permanently stopped while the agent \fBLWP\fR is still alive inside the controlled process. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(7) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Evolving _ MT-Level Unsafe .TE .SH SEE ALSO .sp .LP .BR fork (2), .BR cpc (3CPC), .BR pctx_set_events (3CPC), .BR libpctx (3LIB), .BR proc (5), .BR attributes (7)