Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

cpc_pctx_bind_event(3cpc) [opensolaris man page]

cpc_pctx_bind_event(3CPC)			    CPU Performance Counters Library Functions				 cpc_pctx_bind_event(3CPC)

NAME
cpc_pctx_bind_event, cpc_pctx_take_sample, cpc_pctx_rele, cpc_pctx_invalidate - access CPU performance counters in other processes SYNOPSIS
cc [ flag... ] file... -lcpc -lpctx [ library... ] #include <libpctx.h> #include <libcpc.h> int cpc_pctx_bind_event(pctx_t *pctx, id_t lwpid, cpc_event_t *event, int flags); int cpc_pctx_take_sample(pctx_t *pctx, id_t lwpid, cpc_event_t *event); int cpc_pctx_rele(pctx_t *pctx, id_t lwpid); int cpc_pctx_invalidate(pctx_t *pctx, id_t lwpid); DESCRIPTION
These functions are designed to be run in the context of an event handler created using the libpctx(3LIB) family of functions that allow the caller, also known as the controlling process, to manipulate the performance counters in the context of a controlled process. The con- trolled process is described by the pctx argument, which must be obtained from an invocation of pctx_capture(3CPC) or pctx_create(3CPC) and passed to the functions described on this page in the context of an event handler. The semantics of the functions cpc_pctx_bind_event(), cpc_pctx_take_sample(), and cpc_pctx_rele() are directly analogous to those of cpc_bind_event(), cpc_take_sample(), and cpc_rele() described on the cpc_bind_event(3CPC) manual page. The cpc_pctx_invalidate() function allows the performance context to be invalidated in an LWP in the controlled process. RETURN VALUES
These functions return 0 on success. On failure, they return -1 and set errno to indicate the error. ERRORS
The cpc_pctx_bind_event(), cpc_pctx_take_sample(), and cpc_pctx_rele() functions return the same errno values the analogous functions described on the cpc_bind_event(3CPC) manual page. In addition, these function may fail if: EACCES For cpc_pctx_bind_event(), access to the requested hypervisor event was denied. ESRCH The value of the lwpid argument is invalid in the context of the controlled process. ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |MT-Level |Unsafe | +-----------------------------+-----------------------------+ |Interface Stability |Evolving | +-----------------------------+-----------------------------+ SEE ALSO
cpc(3CPC), cpc_bind_event(3CPC), libcpc(3LIB), pctx_capture(3CPC), pctx_create(3CPC), attributes(5) NOTES
The cpc_pctx_bind_event(), cpc_pctx_invalidate(), cpc_pctx_rele(), and cpc_pctx_take_sample() functions exist for binary compatibility only. Source containing these functions will not compile. These functions are obsolete and might be removed in a future release. Applica- tions should use cpc_bind_pctx(3CPC), cpc_unbind(3CPC), and cpc_set_sample(3CPC) instead. The capability to create and analyze overflow events in other processes is not available, though it may be made available in a future ver- sion of this API. In the current implementation, the flags field must be specified as 0. SunOS 5.11 05 Mar 2007 cpc_pctx_bind_event(3CPC)

Check Out this Related Man Page

pctx_capture(3CPC)				    CPU Performance Counters Library Functions					pctx_capture(3CPC)

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 func- tions 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(4) 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(4) 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. ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Interface Stability |Evolving | +-----------------------------+-----------------------------+ |MT-Level |Unsafe | +-----------------------------+-----------------------------+ SEE ALSO
fork(2), cpc(3CPC), pctx_set_events(3CPC), libpctx(3LIB), proc(4), attributes(5) SunOS 5.11 13 May 2003 pctx_capture(3CPC)
Man Page