CPU Performance Counters Library Functions
                                       cpccountusrevents(3CPC)



NAME
     cpccountusrevents, cpccountsysevents - enable and dis-
     able performance counters

SYNOPSIS
     cc [ flag... ] file... -lcpc [ library... ]
     #include 

     int cpccountusrevents(int enable);


     int cpccountsysevents(int enable);


DESCRIPTION
     In certain applications, it  can  be  useful  to  explicitly
     enable  and  disable performance counters at different times
     so that the performance of a critical algorithm can be exam-
     ined.   The  cpccountusrevents()  function can be used to
     control whether events are counted on behalf of the applica-
     tion  running in user mode, while cpccountsysevents() can
     be used to control whether events are counted on  behalf  of
     the  application  while it is running in the kernel, without
     otherwise disturbing the binding of events to  the  invoking
     LWP.  If the enable argument is non-zero, counting of events
     is enabled, otherwise they are disabled.

RETURN VALUES
     Upon  successful  completion,   cpccountusrevents()   and
     cpccountsysevents()  return  0.  Otherwise, the functions
     return -1 and set errno to indicate the error.

ERORS
     The cpccountusrevents() and cpccountsysevents()  func-
     tions will fail if:

     EAGAIN     The associated performance  counter  context  has
                been invalidated by another process.


     EINVAL     No performance counter context has been  created,
                or  an  attempt  was made to enable system events
                while delivering counter overflow signals.


EXAMPLES
     Example 1 Use cpccountusrevents() to minimize code needed
     by application.






SunOS 5.11          Last change: 28 Mar 2005                    1






CPU Performance Counters Library Functions
                                       cpccountusrevents(3CPC)



     In this example, the routine cpccountusrevents() is  used
     to minimize the amount of code that needs to be added to the
     application. The  cputrack(1) command can be  used  in  con-
     junction with these interfaces to provide event programming,
     sampling, and reporting facilities.



     If the application is instrumented  in  this  way  and  then
     started  by  cputrack  with the nouser flag set in the event
     specification, counting of user events will only be  enabled
     around  the critical code section of interest.   If the pro-
     gram is run normally, no harm will ensue.


       int havecounters = 0;
       int
       main(int argc, char *argv[])
       {
           if (cpcversion(CPCVERCURENT) == CPCVERCURENT &&
               cpcgetcpuver() != -1 && cpcaccess() == 0)
               havecounters = 1;

           /* ... other application code */

           if (havecounters)
               (void) cpccountusrevents(1);

           /* ==> Code to be measured goes here <== */

           if (havecounters)
               (void) cpccountusrevents(0);

           /* ... other application code */
       }


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:














SunOS 5.11          Last change: 28 Mar 2005                    2






CPU Performance Counters Library Functions
                                       cpccountusrevents(3CPC)




           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     MT-Safe                     
    
     Interface Stability          Obsolete                    
    


SEE ALSO
     cputrack(1),          cpc(3CPC),           cpcaccess(3CPC),
     cpcbindevent(3CPC), cpcenable(3CPC), cpcgetcpuver(3CPC),
     cpcpctxbindevent(3CPC), cpcversion(3CPC),  libcpc(3LIB),
     attributes(5)

NOTES
     The cpccountusrevents() and cpccountsysevents()  func-
     tions exist for binary compatibility only. Source containing
     these  functions  will  not  compile.  These  functions  are
     obsolete  and might be removed in a future release. Applica-
     tions should use cpcenable(3CPC) instead.

































SunOS 5.11          Last change: 28 Mar 2005                    3






CPU Performance Counters Library Functions
                                       cpccountusrevents(3CPC)






















































SunOS 5.11          Last change: 28 Mar 2005                    4