PAPI_set_event_info(3)

1PAPI_set_event_info(3)               PAPI               PAPI_set_event_info(3)
2
3
4

NAME

6       PAPI_set_event_info  -  set an event's name, description and definition
7       info
8
9

SYNOPSIS

11       C Interface
12       #include <papi.h>
13       int PAPI_set_event_info(PAPI_event_info_t *info, int *EventCode, int replace);
14
15

DESCRIPTION

17       NOTE: This API has been deprecated in PAPI 3.5 pending a data structure
18       redesign.
19
20       This  function modifies or adds an event to the PAPI preset event table
21       based on the  contents  of  an  even  info  structure.   This  function
22       presently works only to define or modify PAPI preset events.
23
24

ARGUMENTS

26       The  following  arguments are explicitly passed, or are implicit in the
27       info structure.
28
29       EventCode --  event code returned by the function on success
30
31       replace --  1 to replace an existing event, or 0 to prevent  accidental
32       replacement
33
34       info --  structure containing the event information. Relevant fields in
35       this structure are discussed below.
36
37       event_code --  although the value of this event code is not  used,  the
38       PAPI_PRESET_MASK  bit  must be set to indicate that the following event
39       description is for a preset event.
40
41       symbol --  name of the preset event. If the event name is found in  the
42       table  and  replace is non-zero, the event definition will be replaced.
43       If the names do not match a new entry will be created.
44
45       derived --  a string value indicating  whether  and  how  native  event
46       terms are combined to form a preset event.  Possible values include:
47
48          NOT_DERIVED: Do nothing; only one native event,
49          DERIVED_ADD: Add all native events,
50          DERIVED_CMPD:  Event  lives  in  first  counter  but takes 2 or more
51       native codes,
52          DERIVED_SUB: Subtract all events from the first event specified,
53          DERIVED_POSTFIX: Process events based on specified postfix string,
54
55
56       postfix --  a string value containing postfix operations used only  for
57       DERIVED_POSTFIX events.
58
59       short_descr --  short description of the event
60
61       long_descr --  detailed description of the event
62
63       event_note --  special information or notes about the event
64
65       name  --   an array of up to 8 names of native events that make up this
66       preset event.
67
68

RETURN VALUES

70       On success, the function returns PAPI_OK.  The EventCode parameter will
71       also be set to the new event code for this event.  On error, a non-zero
72       error code is returned by the function.
73
74

ERRORS

76       PAPI_EPERM
77              You are trying to modify an existing  event  without  specifying
78              replace.
79
80       PAPI_EISRUN
81              You  are  trying  to  modify  an event that has been added to an
82              EventSet.
83
84       PAPI_EINVAL
85              One or more of the arguments or fields of the info structure  is
86              invalid.
87
88       PAPI_ENOTPRESET
89              The  PAPI  preset  table  is full and there is no room for a new
90              event.
91
92       PAPI_ENOEVNT
93              The event specified is not a PAPI preset.  Usually  because  the
94              PAPI_PRESET_MASK bit is not set.
95
96

EXAMPLE

98       /*Add a note to a custom definition of PAPI_TOT_INS */
99       PAPI_event_name_to_code("PAPI_TOT_INS",&EventCode)
100       if (PAPI_get_event_info(EventCode, &info) != PAPI_OK)
101         handle_error(1);
102       strcpy(info.symbol, "MY_TOT_INS");
103       strcpy(info.note, "This note describes my version of total instructions.");
104       if (PAPI_set_event_info(&info, EventCode, 0) != PAPI_OK)
105         handle_error(1);
106
107

BUGS

109       This function has no known bugs.
110
111