cpc_shared_bind_event(3cpc)

1cpc_shared_open(3CPCCP)U Performance Counters Library Functiocnpsc_shared_open(3CPC)
2
3
4

NAME

6       cpc_shared_open,     cpc_shared_bind_event,     cpc_shared_take_sample,
7       cpc_shared_rele, cpc_shared_close - use  CPU  performance  counters  on
8       processors
9

SYNOPSIS

11       cc [ flag... ] file... −lcpc [ library... ]
12       #include <libcpc.h>
13
14       int cpc_shared_open(void);
15
16
17       int cpc_shared_bind_event(int fd, cpc_event_t *event, int flags);
18
19
20       int cpc_shared_take_sample(int fd, cpc_event_t *event);
21
22
23       int cpc_shared_rele(int fd);
24
25
26       void cpc_shared_close(int fd);
27
28

DESCRIPTION

30       The cpc_shared_open() function allows the caller to access the hardware
31       counters in such a way that the performance of the currently bound  CPU
32       can  be measured. The function returns a file descriptor if successful.
33       Only one such open can be active at a time on any CPU.
34
35
36       The     cpc_shared_bind_event(),     cpc_shared_take_sample(),      and
37       cpc_shared_rele() functions are directly analogous to the corresponding
38       cpc_bind_event(), cpc_take_sample(), and cpc_rele() functions described
39       on the cpc_bind_event(3CPC)manual page, except that they operate on the
40       counters of a particular processor.
41

USAGE

43       If a thread wishes to access the counters using this interface, it must
44       do  so  using  a  thread  bound  to  an lwp, (see the THR_BOUND flag to
45       thr_create(3C)), that has in turn bound itself  to  a  processor  using
46       processor_bind(2).
47
48
49       Unlike the cpc_bind_event(3CPC) family of functions, no counter context
50       is attached to those lwps, so the performance counter samples from  the
51       processors reflects the system-wide usage, instead of per-lwp usage.
52
53
54       The  first  successful invocation of cpc_shared_open() will immediately
55       invalidate all existing performance counter context on the system,  and
56       prevent  all  subsequent  attempts to bind counter context to lwps from
57       succeeding anywhere  on  the  system  until  the  last  caller  invokes
58       cpc_shared_close().
59
60
61       This  is because it is impossible to simultaneously use the counters to
62       accurately measure per-lwp and  system-wide  events,  so  there  is  an
63       exclusive interlock between these uses.
64
65
66       Access  to the shared counters is mediated by file permissions on a cpc
67       pseudo device.  Only a user with  the  {PRIV_SYS_CONFIG}  privilege  is
68       allowed  to  access the shared device. This control prevents use of the
69       counters on a per-lwp basis to other users.
70
71
72       The CPC_BIND_LWP_INHERIT and CPC_BIND_EMT_OVF flags are invalid for the
73       shared interface.
74

RETURN VALUES

76       On success, the functions (except for cpc_shared_close()) return 0.  On
77       failure, the functions return -1 and set errno to indicate the reason.
78

ERRORS

80       EACCES     The caller does not have appropriate privilege to access the
81                  CPU performance counters system-wide.
82
83
84       EAGAIN     For  cpc_shared_open(), this value implies that the counters
85                  on the bound cpu are busy because  they  are  already  being
86                  used to measure system-wide events by some other caller.
87
88
89       EAGAIN     Otherwise,  this  return value implies that the counters are
90                  not available because the thread has been unbound  from  the
91                  processor  it  was  bound  to  at open time. Robust programs
92                  should be coded to expect this behavior, and  should  invoke
93                  cpc_shared_close(), before retrying the operation.
94
95
96       EINVAL     The  counters  cannot be accessed on the current CPU because
97                  the calling thread is not bound to that  CPU  using  proces‐
98                  sor_bind(2).
99
100
101       ENOTSUP    The caller has attempted an operation that is illegal or not
102                  supported on the current platform.
103
104
105       ENXIO      The current machine either has no performance  counters,  or
106                  has been configured to disallow access to them system-wide.
107
108

ATTRIBUTES

110       See attributes(5) for descriptions of the following attributes:
111
112
113
114
115       ┌─────────────────────────────┬─────────────────────────────┐
116       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
117       ├─────────────────────────────┼─────────────────────────────┤
118       │MT-Level                     │MT-Safe                      │
119       ├─────────────────────────────┼─────────────────────────────┤
120       │Interface Stability          │Obsolete                     │
121       └─────────────────────────────┴─────────────────────────────┘
122

NOTES

129       The  cpc_shared_open(),  cpc_shared_bind_event(),  cpc_shared_take_sam‐
130       ple(), cpc_shared_rele(), and cpc_shared_close()  functions  exist  for
131       binary  compatibility  only. Source containing these functions will not
132       compile. These functions are obsolete and might be removed in a  future
133       release.   Applications  should  use  cpc_bind_cpu(3CPC),  cpc_set_sam‐
134       ple(3CPC), and cpc_unbind(3CPC) instead.
135
136
137
138SunOS 5.11                        28 Mar 2005            cpc_shared_open(3CPC)