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(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|MT-Level | Unsafe |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
SEE ALSO
cpc(3CPC),
cpc_bind_event(3CPC),
pctx_capture(3CPC),
pctx_create(3CPC),
libcpc(3LIB),
attributes(7)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)
