PAPI_get_overflow_event_index(3)

1PAPI_get_overflow_event_index(3)     PAPI     PAPI_get_overflow_event_index(3)
2
3
4

NAME

6       PAPI_get_overflow_event_index  -  converts  an  overflow vector into an
7       array of indexes to overflowing events
8
9

SYNOPSIS

11       C Interface
12       #include <papi.h>
13       int PAPI_get_overflow_event_index(int EventSet, long_long overflow_vector, int *array, int *number);
14       Fortran Interface
15       Not implemented
16
17

DESCRIPTION

19       PAPI_get_overflow_event_index decomposes  an  overflow_vector  into  an
20       event  index  array in which the first element corresponds to the least
21       significant set bit in overflow_vector  and  so  on.   Based  on  over‐
22       flow_vector, the user can only tell which physical counters overflowed.
23       Using this function, the user can map overflowing counters to  specific
24       events  in  the event set. An array is used in this function to support
25       the possibility of multiple simultaneous overflow events.
26
27

ARGUMENTS

29       EventSet --  an integer handle to  a  PAPI  event  set  as  created  by
30       PAPI_create_eventset(3)
31
32       overflow_vector  --  a vector with bits set for each counter that over‐
33       flowed.  This vector is passed by the system to  the  overflow  handler
34       routine.
35
36       *array  --  an  array  of indexes for events in EventSet.  No more than
37       *number indexes will be stored into the array.
38
39       *number -- On input the variable determines the size of the array.
40        On output the variable contains the number of indexes in the array.
41
42       Note that if the given *array is too short to hold all the indexes cor‐
43       respond  to  the  set  bits in the overflow_vector the *number variable
44       will be set to the size of array.
45
46

RETURN VALUES

48       On success, this function returns PAPI_OK.
49        On error, a non-zero error code is returned.
50
51

ERRORS

53       PAPI_EINVAL
54              One or more of the arguments is invalid. This could occur if the
55              overflow_vector is empty (zero), if the array or number pointers
56              are NULL, if the value of number is less than  one,  or  if  the
57              EventSet is empty.
58
59       PAPI_ENOEVST
60              The EventSet specified does not exist.
61
62
63
64       EXAMPLES
65              Create a user defined overflow handler routine that prints diag‐
66              nostic information about the overflow:
67              void handler(int EventSet, void *address, long_long overflow_vector, void *context)
68              {
69                int Events[4], number, i;
70                int total = 0, retval;
71
72                 printf("Overflow #%d Handler(%d) Overflow at %p! vector=0x%llx0,
73                   total, EventSet, address, overflow_vector);
74                 total++;
75                 number = 4;
76                 retval = PAPI_get_overflow_event_index(EventSet,
77                               overflow_vector, Events, &number);
78                 if(retval == PAPI_OK)
79                   for(i=0; i<number; i++) printf("Event index[%d] = %d", i, Events[i]);
80              }
81
82

BUGS

84       This function may not return all overflowing events if used with  soft‐
85       ware-driven overflow of multiple derived events.
86
87