- Main Page
- Modules
- Classes

- Search for |

# Pin Error Reporting Support

## Enumerations

enum | PIN_ERR_SEVERITY_TYPE { PIN_ERR_FATAL, PIN_ERR_NONFATAL }
enum | PIN_ERRTYPE { PIN_ERR_NONE = 0, PIN_ERR_INTERNAL, PIN_ERR_ASSERT, PIN_ERR_TOOL,
PIN_ERR_CMD_LINE,
PIN_ERR_PARSING,
PIN_ERR_NO_APP,
PIN_ERR_INVALID_PLOAD,
PIN_ERR_FILE_NOT_FOUND,
PIN_ERR_ELF_HEADER,
PIN_ERR_NO_PIE,
PIN_ERR_NO_ENTRY_OFFSET,
PIN_ERR_INVALID_ADDRESS,
PIN_ERR_INVALID_ADDRESS_RANGE,
PIN_ERR_CANNOT_LOAD_TOOL,
PIN_ERR_PIN_INJECTION,
PIN_ERR_WAIT_FOR_INJECTOR,
PIN_ERR_BAD_OS_FILE,
PIN_ERR_UNSUPPORTED_OS,
PIN_ERR_BIN32,
PIN_ERR_BIN64,
PIN_ERR_CANNOT_RUN,
PIN_ERR_ATTACH_PID,
PIN_ERR_ATTACH_NYI,
PIN_ERR_ATTACH_REJECTED,
PIN_ERR_ATTACH_PTRACE_SCOPE_1,
PIN_ERR_DETACH_PID,
PIN_ERR_WAIT_PID,
PIN_ERR_STEP_PID,
PIN_ERR_WAIT_EXECV,
PIN_ERR_APP_RESUME,
PIN_ERR_NO_INSTRUMENT,
PIN_ERR_CHILD_PTRACEME,
PIN_ERR_CHILD_RESUME,
PIN_ERR_RELINK_APP,
PIN_ERR_KNOB_BAD,
PIN_ERR_NO_RELOCS,
PIN_ERR_VERSION_SKEW,
PIN_ERR_MS_DOS,
PIN_ERR_LONG_PATH,
PIN_ERR_CANNOT_EXECUTE_FILE,
PIN_ERR_BLOCKSIG_TOOL,
PIN_ERR_BLOCKSIG_APP,
PIN_ERR_USER_SPECIFIED_ERROR,
PIN_ERR_OUT_OF_MEMORY,
PIN_ERR_NON_NUMERIC_STRING,
PIN_ERR_EMPTY_STRING,
PIN_ERR_NUMERIC_FROM_STRING,
PIN_ERR_ALREADY_ATTACHED,
PIN_ERR_ILLEGAL_EXCEPTION,
PIN_ERR_EXCEPTION_NEEDS_ADDR,
PIN_ERR_PREDEFINED_INSTRUMENTATION_FAILED,
PIN_ERR_UNSUPPORTED_SYSCALL,
PIN_ERR_ACCESS_DENIED,
PIN_ERR_INVALID_SUSPEND_REQUEST,
PIN_ERR_DEBUGGER,
PIN_ERR_LAST
}

## Functions

VOID | LEVEL_PINCLIENT::PIN_WriteErrorMessage (const char *msg, INT32 type, PIN_ERR_SEVERITY_TYPE severity, INT32 num,...)

## Detailed Description

Pin errors are normally printed to the screen. Some tools prefer to take the Pin errors and create their own error message. This is important if your tool has a particular look and feel. Pin provides the -error_file option, which generates a machine-parsable error code, and supresses error being emitted to the screen.

The PIN_ERRTYPEs are the errors that Pin can report. The PIN_ERRTYPEs are defined in $PIN_HOME/source/include/pin-errtype.h.

## Enumeration Type Documentation

enum PIN_ERR_SEVERITY_TYPE

| Severity used by PIN_WriteErrorMessage()

Enumerator:

  PIN_ERR_FATAL | fatal error, Pin exits after printing message.
  PIN_ERR_NONFATAL | non-fatal error

enum PIN_ERRTYPE

| Client level errors reported by Pin.

