Wiki
Clone wikipapi / PAPI-Error-Handling
PAPI Error Handling
This section discusses the various negative error codes that are returned by the PAPI functions. A table with the names, values, and descriptions of the return codes are given as well as a discussion of the PAPI function that can be used to convert error codes to error messages along with a code example with the corresponding output.
Error Codes
All of the functions contained in the PAPI library return standardized error codes in which the values that are greater than or equal to zero indicate success and those that are less than zero indicate failure, as shown in the table below:
VALUE | SYMBOL | DEFINITION |
---|---|---|
0 | PAPI_OK | No error |
-1 | PAPI_EINVAL | Invalid argument |
-2 | PAPI_ENOMEM | Insufficient memory |
-3 | PAPI_ESYS | A system or C library call failed, please check errno |
-4 | PAPI_ECMP | Not supported by component |
-4 | PAPI_ESBSTR | Substrate returned an error, usually the result of an unimplemented feature |
-5 | PAPI_ECLOST | Access to the counters was lost or interrupted |
-6 | PAPI_EBUG | Internal error, please send mail to the developers |
-7 | PAPI_ENOEVNT | Hardware event does not exist |
-8 | PAPI_ECNFLCT | Hardware event exists, but cannot be counted due to counter resource limitations |
-9 | PAPI_ENOTRUN | No events or event sets are currently not counting |
-10 | PAPI_EISRUN | Event Set is currently running |
-11 | PAPI_ENOEVST | No such event set available |
-12 | PAPI_ENOTPRESET | Event is not a valid preset |
-13 | PAPI_ENOCNTR | Hardware does not support performance counters |
-14 | PAPI_EMISC | ‘Unknown error’ code |
-15 | PAPI_EPERM | You lack the necessary permissions |
-16 | PAPI_ENOINIT | PAPI hasn't been initialized yet |
-17 | PAPI_ENOCMP | Component Index isn't set |
-18 | PAPI_ENOSUPP | Not supported |
-19 | PAPI_ENOIMPL | Not implemented |
-20 | PAPI_EBUF | Buffer size exceeded |
-21 | PAPI_EINVAL_DOM | EventSet domain is not supported for the operation |
-22 | PAPI_EATTR | Invalid or missing event attributes |
-23 | PAPI_ECOUNT | Too many events or attributes |
-24 | PAPI_ECOMBO | Bad combination of features |
-25 | PAPI_ECMP_DISABLED | Component containing event is disabled |
-26 | PAPI_EDELAY_INIT | Delayed initialisation component |
-27 | PAPI_EMULPASS | Event exists, but cannot be counted due to multiple passes required by hardware |
Converting Error Codes to Error Messages
Error codes can be converted to error messages by calling the following low-level functions:
C:
PAPI_perror(code, destination, length)
PAPI_strerror(code)
Fortan:
PAPIF_perror(code, destination, check)
Arguments
- code -- the error code to interpret
- *destination -- NULL or the error message string
- length -- NULL or strlen(destination)
PAPI_perror fills the string, destination, with the error message corresponding to the error code (code). The function copies length worth of the error description string corresponding to code into destination. The resulting string is always null terminated. If either destination or length is 0, then the string is printed to stderr.
PAPI_strerror returns a pointer to the error message corresponding to the error code (code). If the call fails, the function returns a NULL pointer. Otherwise, a non-NULL pointer is returned. Note that this function is not implemented in Fortran.
Example
In the following code example, PAPI_perror is used to convert error codes to error messages:
#include <papi.h>
#include <stdio.h>
main()
{
int EventSet = PAPI_NULL;
int event = 0x0;
char error_str[PAPI_MAX_STR_LEN];
/* Initialize the PAPI library */
retval = PAPI_library_init(PAPI_VER_CURRENT);
if (retval != PAPI_VER_CURRENT && retval > 0) {
fprintf(stderr,"PAPI library version mismatch!\n");
exit(1);
}
if ((retval = PAPI_create_eventset(&EventSet)) != PAPI_OK) {
fprintf(stderr, "PAPI error %d: %s\n",retval,PAPI_strerror(retval));
exit(1);
}
/* Add Total Instructions Executed to our EventSet */
if ((retval = PAPI_add_event(&EventSet, PAPI_TOT_INS)) != PAPI_OK) {
PAPI_perror(retval,error_str,PAPI_MAX_STR_LEN);
fprintf(stderr,"PAPI_error %d: %s\n",retval,error_str);
exit(1);
}
/* Add illegal PRESET event */
retval = PAPI_event_name_to_code("PAPI_L4_DCM", &event);
if ((retval = PAPI_add_event(&EventSet, event)) != PAPI_OK) {
/* Dump error string directly to stderr. */
PAPI_perror(retval,NULL,NULL);
exit(1);
}
/* Start counting */
if ((retval = PAPI_start(EventSet)) != PAPI_OK)
handle_error(retval);
}
Output
Invalid argument
Notice that the above output was generated from the last call to PAPI_perror.
On success, PAPI_perror returns PAPI_OK and on error, a non-zero error code is returned.
Handling Errors
Throughout this Overview, the code snippets often reference a routine called handle_error. Feel free to implement this routine in whatever way makes sense for your circumstances. One possible implementation, based on the routines discussed above, is shown below.
void handle_error (int retval)
{
/* print error to stderr and exit */
PAPI_perror(retval,NULL,NULL);
exit(1);
}
Updated