cpc_shared_take_sample man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

cpc_shared_open(3CCPU Performance Counters Library Functicpc_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 <libcpc.h>

       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 interface, 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 performance counter samples from  the
       processors reflects the system-wide usage, instead of per-lwp usage.

       The  first  successful invocation of cpc_shared_open() will immediately
       invalidate all existing performance counter context 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 permissions 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 operation.

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

       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 attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      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),
       attributes(5)

NOTES
       The  cpc_shared_open(),	cpc_shared_bind_event(),  cpc_shared_take_sam‐
       ple(), 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_sam‐
       ple(3CPC), and cpc_unbind(3CPC) instead.

SunOS 5.11			  28 Mar 2005		 cpc_shared_open(3CPC)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net