PAPI_add_event(3)

1PAPI_add_event(3)                    PAPI                    PAPI_add_event(3)
2
3
4

NAME

6        PAPI_add_event  - add PAPI preset or native hardware event to an event
7       set
8        PAPI_add_events - add PAPI presets or native  hardware  events  to  an
9       event set
10
11

SYNOPSIS

13       C Interface
14       #include <papi.h>
15       int PAPI_add_event(int EventSet, int EventCode);
16       int PAPI_add_events(int EventSet, int *EventCodes, int number);
17       Fortran Interface
18       #include fpapi.h
19       PAPIF_add_event(C_INT EventSet, C_INT EventCode, C_INT check)
20       PAPIF_add_events(C_INT EventSet, C_INT(*) EventCodes, C_INT number, C_INT check)
21
22

DESCRIPTION

24       PAPI_add_event()  adds one event to a PAPI Event Set.
25       PAPI_add_events() does the same, but for an array of events.
26
27       A hardware event can be either a PAPI preset or a native hardware event
28       code.  For a list of PAPI preset events, see PAPI_presets(3) or run the
29       avail test case in the PAPI distribution. PAPI presets can be passed to
30       PAPI_query_event(3) to see if they exist on  the  underlying  architec‐
31       ture.   For  a list of native events available on current platform, run
32       native_avail test case in the PAPI distribution. For  the  encoding  of
33       native  events, see PAPI_event_name_to_code(3) to learn how to generate
34       native code for the supported native event on the underlying  architec‐
35       ture.
36
37

ARGUMENTS

39       EventSet  --   an  integer  handle  for  a PAPI Event Set as created by
40       PAPI_create_eventset(3)
41
42       EventCode -- a defined event such as PAPI_TOT_INS.
43
44       *EventCode -- an array of defined events
45
46       number -- an integer indicating the  number  of  events  in  the  array
47       *EventCode
48
49       It  should be noted that PAPI_add_events can partially succeed, exactly
50       like PAPI_remove_events.
51
52

RETURN VALUES

54       On success, these functions return PAPI_OK.
55        On error, a less than zero error code is returned or the the number of
56       elements that succeeded before the error.
57
58

ERRORS

60       Positive integer
61              The  number  of  consecutive  elements that succeeded before the
62              error.
63
64       PAPI_EINVAL
65              One or more of the arguments is invalid.
66
67       PAPI_ENOMEM
68              Insufficient memory to complete the operation.
69
70       PAPI_ENOEVST
71              The event set specified does not exist.
72
73       PAPI_EISRUN
74              The event set is currently counting events.
75
76       PAPI_ECNFLCT
77              The underlying counter hardware can not  count  this  event  and
78              other events in the event set simultaneously.
79
80       PAPI_ENOEVNT
81              The PAPI preset is not available on the underlying hardware.
82
83       PAPI_EBUG
84              Internal error, please send mail to the developers.
85
86

EXAMPLES

88       int EventSet = PAPI_NULL;
89       unsigned int native = 0x0;
90
91       if (PAPI_create_eventset(&EventSet) != PAPI_OK)
92         handle_error(1);
93
94       /* Add Total Instructions Executed to our EventSet */
95
96       if (PAPI_add_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
97         handle_error(1);
98
99       /* Add native event PM_CYC to EventSet */
100
101       if (PAPI_event_name_to_code("PM_CYC",&native) != PAPI_OK)
102         handle_error(1);
103
104       if (PAPI_add_event(EventSet, native) != PAPI_OK)
105         handle_error(1);
106
107
108

BUGS

110       The  vector  function  should  take a pointer to a length argument so a
111       proper return value can be set upon partial success.
112
113