'\" te
.\" Copyright (c) 2004, 2000, Oracle and/or its affiliates. All rights reserved.
.TH cpc_open 3CPC "30 Jan 2004" "SunOS 5.11" "CPU Performance Counters Library Functions"
.SH NAME
cpc_open, cpc_close \- initialize the CPU Performance Counter library
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <libcpc.h>

\fBcpc_t *\fR\fBcpc_open\fR(\fBint\fR \fIvers\fR);
.fi

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

.SH DESCRIPTION
.sp
.LP
The \fBcpc_open()\fR function initializes \fBlibcpc\fR(3LIB) and returns an identifier that must be used as the \fIcpc\fR argument in subsequent \fBlibcpc\fR function calls. The \fBcpc_open()\fR function takes an interface version as an argument and returns \fINULL\fR if that version of the interface is incompatible with the \fBlibcpc\fR implementation present on the system. Usually, the argument has the value of \fBCPC_VER_CURRENT\fR bound to the application when it was compiled.
.sp
.LP
If \fBcpc_open()\fR function is called with  \fBCPC_VER_CURRENT\fR, and if  the system supports both the CPU performance counter (\fIcpc\fR) and the hardware sampling (\fISMPL\fR), \fBcpc_open()\fR function initializes both CPC and SMPL. The returned identifier can be used as the \fIcpc\fR argument in  subsequent  \fBlibcpc\fR function calls that require the SMPL functionality. If the system supports only CPC, \fBcpc_open()\fR function initializes only CPC. The returned identifier can be used as the \fIcpc\fR argument in subsequent \fBlibcpc\fR function calls that do not require the SMPL functionality.
.sp
.LP
If \fBcpc_open()\fR function is called with \fBCPC_VER_CPC_ONLY\fR, \fBcpc_open()\fRfunction initializes only CPC, whether the system supports SMPL in addition to CPC or not.
.sp
.LP
The following macros can be specified to \fBcpc_open()\fR as \fIvers\fR:
.sp
.ne 2
.mk
.na
\fB\fBCPC_VER_CURRENT\fR\fR
.ad
.RS 20n
.rt  
If the system supports SMPL in addition to CPC, \fBcpc_open()\fR initializes both CPC and SMPL. Otherwise, \fBcpc_open()\fR initializes only CPC.
.RE

.sp
.ne 2
.mk
.na
\fB\fBCPC_VER_CPC_ONLY\fR\fR
.ad
.RS 20n
.rt  
\fBcpc_open()\fR initializes only CPC whether the system support SMPL in addition to CPC or not.
.RE

.sp
.LP
The \fBcpc_close()\fR function releases all resources associated with the \fIcpc\fR argument. Any bound counters and hardware sampling utilized by the process are unbound. All entities of type \fBcpc_set_t\fR and \fBcpc_buf_t\fR are invalidated and destroyed.
.SH RETURN VALUES
.sp
.LP
If the version requested is supported by the implementation, \fBcpc_open()\fR returns a \fBcpc_t\fR handle for use in all subsequent \fBlibcpc\fR operations. If the implementation cannot support the version needed by the application, \fBcpc_open()\fR returns \fINULL\fR, indicating that the application at least needs to be recompiled to operate correctly on the new platform and might require further changes.
.sp
.LP
The \fBcpc_close()\fR function always returns 0.
.SH ERRORS
.sp
.LP
These functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
The version requested by the client is incompatible with the implementation.
.RE

.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
\fBlibcpc\fR(3LIB), \fBattributes\fR(5)