Manual Pages for UNIX Operating System command usage for man cpc_count_usr_events

CPU Performance Counters Library Functions
                                       cpc_count_usr_events(3CPC)



NAME
     cpc_count_usr_events, cpc_count_sys_events - enable and dis-
     able performance counters

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

     int cpc_count_usr_events(int enable);


     int cpc_count_sys_events(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  cpc_count_usr_events()  function can be used to
     control whether events are counted on behalf of the applica-
     tion  running in user mode, while cpc_count_sys_events() 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,   cpc_count_usr_events()   and
     cpc_count_sys_events()  return  0.  Otherwise, the functions
     return -1 and set errno to indicate the error.

ERRORS
     The cpc_count_usr_events() and cpc_count_sys_events()  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 cpc_count_usr_events() to minimize code needed
     by application.






SunOS 5.11          Last change: 28 Mar 2005                    1






CPU Performance Counters Library Functions
                                       cpc_count_usr_events(3CPC)



     In this example, the routine cpc_count_usr_events() 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 have_counters = 0;
       int
       main(int argc, char *argv[])
       {
           if (cpc_version(CPC_VER_CURRENT) == CPC_VER_CURRENT &&
               cpc_getcpuver() != -1 && cpc_access() == 0)
               have_counters = 1;

           /* ... other application code */

           if (have_counters)
               (void) cpc_count_usr_events(1);

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

           if (have_counters)
               (void) cpc_count_usr_events(0);

           /* ... other application code */
       }


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














SunOS 5.11          Last change: 28 Mar 2005                    2






CPU Performance Counters Library Functions
                                       cpc_count_usr_events(3CPC)



______________________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Obsolete                    |
    |_____________________________|_____________________________|


SEE ALSO
     cputrack(1),          cpc(3CPC),           cpc_access(3CPC),
     cpc_bind_event(3CPC), cpc_enable(3CPC), cpc_getcpuver(3CPC),
     cpc_pctx_bind_event(3CPC), cpc_version(3CPC),  libcpc(3LIB),
     attributes(5)

NOTES
     The cpc_count_usr_events() and cpc_count_sys_events()  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 cpc_enable(3CPC) instead.

































SunOS 5.11          Last change: 28 Mar 2005                    3






CPU Performance Counters Library Functions
                                       cpc_count_usr_events(3CPC)






















































SunOS 5.11          Last change: 28 Mar 2005                    4