cpc_walk_requests man page on SmartOS

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


       cpc_set_create, cpc_set_destroy, cpc_set_add_request, cpc_walk_requests
       - manage sets of counter requests

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

       cpc_set_t *cpc_set_create(cpc_t *cpc);

       int cpc_set_destroy(cpc_t *cpc, cpc_set_t *set);

       int cpc_set_add_request(cpc_t *cpc, cpc_set_t *set,
	    const char *event, uint64_t preset, uint_t flags,
	    uint_t nattrs, const cpc_attr_t *attrs);

       void cpc_walk_requests(cpc_t *cpc, cpc_set_t *set, void *arg,
	    void (*action)(void *arg, int index, const char *event,
	    uint64_t preset, uint_t flags, int nattrs,
	    const cpc_attr_t *attrs));

       The cpc_set_create() function returns an initialized and empty CPC set.
       A  CPC set contains some number of requests, where a request represents
       a specific configuration	 of  a	hardware  performance  instrumentation
       counter	present	 on  the  processor.  The  cpc_set_t data structure is
       opaque and must not be accessed directly by the application.

       Applications wanting to program one or more performance	counters  must
       create  an  empty set with cpc_set_create() and add requests to the set
       with cpc_set_add_request(). Once all requests have been added to a set,
       the  set	 must  be  bound  to  the  hardware  performance counters (see
       cpc_bind_curlwp(), cpc_bind_pctx(), and cpc_bind_cpu(),	all  described
       on  cpc_bind_curlwp(3CPC))  before  counting  events. At bind time, the
       system attempts to  match  each	request	 with  an  available  physical
       counter	capable of counting the event specified in the request. If the
       bind is successful, a 64-bit virtualized counter is  created  to	 store
       the counts accumulated by the hardware counter. These counts are stored
       and managed in CPC buffers separate from the CPC set whose requests are
       being counted. See cpc_buf_create(3CPC) and cpc_set_sample(3CPC).

       The cpc_set_add_request() function specifies a configuration of a hard‐
       ware counter.  The arguments to cpc_set_add_request() are:

			A string containing the name of an event supported  by
			the system's processor.	 The cpc_walk_events_all() and
			cpc_walk_events_pic()  functions  (both	 described  on
			cpc_npic(3CPC)) can be used to query the processor for
			the names  of  available  events.  Certain  processors
			allow  the  use	 of  raw  event codes, in which case a
			string representation of  an  event  code  in  a  form
			acceptable  to	strtol(3C)  can	 be  used as the event

			The  value  with  which	 the  system  initializes  the

			Three  flags  are  defined that modify the behavior of
			the counter acting on behalf of this request:


			    The counter should count events that  occur	 while
			    the processor is in user mode.


			    The	 counter  should count events that occur while
			    the processor is in privileged mode.


			    Request a signal to be  sent  to  the  application
			    when the physical counter overflows. A SIGEMT sig‐
			    nal is delivered if the processor  is  capable  of
			    delivering	an  interrupt  when the counter counts
			    past its maximum value. All requests  in  the  set
			    containing the counter that overflowed are stopped
			    until the set is rebound.

			At least one  of  CPC_COUNT_USER  or  CPC_COUNT_SYSTEM
			must  be  specified to program the hardware for count‐

       nattrs, attrs
			The nattrs argument specifies the number of attributes
			pointed to by the attrs argument, which is an array of
			cpc_attr_t  structures	containing  processor-specific
			attributes  that  modify  the request's configuration.
			The cpc_walk_attrs() function (see cpc_npic(3CPC)) can
			be  used  to  query  the  processor  for  the  list of
			attributes it accepts. The  library  makes  a  private
			copy  of  the attrs array, allowing the application to
			dispose	   of	 it    immediately    after    calling

       The  cpc_walk_requests()	 function  calls  the  action function on each
       request that has been added to the set.	The  arg  argument  is	passed
       unmodified to the action function with each call.

       Upon  successful	 completion,  cpc_set_create() returns a handle to the
       opaque cpc_set_t data structure. Otherwise, NULL is returned and	 errno
       is set to indicate the error.

       Upon  successful completion, Cpc_set_destroy() returns 0. Otherwise, -1
       is returned and errno is set to indicate the error.

       Upon successful completion, cpc_set_add_request()  returns  an  integer
       index  used  to refer to the data generated by that request during data
       retrieval. Otherwise, -1 is returned and errno is set to	 indicate  the

       These functions will fail if:

		 An  event, attribute, or flag passed to cpc_set_add_request()
		 was invalid.

		 For  cpc_set_destroy()	 and  cpc_set_add_request(),  the  set
		 parameter was not created with the given cpc_t.

		 There	was not enough memory available to the process to cre‐
		 ate the library's data structures.

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

       │Interface Stability │ Committed	      │
       │MT-Level	    │ Safe	      │

       cpc_bind_curlwp(3CPC), cpc_buf_create(3CPC), cpc_npic(3CPC), cpc_seter‐
       rhndlr(3CPC), libcpc(3LIB), strtol(3C), attributes(5)

       The  system  automatically determines which particular physical counter
       to use to count the events specified by each request. Applications  can
       force  the system to use a particular counter by specifying the counter
       number	in   an	  attribute   named   picnum   that   is   passed   to
       cpc_set_add_request().  Counters	 are numbered from 0 to n - 1, where n
       is  the	number	of  counters  in  the	processor   as	 returned   by

       Some processors, such as UltraSPARC, do not allow the hardware counters
       to be programmed differently. In this case, all	requests  in  the  set
       must  have  the	same configuration, or an attempt to bind the set will
       return EINVAL. If a cpc_errhndlr_t has been registered with  cpc_seter‐
       rhndlr(3CPC),  the  error  handler is called with subcode CPC_CONFLICT‐
       ING_REQS. For example, on UltraSPARC pic0 and pic1  must	 both  program
       events  in  the	same processor mode (user mode, kernel mode, or both).
       For example, pic0 cannot be programmed with CPC_COUNT_USER  while  pic1
       is  programmed  with CPC_COUNT_SYSTEM. Refer to the hardware documenta‐
       tion referenced by cpc_cpuref(3CPC) for details about a particular pro‐
       cessor's performance instrumentation hardware.

				 Aug 20, 2007		  CPC_SET_CREATE(3CPC)

List of man pages available for SmartOS

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]
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