CPC_PCTX_BIND_EVENT(3CPC) CPU Performance Counters Library Functions


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
controlled 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. Applications 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 version of
this API. In the current implementation, the flags field must be
specified as 0.


March 5, 2007 CPC_PCTX_BIND_EVENT(3CPC)