Enumerator:

  PIN_ERR_NONE | 0 args. no error.
  PIN_ERR_INTERNAL | 0 args. internal pin error has occurred.
  PIN_ERR_ASSERT | 0 args. internal pin assertion has occurred.
  PIN_ERR_TOOL | 0 args. tool error has been detected.
  PIN_ERR_CMD_LINE | 0 args. tool arguments are incorrect.
  PIN_ERR_PARSING | 0 args. command line arguments are incorrect.
  PIN_ERR_NO_APP | 0 args. missing application name.
  PIN_ERR_INVALID_PLOAD | 0 args. invalid pload argument.
  PIN_ERR_FILE_NOT_FOUND | 1 arg: file name. error in application file name or path.
  PIN_ERR_ELF_HEADER | 1 arg: file name. unable to read elf header of "filename".
  PIN_ERR_NO_PIE | 1 arg: file name. pie binaries not supported on this system.
  PIN_ERR_NO_ENTRY_OFFSET | 1 arg: file name. no entry in aux vector.
  PIN_ERR_INVALID_ADDRESS | 1 arg: address. "address" is invalid.
  PIN_ERR_INVALID_ADDRESS_RANGE | 2 args: low address, high address. address range is invalid.
  PIN_ERR_CANNOT_LOAD_TOOL | 1 arg: tool name. pin cannot load "tool".
  PIN_ERR_PIN_INJECTION | 0 arg: can't inject pin in running process.
  PIN_ERR_WAIT_FOR_INJECTOR | 2 args: pid, errno. injector "pid" failed to exit.
  PIN_ERR_BAD_OS_FILE | 0 args. cannot determine os release.
  PIN_ERR_UNSUPPORTED_OS | 0 args. unsupported os.
  PIN_ERR_BIN32 | 0 args. 32-bit binary detected.
  PIN_ERR_BIN64 | 0 args. 64-bit binary detected.
  PIN_ERR_CANNOT_RUN | 1 arg: errno. error in running pin.
  PIN_ERR_ATTACH_PID | 2 arg: pid, errno. attach to "pid" failed.
  PIN_ERR_ATTACH_NYI | 0 arg: attach to running process is NYI for Pin/Windows in JIT mode.
  PIN_ERR_ATTACH_REJECTED | 0 arg: ptrace attach rejected.
  PIN_ERR_ATTACH_PTRACE_SCOPE_1 | 1 arg: pid, ptrace attach rejected due to sysctl kernel.yama.ptrace_scope.
  PIN_ERR_DETACH_PID | 2 arg: pid, errno. detach failed.
  PIN_ERR_WAIT_PID | 2 arg: pid, errno. wait for child failed.
  PIN_ERR_STEP_PID | 2 arg: pid, errno. single step failed.
  PIN_ERR_WAIT_EXECV | 1 arg: errno. wait after execv failed.
  PIN_ERR_APP_RESUME | 1 arg: errno. resuming application failed.
  PIN_ERR_NO_INSTRUMENT | 2 args: file name, errno. could not instrument process.
  PIN_ERR_CHILD_PTRACEME | 1 arg: errno. parent cannot trace the child.
  PIN_ERR_CHILD_RESUME | 1 arg: errno. resuming child failed.
  PIN_ERR_RELINK_APP | 0 args: application address overlaps with pin, relink.
  PIN_ERR_KNOB_BAD | 1 arg: knob. unknown "knob" on command line.
  PIN_ERR_NO_RELOCS | 0 args. regular relocations not found, relink with -q.
  PIN_ERR_VERSION_SKEW | 0 args. pintool version does not match pin version.
  PIN_ERR_MS_DOS | 0 args. ms-dos & win16 application are not supported.
  PIN_ERR_LONG_PATH | 0 args. fully qualified pathname of pin executable is too long.
  PIN_ERR_CANNOT_EXECUTE_FILE | 1 arg: filename. cannot execute application.
  PIN_ERR_BLOCKSIG_TOOL | 1 arg: signal number. Tool intercepted signal and forwarded while application had it blocked.
  PIN_ERR_BLOCKSIG_APP | 1 arg: signal number. Application received asynchronous blocked signal, which can't be emulated.
  PIN_ERR_USER_SPECIFIED_ERROR | reserved. internal use only
  PIN_ERR_OUT_OF_MEMORY | 0 args. Pin is out of memory.
  PIN_ERR_NON_NUMERIC_STRING | 1 arg: string. Non-numeric string passed to conversion utility.
  PIN_ERR_EMPTY_STRING | 0 args. Empty string passed to conversion utility.
  PIN_ERR_NUMERIC_FROM_STRING | 1 arg: string. Error in numeric to string conversion utility.
  PIN_ERR_ALREADY_ATTACHED | 0 args. Pin is already attached to the process.
  PIN_ERR_ILLEGAL_EXCEPTION | 1 arg: string. Tool raised invalid exception.
  PIN_ERR_EXCEPTION_NEEDS_ADDR | 1 arg: string. Must specify access address for exception.
  PIN_ERR_PREDEFINED_INSTRUMENTATION_FAILED | 1 arg: string. Specified function can not be instrumented
  PIN_ERR_UNSUPPORTED_SYSCALL | 1 arg: string. System call is not supported by Pin
  PIN_ERR_ACCESS_DENIED | 0 args. File access denied due to bad permissions
  PIN_ERR_INVALID_SUSPEND_REQUEST | 0 args. Attempting to suspend an internal thread
  PIN_ERR_DEBUGGER | 0 args. Error related to debugger

## Function Documentation

VOID LEVEL_PINCLIENT::PIN_WriteErrorMessage | ( | const char * | msg,
|  | INT32 | type,
|  | PIN_ERR_SEVERITY_TYPE | severity,
|  | INT32 | num,
|  |  | ...
| ) |

| Writes the given error message to the Pin error file. The error file name is specified using the -error_file switch. This API allows tool writer to write a tool-specified error message to the Pin error file. Pin reserves the error type enums from 0-999. Pin will exit after printing a fatal message.
This function can be used in any thread, including any internal thread spawned by the tool.

Parameters:

  | msg | a description of the error
  | type | an enum associated with the error. type >= 1000.
  | severity | 0=fatal, 1=non-fatal.
  | num | number of arguments following this parameter
  | ... | arguments. must be of type "char *".

Availability:
  Mode: JIT, Probe
  O/S: Linux, Windows
  CPU: All.