cpc_seterrhndlr(3cpc)

1cpc_seterrhndlr(3CPCCP)U Performance Counters Library Functiocnpsc_seterrhndlr(3CPC)
2
3
4

NAME

6       cpc_seterrhndlr - control libcpc error reporting
7

SYNOPSIS

9       cc [ flag... ] file... -lcpc [ library... ]
10       #include <libcpc.h>
11
12       typedef void(cpc_errhndlr_t)(cpc_t *cpc, const char *fn, int subcode,
13            const char *fmt, va_list ap);
14
15
16       void cpc_seterrhndlr(cpc_t *cpc, cpc_errhndlr_t *errfn);
17
18

DESCRIPTION

20       For  the  convenience  of programmers instrumenting their code, several
21       libcpc(3LIB) functions automatically emit to stderr error messages that
22       attempt  to  provide  a more detailed explanation of their error return
23       values.  While this can be useful for simple  programs,  some  applica‐
24       tions might wanat to report their errors differently, for example, to a
25       window or to a log file.
26
27
28       The cpc_seterrhndlr() function allows the caller to provide  an  alter‐
29       nate  function for reporting errors. The type signature is shown in the
30       SYNOPSIS. The fn argument is passed  the  library  function  name  that
31       detected  the  error,  an integer subcode indicating the specific error
32       condidtion that has occurred, and the format string fmt that contains a
33       textual  description  of the integer subcode. The format string fmt and
34       argument pointer ap can be passed directly to vsnprintf(3C) or  similar
35       varargs-based function for formatting.
36
37
38       The  integer subcodes are provided to allow programs to recognize error
39       conditions while using libcpc. The fmt string is provided as  a  conve‐
40       nience for easy printing. The error subcodes are:
41
42       CPC_INVALID_EVENT
43
44           A specified event is not supported by the processor.
45
46
47       CPC_INVALID_PICNUM
48
49           The  counter  number  does not fall in the range of available coun‐
50           ters.
51
52
53       CPC_INVALID_ATTRIBUTE
54
55           A specified attribute is not supported by the processor.
56
57
58       CPC_ATTRIBUTE_OUT_OF_RANGE
59
60           The value of an attribute is outside the  range  supported  by  the
61           processor.
62
63
64       CPC_RESOURCE_UNAVAIL
65
66           A  hardware  resource  necessary  for  completing  an operation was
67           unavailable.
68
69
70       CPC_PIC_NOT_CAPABLE
71
72           The requested counter cannot count an assigned event.
73
74
75       CPC_REQ_INVALID_FLAGS
76
77           One or more requests has invalid flags.
78
79
80       CPC_CONFLICTING_REQS
81
82           The requests in a set cannot be programmed onto the hardware at the
83           same time.
84
85
86       CPC_ATTR_REQUIRES_PRIVILEGE
87
88           A  request  contains an attribute which requires the cpc_cpu privi‐
89           lege, which the process does not have.
90
91
92
93       The default printing routine can be restored by  calling   the  routine
94       with an errfn argument of NULL.
95

EXAMPLES

97       Example 1 Debugging example.
98
99
100       The  following  example produces error messages only when debugging the
101       program containing it, or when the  cpc_bind_curlwp(),  cpc_bind_cpu(),
102       or  cpc_bind_pctx()  functions  are  reporting  an error when binding a
103       cpc_set_t.
104
105
106         int debugging;
107         void
108         myapp_errfn(const char *fn, int subcode, const char *fmt, va_list ap)
109         {
110                 if (strncmp(fn, "cpc_bind", 8) != 0 && !debugging)
111                     return;
112                 (void) fprintf(stderr, "myapp: cpc_%s(): ", fn);
113                 (void) vfprintf(stderr, fmt, ap);
114         }
115
116

ATTRIBUTES

118       See attributes(5) for descriptions of the following attributes:
119
120
121
122
123       ┌─────────────────────────────┬─────────────────────────────┐
124       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
125       ├─────────────────────────────┼─────────────────────────────┤
126       │Interface Stability          │Evolving                     │
127       ├─────────────────────────────┼─────────────────────────────┤
128       │MT-Level                     │Safe                         │
129       └─────────────────────────────┴─────────────────────────────┘
130

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

ATTRIBUTES

SEE ALSO