PAPI_overflow(3)

💖 PAPI_overflow(3) 💖

okay bestie, welcome to the PAPI manual page for PAPI_overflow(3). We're gonna set up an event set so it starts registering overflows, and no, we are not skipping a single flag. 🫶

✨ NAME ✨

PAPI_overflow — Set up an event set to begin registering overflows. 💅

✨ SYNOPSIS ✨

💫 Detailed Description 💫

PAPI_overflow() marks a specific EventCode in an EventSet to generate an overflow signal after every threshold events are counted. Like, literally every time the threshold hits, boom, overflow signal. ⭐

More than one event in an event set can be used to trigger overflows. In those cases, the user must call this function once for each overflowing event. One call per overflowing event, bestie — don't try to bundle. To turn off overflow on a specified event, call this function with a threshold value of 0. Zero means off, periodt. 💀

Overflows can be implemented in either software or hardware, but the scope is the entire event set. PAPI defaults to hardware overflow if it is available. 👑

In the case of software overflow, a periodic timer interrupt causes PAPI to compare the event counts against the threshold values and call the overflow handler if one or more events have exceeded their threshold. In the case of hardware overflow, the counters are typically set to the negative of the threshold value and count up to 0. This zero-crossing triggers a hardware interrupt that calls the overflow handler. Because of this counter interrupt, the counter values for overflowing counters may be very small or even negative numbers, and cannot be relied upon as accurate. In such cases the overflow handler can approximate the counts by supplying the threshold value whenever an overflow occurs. 🫶

_papi_overflow_handler() is a placeholder for a user-defined function to process overflow events. A pointer to this function is passed to the PAPI_overflow routine, where it is invoked whenever a software or hardware overflow occurs. This handler receives the EventSet of the overflowing event, the Program Counter address when the interrupt occurred, an overflow_vector that can be processed to determined which event(s) caused the overflow, and a pointer to the machine context, which can be used in a platform-specific manor to extract register information about what was happening when the overflow occurred. (Yes, “manor” is the original spelling — we keep the lore. 🧚)

C Interface:

#include <papi.h>
int PAPI_overflow (int EventSet, int EventCode, int threshold, int
flags, PAPI_overflow_handler_t handler );

(*PAPI_overflow_handler_t) _papi_overflow_handler (int EventSet,
void *address, long_long overflow_vector, void *context );

Fortran Interface: Not implemented 😭

🎀 Parameters 🎀

• EventSet — an integer handle to a PAPI event set as created by PAPI_create_eventset. Like your event set's VIP pass. 🎟️
• EventCode — the preset or native event code to be set for overflow detection. This event must have already been added to the EventSet. No sneaking in un-added events, bestie. 🙈
• threshold — the overflow threshold value for this EventCode. The magic number where overflow goes brrr. 🔥
• flags — bitmap that controls the overflow mode of operation. Set to PAPI_OVERFLOW_FORCE_SW to force software overflowing, even if hardware overflow support is available. If hardware overflow support is available on a given system, it will be the default mode of operation. There are situations where it is advantageous to use software overflow instead. Although software overflow is inherently less accurate, with more latency and processing overhead, it does allow for overflowing on derived events, and for the accurate recording of overflowing event counts. These two features are typically not available with hardware overflow. Only one type of overflow is allowed per event set, so setting one event to hardware overflow and another to forced software overflow will result in an error being returned. ⚠️
• handler — pointer to the user supplied handler function to call upon overflow. Your main character callback. 🌟
• address — the Program Counter address at the time of the overflow. 📍
• overflow_vector — a long long word containing flag bits to indicate which hardware counter(s) caused the overflow. 🧮
• *context — pointer to a machine specific structure that defines the register context at the time of overflow. This parameter is often unused and can be ignored in the user function. Very “you can leave it on read” energy. 💅

🌈 Return values 🌈

• PAPI_OK — On success, PAPI_overflow returns PAPI_OK. Slay. ✅
• PAPI_EINVAL — One or more of the arguments is invalid. Most likely a bad threshold value. 🚩
• PAPI_ENOMEM — Insufficient memory to complete the operation. 😭
• PAPI_ENOEVST — The EventSet specified does not exist. Ghosted. 👻
• PAPI_EISRUN — The EventSet is currently counting events. Busy, do not disturb. ⏳
• PAPI_ECNFLCT — The underlying counter hardware cannot count this event and other events in the EventSet simultaneously. Also can happen if you are trying to overflow both by hardware and by forced software at the same time. Conflict, no cap. 💥
• PAPI_ENOEVNT — The PAPI event is not available on the underlying hardware. Not in this house. 🚫

🌸 Example 🌸

// Define a simple overflow handler:
void handler(int EventSet, void *address, long_long overflow_vector, void *context)
{
   fprintf(stderr,\"Overflow at %p! bit=%#llx \\n\",
            address,overflow_vector);
}

// Call PAPI_overflow for an EventSet containing PAPI_TOT_INS,
// setting the threshold to 100000. Use the handler defined above.
retval = PAPI_overflow(EventSet, PAPI_TOT_INS, 100000, 0, handler);

🦋 See also 🦋

• PAPI_get_overflow_event_index — go read that one next, bestie. 🫶

👑 Author 👑

Generated automatically by Doxygen for PAPI from the source code. 🤖

---

okay that's the whole page!! Version 7.2.0.0, dated Wed Jun 25 2025 19:30:48, from the PAPI manual, and this page is PAPI_overflow(3). Mwah 💋✨