Manual Pages for UNIX Operating System command usage for man cpc_shared_close

CPU Performance Counters Library Functions  cpc_shared_open(3CPC)



NAME
     cpc_shared_open,                      cpc_shared_bind_event,
     cpc_shared_take_sample,  cpc_shared_rele, cpc_shared_close -
     use CPU performance counters on processors

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

     int cpc_shared_open(void);


     int cpc_shared_bind_event(int fd, cpc_event_t *event, int flags);


     int cpc_shared_take_sample(int fd, cpc_event_t *event);


     int cpc_shared_rele(int fd);


     void cpc_shared_close(int fd);


DESCRIPTION
     The cpc_shared_open() function allows the caller  to  access
     the  hardware counters in such a way that the performance of
     the currently  bound  CPU  can  be  measured.  The  function
     returns  a file descriptor if successful. Only one such open
     can be active at a time on any CPU.


     The cpc_shared_bind_event(),  cpc_shared_take_sample(),  and
     cpc_shared_rele()  functions  are  directly analogous to the
     corresponding   cpc_bind_event(),   cpc_take_sample(),   and
     cpc_rele()       functions       described       on      the
     cpc_bind_event(3CPC)manual page, except that they operate on
     the counters of a particular processor.

USAGE
     If a thread wishes to access the counters using this  inter-
     face, it must do so using a thread bound to an lwp, (see the
     THR_BOUND flag to thr_create(3C)), that has  in  turn  bound
     itself to a processor using processor_bind(2).


     Unlike the  cpc_bind_event(3CPC)  family  of  functions,  no
     counter  context  is  attached to those lwps, so the perfor-
     mance counter  samples  from  the  processors  reflects  the
     system-wide usage, instead of per-lwp usage.





SunOS 5.11          Last change: 28 Mar 2005                    1






CPU Performance Counters Library Functions  cpc_shared_open(3CPC)



     The first successful invocation  of  cpc_shared_open()  will
     immediately invalidate all existing performance counter con-
     text on the system, and prevent all subsequent  attempts  to
     bind counter context to lwps from succeeding anywhere on the
     system until the last caller invokes cpc_shared_close().


     This is because it is impossible to simultaneously  use  the
     counters  to  accurately  measure  per-lwp  and  system-wide
     events, so there is an  exclusive  interlock  between  these
     uses.


     Access to the shared counters is mediated  by  file  permis-
     sions  on  a  cpc  pseudo  device.   Only  a  user  with the
     {PRIV_SYS_CONFIG} privilege is allowed to access the  shared
     device.  This control prevents use of the counters on a per-
     lwp basis to other users.


     The  CPC_BIND_LWP_INHERIT  and  CPC_BIND_EMT_OVF  flags  are
     invalid for the shared interface.

RETURN VALUES
     On success, the functions  (except  for  cpc_shared_close())
     return 0.  On failure, the functions return -1 and set errno
     to indicate the reason.

ERRORS
     EACCES     The caller does not have appropriate privilege to
                access the CPU performance counters system-wide.


     EAGAIN     For cpc_shared_open(), this  value  implies  that
                the  counters  on  the bound cpu are busy because
                they are already being used  to  measure  system-
                wide events by some other caller.


     EAGAIN     Otherwise, this return  value  implies  that  the
                counters are not available because the thread has
                been unbound from the processor it was  bound  to
                at  open time. Robust programs should be coded to
                expect   this   behavior,   and   should   invoke
                cpc_shared_close(),  before  retrying  the opera-
                tion.


     EINVAL     The counters cannot be accessed  on  the  current
                CPU  because  the  calling thread is not bound to
                that CPU using processor_bind(2).




SunOS 5.11          Last change: 28 Mar 2005                    2






CPU Performance Counters Library Functions  cpc_shared_open(3CPC)



     ENOTSUP    The caller has attempted  an  operation  that  is
                illegal or not supported on the current platform.


     ENXIO      The current machine  either  has  no  performance
                counters,  or  has  been  configured  to disallow
                access to them system-wide.


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



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


SEE ALSO
     processor_bind(2),      cpc(3CPC),       cpc_bind_cpu(3CPC),
     cpc_bind_event(3CPC),                  cpc_set_sample(3CPC),
     cpc_unbind(3CPC),   libcpc(3LIB),   thr_create(3C),   attri-
     butes(5)

NOTES
     The       cpc_shared_open(),        cpc_shared_bind_event(),
     cpc_shared_take_sample(),       cpc_shared_rele(),       and
     cpc_shared_close() functions exist for binary  compatibility
     only.  Source  containing  these functions will not compile.
     These functions are obsolete  and  might  be  removed  in  a
     future  release. Applications should use cpc_bind_cpu(3CPC),
     cpc_set_sample(3CPC), and cpc_unbind(3CPC) instead.

















SunOS 5.11          Last change: 28 Mar 2005                    3