Tribblix: manual page: pctx

PCTX_CAPTURE(3CPC) CPU Performance Counters Library Functions

NAME

pctx_capture, pctx_create, pctx_run, pctx_release - process context
library

SYNOPSIS

cc [ flag... ] file... -lpctx [ library... ]
#include <libpctx.h>

typedef void (pctx_errfn_t)(const char *fn, const char *fmt, va_list ap);

pctx_t *pctx_create(const char *filename, char *const *argv, void *arg,
int verbose, pctx_errfn_t *errfn);

pctx_t *pctx_capture(pid_t pid, void *arg, int verbose,
pctx_errfn_t *errfn);

int pctx_run(pctx_t *pctx, uint_t sample, uint_t nsamples,
int (*tick)(pctx *, pid_t, id_t, void *));

void pctx_release(pctx_t *pctx);

DESCRIPTION

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.

pctx_create() and pctx_capture()
There are two ways a process can be acquired by the process context
functions. First, a named application can be invoked with the usual
argv[] array using pctx_create(), which forks the caller and execs
the application in the child. Alternatively, an existing process can
be captured by its process ID using pctx_capture().

Both functions accept a pointer to an opaque handle, arg; 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
printf(3C)-like error routine errfn; a default version is provided if
NULL is specified.

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 pctx_set_events(3CPC)
manual page.

pctx_run()
Once the callback handlers have been set with pctx_set_events(), the
application can be set running using pctx_run(). 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 exec-ed a setuid program).

Every sample milliseconds the process is stopped and the tick()
routine is called so that, for example, the performance counters can
be sampled by the caller. No periodic sampling is performed if sample
is 0.

pctx_release()
Once pctx_run() has returned, the process can be released and the
underlying storage freed using pctx_release(). 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 pctx_create()).

RETURN VALUES

Upon successful completion, pctx_capture() and pctx_create() return a
valid handle. Otherwise, the functions print a diagnostic message
and return NULL.

Upon successful completion, pctx_run() returns 0 with the controlled
process either stopped or exited (if the controlled process has
invoked exit(2).) If an error has occurred (for example, if the
controlled process has exec-ed a set-ID executable, if certain
callbacks have returned error indications, or if the process was
unable to respond to proc(5) requests) an error message is printed
and the function returns -1.

USAGE

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 cpc_pctx family of interfaces
in libcpc such as cpc_pctx_bind_event(3CPC). A specially created
agent LWP is used to execute these system calls in the controlled
process. See proc(5) for more details.

While executing the event handler functions, the library arranges for
the signals SIGTERM, SIGQUIT, SIGABRT, and SIGINT 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 LWP is still alive inside the
controlled process.