'\" te
.\" Copyright (c) 2005, 2000, 2013, Oracle and/or its affiliates. All rights reserved.
.TH cpc_enable 3CPC "31 Jan 2005" "SunOS 5.11" "CPU Performance Counters Library Functions"
.SH NAME
cpc_enable, cpc_disable \- enable and disable performance counters and hardware sampling
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <libcpc.h>

\fBint\fR \fBcpc_enable\fR(\fBcpc_t *\fR\fIcpc\fR);
.fi

.LP
.nf
\fBint\fR \fBcpc_disable\fR(\fBcpc_t *\fR\fIcpc\fR);
.fi

.SH DESCRIPTION
.sp
.LP
In certain applications, it can be useful to explicitly enable and disable performance counters and hardware sampling at different times so that the performance of a critical algorithm can be examined. The \fBcpc_enable()\fR and \fBcpc_disable()\fR functions can be used to enable and disable the performance counters and hardware sampling without otherwise disturbing the invoking LWP's performance hardware configuration.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBcpc_enable()\fR and \fBcpc_disable()\fR return 0. Otherwise, they return -1 and set \fBerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
These functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
.rt  
The associated performance counter context has been invalidated by another process.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
No performance counter context has been created for the calling LWP.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUse cpc_enable and cpc_disable to minimize code needed by application.
.sp
.LP
In the following example, the \fBcpc_enable()\fR and \fBcpc_disable()\fR functions are used to minimize the amount of code that needs to be added to the application. The \fBcputrack\fR(1) command can be used in conjunction with these functions to provide event programming, sampling, and reporting facilities.

.sp
.LP
If the application is instrumented in this way and then started by \fBcputrack\fR with the \fBnouser\fR flag set in the event specification, counting of user events will only be enabled around the critical code section of interest. If the program is run normally, no harm will ensue.

.sp
.in +2
.nf
int
main(int argc, char *argv[])
{
   cpc_t *cpc = cpc_open(CPC_VER_CURRENT);
    /* ... application code ... */
 
   if (cpc != NULL)
           (void) cpc_enable(cpc);
 
    /* ==> Code to be measured goes here <== */
 
   if (cpc != NULL)
           (void) cpc_disable(cpc);
 
    /* ... other application code */
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBcputrack\fR(1), \fBcpc\fR(3CPC), \fBcpc_open\fR(3CPC), \fBlibcpc\fR(3LIB), \fBattributes\fR(5)