Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

cpc_seterrhndlr(3cpc) [opensolaris man page]

cpc_seterrhndlr(3CPC)				    CPU Performance Counters Library Functions				     cpc_seterrhndlr(3CPC)

NAME
cpc_seterrhndlr - control libcpc error reporting SYNOPSIS
cc [ flag... ] file... -lcpc [ library... ] #include <libcpc.h> typedef void(cpc_errhndlr_t)(cpc_t *cpc, const char *fn, int subcode, const char *fmt, va_list ap); void cpc_seterrhndlr(cpc_t *cpc, cpc_errhndlr_t *errfn); DESCRIPTION
For the convenience of programmers instrumenting their code, several libcpc(3LIB) functions automatically emit to stderr error messages that attempt to provide a more detailed explanation of their error return values. While this can be useful for simple programs, some applications might wanat to report their errors differently, for example, to a window or to a log file. The cpc_seterrhndlr() function allows the caller to provide an alternate function for reporting errors. The type signature is shown in the SYNOPSIS. The fn argument is passed the library function name that detected the error, an integer subcode indicating the specific error condidtion that has occurred, and the format string fmt that contains a textual description of the integer subcode. The format string fmt and argument pointer ap can be passed directly to vsnprintf(3C) or similar varargs-based function for formatting. The integer subcodes are provided to allow programs to recognize error conditions while using libcpc. The fmt string is provided as a con- venience for easy printing. The error subcodes are: CPC_INVALID_EVENT A specified event is not supported by the processor. CPC_INVALID_PICNUM The counter number does not fall in the range of available counters. CPC_INVALID_ATTRIBUTE A specified attribute is not supported by the processor. CPC_ATTRIBUTE_OUT_OF_RANGE The value of an attribute is outside the range supported by the processor. CPC_RESOURCE_UNAVAIL A hardware resource necessary for completing an operation was unavailable. CPC_PIC_NOT_CAPABLE The requested counter cannot count an assigned event. CPC_REQ_INVALID_FLAGS One or more requests has invalid flags. CPC_CONFLICTING_REQS The requests in a set cannot be programmed onto the hardware at the same time. CPC_ATTR_REQUIRES_PRIVILEGE A request contains an attribute which requires the cpc_cpu privilege, which the process does not have. The default printing routine can be restored by calling the routine with an errfn argument of NULL. EXAMPLES
Example 1 Debugging example. The following example produces error messages only when debugging the program containing it, or when the cpc_bind_curlwp(), cpc_bind_cpu(), or cpc_bind_pctx() functions are reporting an error when binding a cpc_set_t. int debugging; void myapp_errfn(const char *fn, int subcode, const char *fmt, va_list ap) { if (strncmp(fn, "cpc_bind", 8) != 0 && !debugging) return; (void) fprintf(stderr, "myapp: cpc_%s(): ", fn); (void) vfprintf(stderr, fmt, ap); } 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), libcpc(3LIB), vsnprintf(3C), attributes(5) SunOS 5.11 30 Jan 2004 cpc_seterrhndlr(3CPC)

Check Out this Related Man Page

cpc_set_create(3CPC)				    CPU Performance Counters Library Functions				      cpc_set_create(3CPC)

NAME
cpc_set_create, cpc_set_destroy, cpc_set_add_request, cpc_walk_requests - manage sets of counter requests SYNOPSIS
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)); DESCRIPTION
The cpc_set_create() function returns an initialized and empty CPC set. A CPC set contains some number of requests, where a request repre- sents 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_sam- ple(3CPC). The cpc_set_add_request() function specifies a configuration of a hardware counter. The arguments to cpc_set_add_request() are: event 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. preset The value with which the system initializes the counter. flags Three flags are defined that modify the behavior of the counter acting on behalf of this request: CPC_COUNT_USER The counter should count events that occur while the processor is in user mode. CPC_COUNT_SYSTEM The counter should count events that occur while the processor is in privileged mode. CPC_OVF_NOTIFY_EMT Request a signal to be sent to the application when the physical counter overflows. A SIGEMT signal 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 counting. 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 cpc_set_add_request(). 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. RETURN VALUES
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 error. ERRORS
These functions will fail if: EINVAL 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. ENOMEM There was not enough memory available to the process to create the library's 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_buf_create(3CPC), cpc_npic(3CPC), cpc_seterrhndlr(3CPC), libcpc(3LIB), attributes(5) NOTES
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 cpc_npic(3CPC). 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_CONFLICTING_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 documentation referenced by cpc_cpuref(3CPC) for details about a particular pro- cessor's performance instrumentation hardware. SunOS 5.10 22 Jun 2004 cpc_set_create(3CPC)
Man Page