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

   1 '\" te
   2 .\" Copyright (c) 2004, 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_OPEN 3CPC "Jan 30, 2004"
   7 .SH NAME
   8 cpc_open, cpc_close \- initialize the CPU Performance Counter library
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ]
  13 #include <libcpc.h>
  14
  15 \fBcpc_t *\fR\fBcpc_open\fR(\fBint\fR \fIvers\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBcpc_close\fR(\fBcpc_t *\fR\fIcpc\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBcpc_open()\fR function initializes \fBlibcpc\fR(3LIB) and returns an
  27 identifier that must be used as the \fIcpc\fR argument in subsequent
  28 \fBlibcpc\fR function calls. The \fBcpc_open()\fR function takes an interface
  29 version as an argument and returns \fINULL\fR if that version of the interface
  30 is incompatible with the \fBlibcpc\fR implementation present on the system.
  31 Usually, the argument has the value of \fBCPC_VER_CURRENT\fR bound to the
  32 application when it was compiled.
  33 .sp
  34 .LP
  35 The \fBcpc_close()\fR function releases all resources associated with the
  36 \fIcpc\fR argument. Any bound counters utilized by the process are unbound. All
  37 entities of type \fBcpc_set_t\fR and \fBcpc_buf_t\fR are invalidated and
  38 destroyed.
  39 .SH RETURN VALUES
  40 .sp
  41 .LP
  42 If the version requested is supported by the implementation, \fBcpc_open()\fR
  43 returns a \fBcpc_t\fR handle for use in all subsequent \fBlibcpc\fR operations.
  44 If the implementation cannot support the version needed by the application,
  45 \fBcpc_open()\fR returns \fINULL\fR, indicating that the application at least
  46 needs to be recompiled to operate correctly on the new platform and might
  47 require further changes.
  48 .sp
  49 .LP
  50 The \fBcpc_close()\fR function always returns 0.
  51 .SH ERRORS
  52 .sp
  53 .LP
  54 These functions will fail if:
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fBEINVAL\fR\fR
  59 .ad
  60 .RS 10n
  61 The version requested by the client is incompatible with the implementation.
  62 .RE
  63
  64 .SH ATTRIBUTES
  65 .sp
  66 .LP
  67 See \fBattributes\fR(5) for descriptions of the following attributes:
  68 .sp
  69
  70 .sp
  71 .TS
  72 box;
  73 c | c
  74 l | l .
  75 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  76 _
  77 Interface Stability     Evolving
  78 _
  79 MT-Level        Safe
  80 .TE
  81
  82 .SH SEE ALSO
  83 .sp
  84 .LP
  85 \fBlibcpc\fR(3LIB), \fBattributes\fR(5)