cpc_buf_destroy man page on Solaris

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

cpc_buf_create(3CPCPU Performance Counters Library Functiocpc_buf_create(3CPC)

NAME
       cpc_buf_create,	   cpc_buf_destroy,    cpc_set_sample,	  cpc_buf_get,
       cpc_buf_set, cpc_buf_hrtime,  cpc_buf_tick,  cpc_buf_sub,  cpc_buf_add,
       cpc_buf_copy, cpc_buf_zero - sample and manipulate CPC data

SYNOPSIS
       cc [ flag... ] file... -lcpc [ library... ]
       #include <libcpc.h>

       cpc_buf_t *cpc_buf_create(cpc_t *cpc, cpc_set_t *set);

       int cpc_buf_destroy(cpc_t *cpc, cpc_buf_t *buf);

       int cpc_set_sample(cpc_t *cpc, cpc_set_t *set, cpc_buf_t *buf);

       int cpc_buf_get(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t *val);

       int cpc_buf_set(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t val);

       hrtime_t cpc_buf_hrtime(cpc_t *cpc, cpc_buf_t *buf);

       uint64_t cpc_buf_tick(cpc_t *cpc, cpc_buf_t *buf);

       void  cpc_buf_sub(cpc_t	*cpc,  cpc_buf_t  *ds, cpc_buf_t *a, cpc_buf_t
       *b);

       void cpc_buf_add(cpc_t *cpc, cpc_buf_t  *ds,  cpc_buf_t	*a,  cpc_buf_t
       *b);

       void cpc_buf_copy(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *src);

       void cpc_buf_zero(cpc_t *cpc, cpc_buf_t *buf);

DESCRIPTION
       Counter	data is sampled into CPC buffers, which are represented by the
       opaque data type cpc_buf_t. A CPC buffer is created  with  cpc_buf_cre‐
       ate()  to  hold	the data for a specific CPC set. Once a CPC buffer has
       been created, it can only be used to store and manipulate the  data  of
       the CPC set for which it was created.

       Once  a set has been successfully bound, the counter values are sampled
       using cpc_set_sample(). The cpc_set_sample() function takes a  snapshot
       of the hardware performance counters counting on behalf of the requests
       in set and stores the 64-bit virtualized	 software  representations  of
       the  counters  in  the  supplied	 CPC  buffer.  If a set was bound with
       cpc_bind_curlwp(3CPC) or cpc_bind_cpu(3CPC), the set can only  be  sam‐
       pled by the LWP that bound it.

       The  kernel  maintains  64-bit  virtual	software  counters to hold the
       counts accumulated for each request in the set, thereby allowing appli‐
       cations	to  count  past the limits of the underlying physical counter,
       which can be significantly smaller than 64 bits. The kernel attempts to
       maintain	 the  full  64-bit counter values even in the face of physical
       counter overflow on architectures and processors that can automatically
       detect overflow. If the processor is not capable of overflow detection,
       the caller must ensure that the counters are sampled  often  enough  to
       avoid the physical counters wrapping. The events most prone to wrap are
       those that count processor clock cycles. If such an event is of	inter‐
       est, sampling should occur frequently so that the counter does not wrap
       between samples.

       The cpc_buf_get() function retrieves the last sampled value of  a  par‐
       ticular	request	 in  buf.  The	index argument specifies which request
       value in the set to retrieve. The index for each	 request  is  returned
       during  set configuration by cpc_set_add_request(3CPC). The 64-bit vir‐
       tualized software counter value is stored in the location pointed to by
       the val argument.

       The  cpc_buf_set() function stores a 64-bit value to a specific request
       in the supplied buffer. This operation can  be  useful  for  performing
       calculations  with CPC buffers, but it does not affect the value of the
       hardware counter (and thus will not affect the next sample).

       The cpc_buf_hrtime() function returns a high-resolution timestamp indi‐
       cating exactly when the set was last sampled by the kernel.

       The  cpc_buf_tick() function returns a 64-bit virtualized cycle counter
       indicating how long the set has been programmed into the counter	 since
       it  was	bound.	The units of the values returned by cpc_buf_tick() are
       CPU clock cycles.

       The cpc_buf_sub()  function  calculates	the  difference	 between  each
       request	in  sets  a  and  b,  storing  the result in the corresponding
       request within set ds. More specifically, for  each  request  index  n,
       this  function  performs	 ds[n] = a[n] - b[n]. Similarly, cpc_buf_add()
       adds each request in sets a and b and stores the result in  the	corre‐
       sponding request within set ds.

       The cpc_buf_copy() function copies each value from buffer src into buf‐
       fer ds. Both buffers must have been created from the same cpc_set_t.

       The cpc_buf_zero() function sets each request's value in the buffer  to
       zero.

       The  cpc_buf_destroy() function frees all resources associated with the
       CPC buffer.

RETURN VALUES
       Upon successful completion, cpc_buf_create() returns a pointer to a CPC
       buffer  which can be used to hold data for the set argument. Otherwise,
       this function returns NULL and sets errno to indicate the error.

       Upon  successful	 completion,  cpc_set_sample(),	  cpc_buf_get(),   and
       cpc_buf_set()  return  0.  Otherwise,  they  return -1 and set errno to
       indicate the error.

ERRORS
       These functions will fail if:

       EINVAL	       For cpc_set_sample(), the set is	 not  bound,  the  set
		       and/or  CPC  buffer were not created with the given cpc
		       handle, or the CPC buffer was not created with the sup‐
		       plied set.

       EAGAIN	       When  using cpc_set_sample() to sample a CPU-bound set,
		       the LWP has been unbound from the processor it is  mea‐
		       suring.

       ENOMEM	       The  library  could  not allocate enough memory for its
		       internal data structures.

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

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Evolving			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       cpc_bind_curlwp(3CPC),	  cpc_set_add_request(3CPC),	 libcpc(3LIB),
       attributes(5)

NOTES
       Often the overhead of performing a system call can be too disruptive to
       the events being measured. Once a cpc_bind_curlwp(3CPC) call  has  been
       issued, it is possible to access directly the performance hardware reg‐
       isters from within the application. If the performance counter  context
       is active, the counters will count on behalf of the current LWP.

       Not  all	 processors  support  this type of access. On processors where
       direct access is not possible, cpc_set_sample() must be	used  to  read
       the counters.

       SPARC

	   rd %pic, %rN	       ! All UltraSPARC
	   wr %rN, %pic	       ! (All UltraSPARC, but see text)

       x86

	   rdpmc	       ! Pentium II, III, and 4 only

       If  the counter context is not active or has been invalidated, the %pic
       register (SPARC), and the rdpmc instruction (Pentium) becomes  unavail‐
       able.

       Pentium II and III processors support the non-privileged rdpmc instruc‐
       tion that requires that the counter of interest be  specified  in  %ecx
       and  return  a 40-bit value in the %edx:%eax register pair. There is no
       non-privileged access mechanism for Pentium I processors.

SunOS 5.10			  30 Jan 2004		  cpc_buf_create(3CPC)
[top]

List of man pages available for Solaris

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