CPU Performance Counters Library Functions  cpcsharedopen(3CPC)



NAME
     cpcsharedopen,                      cpcsharedbindevent,
     cpcsharedtakesample,  cpcsharedrele, cpcsharedclose -
     use CPU performance counters on processors

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

     int cpcsharedopen(void);


     int cpcsharedbindevent(int fd, cpceventt *event, int flags);


     int cpcsharedtakesample(int fd, cpceventt *event);


     int cpcsharedrele(int fd);


     void cpcsharedclose(int fd);


DESCRIPTION
     The cpcsharedopen() 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 cpcsharedbindevent(),  cpcsharedtakesample(),  and
     cpcsharedrele()  functions  are  directly analogous to the
     corresponding   cpcbindevent(),   cpctakesample(),   and
     cpcrele()       functions       described       on      the
     cpcbindevent(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
     THRBOUND flag to thrcreate(3C)), that has  in  turn  bound
     itself to a processor using processorbind(2).


     Unlike the  cpcbindevent(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  cpcsharedopen(3CPC)



     The first successful invocation  of  cpcsharedopen()  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 cpcsharedclose().


     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
     {PRIVSYSCONFIG} privilege is allowed to access the  shared
     device.  This control prevents use of the counters on a per-
     lwp basis to other users.


     The  CPCBINDLWPINHERIT  and  CPCBINDEMTOVF  flags  are
     invalid for the shared interface.

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

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


     EAGAIN     For cpcsharedopen(), 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
                cpcsharedclose(),  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 processorbind(2).




SunOS 5.11          Last change: 28 Mar 2005                    2






CPU Performance Counters Library Functions  cpcsharedopen(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.


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



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


SEE ALSO
     processorbind(2),      cpc(3CPC),       cpcbindcpu(3CPC),
     cpcbindevent(3CPC),                  cpcsetsample(3CPC),
     cpcunbind(3CPC),   libcpc(3LIB),   thrcreate(3C),   attri-
     butes(5)

NOTES
     The       cpcsharedopen(),        cpcsharedbindevent(),
     cpcsharedtakesample(),       cpcsharedrele(),       and
     cpcsharedclose() 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 cpcbindcpu(3CPC),
     cpcsetsample(3CPC), and cpcunbind(3CPC) instead.

















SunOS 5.11          Last change: 28 Mar 2005                    3