NAME

PAPI_query_event - query if PAPI event exists
PAPI_query_event_verbose - query details of a PAPI event
PAPI_query_all_events_verbose - acquire details of all PAPI events

CONTENTS

Synopsis
Description
Arguments
Return Values
Errors
Examples
Author
Bugs
See Also

C Interface

#include <papi.h> 

int PAPI_query_event(int EventCode); 

int PAPI_query_event_verbose(int EventCode, PAPI_preset_info_t *info); 

const PAPI_preset_info_t* PAPI_query_all_events_verbose(); 

Fortran Interface

#include fpapi.h 

PAPIF_query_event(C_INT EventCode, C_INT check) 

PAPIF_query_event_verbose(C_INT EventCode, C_STRING EventName,  
           C_STRING EventDescr,  C_STRING EventLabel,  C_INT  avail, 
           C_STRING EventNote,  C_INT  flags,  C_INT  check )

PAPI_query_event() asks the PAPI library if the PAPI Preset event can be counted on this architecture. If the event CAN be counted, the function returns PAPI_OK. If the event CANNOT be counted, the function returns an error code. On some platforms, this function also can be used to check the syntax of a native event.

PAPI_query_event_verbose() asks the PAPI library for a copy of an event descriptor. This descriptor can then be used to investigate the details about the event. In Fortran, the individual fields in the descriptor are returned as parameters.

PAPI_query_all_events_verbose() is implemented only in C. It asks the PAPI library to return a pointer to an array of event descriptors. The number of objects in the array is PAPI_MAX_PRESET_EVENTS and each object is a descriptor as returned by PAPI_query_event_verbose().

EventCode -- a defined event such as PAPI_TOT_INS.

EventName -- the event name as described in PAPI_presets (3) .

EventDescr -- a descriptive string for the event of length less than PAPI_MAX_STR_LEN.

EventLabel -- a short descriptive label for the event of length less than 18 characters.

avail -- zero if the event CANNOT be counted.

EventNote -- additional text information about an event if available.

flags -- provides additional information about an event, e.g., PAPI_DERIVED for an event derived from 2 or more other events.

On success, PAPI_query_event and PAPI_query_event_verbose return PAPI_OK , and on error, a non-zero error code is returned.

PAPI_query_all_events_verbose returns a pointer to an array of PAPI_preset_info_t structures on success, and a NULL pointer on error.

PAPI_EINVAL
	One or more of the arguments is invalid.
PAPI_ENOTPRESET
	The hardware event specified is not a valid PAPI preset.
PAPI_ENOEVNT
	The PAPI preset is not available on the underlying hardware.

int EventSet = PAPI_NULL;
unsigned int native = 0x0;
int retval,i;
PAPI_preset_info_t info;
PAPI_preset_info_t *infostructs;

/* Initialize the library */

retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT) {
  fprintf(stderr,"PAPI library init error!\n");
  exit(1); }
        
if (PAPI_query_event(PAPI_TOT_INS) != PAPI_OK) {
  fprintf(stderr,"No instruction counter? How lame.\n");
  exit(1);
  }
        
if (PAPI_query_event_verbose(PAPI_TOT_INS,&info) != PAPI_OK) {
  fprintf(stderr,"No instruction counter? How lame.\n");
  exit(1);
  }

if(info.avail)
  printf("This event is available on this hardware.\n");

if(info.flags & PAPI_DERIVED)
  printf("This event is a derived event on this hardware.\n");

retval=0;
infostructs=PAPI_query_all_events_verbose();
if(infostructs)
  for(i=0;i<PAPI_MAX_PRESET_EVENTS;i++)
    if(infostructs[i].avail)
      retval += 1;

Philip J. Mucci <mucci@cs.utk.edu>

These functions have no known bugs.

PAPI_preset (3), PAPI_set_opt (3), PAPI_start (3), PAPI_rem_event (3), PAPI_rem_events (3), PAPI_query (3), PAPI_cleanup_eventset (3), PAPI_destroy_eventset (3),
The PAPI Web Site: http://icl.cs.utk.edu/projects/papi