usr/src/man/man3cpc/cpc_pctx_bind_event.3cpc

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH CPC_PCTX_BIND_EVENT 3CPC "Mar 05, 2007"
   7 .SH NAME
   8 cpc_pctx_bind_event, cpc_pctx_take_sample, cpc_pctx_rele, cpc_pctx_invalidate
   9 \- access CPU performance counters in other processes
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc \(milpctx [ \fIlibrary\fR... ]
  14 #include <libpctx.h>
  15 #include <libcpc.h>
  16
  17 \fBint\fR \fBcpc_pctx_bind_event\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR, \fBcpc_event_t *\fR\fIevent\fR,
  18      \fBint\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBcpc_pctx_take_sample\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR, \fBcpc_event_t *\fR\fIevent\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBcpc_pctx_rele\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBcpc_pctx_invalidate\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR);
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .sp
  38 .LP
  39 These functions are designed to be run in the context of an event handler
  40 created using the \fBlibpctx\fR(3LIB) family of functions that allow the
  41 caller, also known as the \fIcontrolling process\fR, to manipulate the
  42 performance counters in the context of a \fIcontrolled process\fR. The
  43 controlled process is described by the \fIpctx\fR argument, which must be
  44 obtained from an invocation of \fBpctx_capture\fR(3CPC) or
  45 \fBpctx_create\fR(3CPC) and passed to the functions described on this page in
  46 the context of an event handler.
  47 .sp
  48 .LP
  49 The semantics of the functions \fBcpc_pctx_bind_event()\fR,
  50 \fBcpc_pctx_take_sample()\fR, and \fBcpc_pctx_rele()\fR are directly analogous
  51 to those of \fBcpc_bind_event()\fR, \fBcpc_take_sample()\fR, and
  52 \fBcpc_rele()\fR described on the \fBcpc_bind_event\fR(3CPC) manual page.
  53 .sp
  54 .LP
  55 The \fBcpc_pctx_invalidate()\fR function allows the performance context to be
  56 invalidated in an \fBLWP\fR in the controlled process.
  57 .SH RETURN VALUES
  58 .sp
  59 .LP
  60 These functions return \fB0\fR on success.  On failure, they return \fB\(mi1\fR
  61 and set \fBerrno\fR to indicate the error.
  62 .SH ERRORS
  63 .sp
  64 .LP
  65 The \fBcpc_pctx_bind_event()\fR, \fBcpc_pctx_take_sample()\fR, and
  66 \fBcpc_pctx_rele()\fR functions return the same \fBerrno\fR values the
  67 analogous functions described on the \fBcpc_bind_event\fR(3CPC) manual page. In
  68 addition, these function may fail if:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBEACCES\fR\fR
  73 .ad
  74 .RS 10n
  75 For \fBcpc_pctx_bind_event()\fR, access to the requested hypervisor event was
  76 denied.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBESRCH\fR\fR
  83 .ad
  84 .RS 10n
  85 The value of the \fIlwpid\fR argument is invalid in the context of the
  86 controlled process.
  87 .RE
  88
  89 .SH ATTRIBUTES
  90 .sp
  91 .LP
  92 See \fBattributes\fR(5) for descriptions of the following attributes:
  93 .sp
  94
  95 .sp
  96 .TS
  97 box;
  98 c | c
  99 l | l .
 100 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 101 _
 102 MT-Level        Unsafe
 103 _
 104 Interface Stability     Evolving
 105 .TE
 106
 107 .SH SEE ALSO
 108 .sp
 109 .LP
 110 \fBcpc\fR(3CPC), \fBcpc_bind_event\fR(3CPC), \fBlibcpc\fR(3LIB),
 111 \fBpctx_capture\fR(3CPC), \fBpctx_create\fR(3CPC), \fBattributes\fR(5)
 112 .SH NOTES
 113 .sp
 114 .LP
 115 The \fBcpc_pctx_bind_event()\fR, \fBcpc_pctx_invalidate()\fR,
 116 \fBcpc_pctx_rele()\fR, and \fBcpc_pctx_take_sample()\fR functions exist for
 117 binary compatibility only. Source containing these functions will not compile.
 118 These functions are obsolete and might be removed in a future release.
 119 Applications should use \fBcpc_bind_pctx\fR(3CPC), \fBcpc_unbind\fR(3CPC), and
 120 \fBcpc_set_sample\fR(3CPC) instead.
 121 .sp
 122 .LP
 123 The capability to create and analyze overflow events in other processes is not
 124 available, though it may be made available in a future version of this API.  In
 125 the current implementation, the \fIflags\fR field must be specified as 0.