share/man/man3cpc/cpc_count_usr_events.3cpc

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.
   3 .\" All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH CPC_COUNT_USR_EVENTS 3CPC "Mar 28, 2005"
   8 .SH NAME
   9 cpc_count_usr_events, cpc_count_sys_events \- enable and disable performance
  10 counters
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ]
  15 #include <libcpc.h>
  16
  17 \fBint\fR \fBcpc_count_usr_events\fR(\fBint\fR \fIenable\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBcpc_count_sys_events\fR(\fBint\fR \fIenable\fR);
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 In certain applications, it can be useful to explicitly enable and disable
  29 performance counters at different times so that the performance of a critical
  30 algorithm can be examined.  The \fBcpc_count_usr_events()\fR function can be
  31 used to control whether events are counted on behalf of the application running
  32 in user mode, while \fBcpc_count_sys_events()\fR can be used to control whether
  33 events are counted on behalf of the application while it is running in the
  34 kernel, without otherwise disturbing the binding of events to the invoking LWP.
  35 If the \fIenable\fR argument is non-zero, counting of events is enabled,
  36 otherwise they are disabled.
  37 .SH RETURN VALUES
  38 .sp
  39 .LP
  40 Upon successful completion, \fBcpc_count_usr_events()\fR and
  41 \fBcpc_count_sys_events()\fR return \fB0\fR. Otherwise, the functions return
  42 \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
  43 .SH ERRORS
  44 .sp
  45 .LP
  46 The \fBcpc_count_usr_events()\fR and \fBcpc_count_sys_events()\fR functions
  47 will fail if:
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fBEAGAIN\fR \fR
  52 .ad
  53 .RS 11n
  54 The associated performance counter context has been invalidated by another
  55 process.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBEINVAL\fR \fR
  62 .ad
  63 .RS 11n
  64 No performance counter context has been created, or an attempt was made to
  65 enable system events while delivering counter overflow signals.
  66 .RE
  67
  68 .SH EXAMPLES
  69 .LP
  70 \fBExample 1 \fRUse \fBcpc_count_usr_events()\fR to minimize code needed by
  71 application.
  72 .sp
  73 .LP
  74 In this example, the routine \fBcpc_count_usr_events()\fR is used to minimize
  75 the amount of code that needs to be added to the application. The
  76 \fBcputrack\fR(1) command can be used in conjunction with these interfaces to
  77 provide event programming, sampling, and reporting facilities.
  78
  79 .sp
  80 .LP
  81 If the application is instrumented in this way and then started by
  82 \fBcputrack\fR with the \fBnouser\fR flag set in the event specification,
  83 counting of user events will only be enabled around the critical code section
  84 of interest.   If the program is run normally, no harm will ensue.
  85
  86 .sp
  87 .in +2
  88 .nf
  89 int have_counters = 0;
  90 int
  91 main(int argc, char *argv[])
  92 {
  93     if (cpc_version(CPC_VER_CURRENT) == CPC_VER_CURRENT &&
  94         cpc_getcpuver() != -1 && cpc_access() == 0)
  95         have_counters = 1;
  96
  97     /* ... other application code */
  98
  99     if (have_counters)
 100         (void) cpc_count_usr_events(1);
 101
 102     /* ==> Code to be measured goes here <== */
 103
 104     if (have_counters)
 105         (void) cpc_count_usr_events(0);
 106
 107     /* ... other application code */
 108 }
 109 .fi
 110 .in -2
 111
 112 .SH ATTRIBUTES
 113 .sp
 114 .LP
 115 See \fBattributes\fR(5) for descriptions of the following attributes:
 116 .sp
 117
 118 .sp
 119 .TS
 120 box;
 121 c | c
 122 l | l .
 123 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 124 _
 125 MT-Level        MT-Safe
 126 _
 127 Interface Stability     Obsolete
 128 .TE
 129
 130 .SH SEE ALSO
 131 .sp
 132 .LP
 133 \fBcputrack\fR(1), \fBcpc\fR(3CPC), \fBcpc_access\fR(3CPC),
 134 \fBcpc_bind_event\fR(3CPC), \fBcpc_enable\fR(3CPC), \fBcpc_getcpuver\fR(3CPC),
 135 \fBcpc_pctx_bind_event\fR(3CPC), \fBcpc_version\fR(3CPC), \fBlibcpc\fR(3LIB),
 136 \fBattributes\fR(5)
 137 .SH NOTES
 138 .sp
 139 .LP
 140 The \fBcpc_count_usr_events()\fR and \fBcpc_count_sys_events()\fR functions
 141 exist for binary compatibility only. Source containing these functions will not
 142 compile. These functions are obsolete and might be removed in a future release.
 143 Applications should use \fBcpc_enable\fR(3CPC) instead.