Pin
Classes | Typedefs | Enumerations | Functions
Application Level Debugging API

Classes

struct  DEBUGGER_REG_DESCRIPTION
 
struct  DEBUG_CONNECTION_INFO
 
struct  DEBUG_MODE
 

Typedefs

typedef BOOL(* DEBUG_INTERPRETER_CALLBACK) (THREADID threadIndex, CONTEXT *ctxt, const std::string &cmd, std::string *reply, VOID *v)
 
typedef BOOL(* DEBUG_BREAKPOINT_CALLBACK) (ADDRINT addr, UINT size, BOOL insert, VOID *v)
 
typedef BOOL(* INTERCEPT_DEBUGGING_EVENT_CALLBACK) (THREADID tid, DEBUGGING_EVENT eventType, CONTEXT *ctxt, VOID *arg)
 
typedef VOID(* GET_EMULATED_REGISTER_CALLBACK) (unsigned toolRegId, THREADID tid, CONTEXT *ctxt, VOID *data, VOID *v)
 
typedef VOID(* SET_EMULATED_REGISTER_CALLBACK) (unsigned toolRegId, THREADID tid, CONTEXT *ctxt, const VOID *data, VOID *v)
 
typedef USIZE(* GET_TARGET_DESCRIPTION_CALLBACK) (const std::string &name, USIZE size, VOID *buf, VOID *v)
 

Enumerations

enum  DEBUGGING_EVENT {
  DEBUGGING_EVENT_BREAKPOINT,
  DEBUGGING_EVENT_SINGLE_STEP,
  DEBUGGING_EVENT_ASYNC_BREAK
}
 
enum  DEBUG_STATUS {
  DEBUG_STATUS_DISABLED,
  DEBUG_STATUS_UNCONNECTABLE,
  DEBUG_STATUS_UNCONNECTED,
  DEBUG_STATUS_CONNECTED
}
 
enum  DEBUG_CONNECTION_TYPE {
  DEBUG_CONNECTION_TYPE_NONE,
  DEBUG_CONNECTION_TYPE_TCP_SERVER,
  DEBUG_CONNECTION_TYPE_TCP_CLIENT
}
 
enum  DEBUGGER_TYPE {
  DEBUGGER_TYPE_UNKNOWN,
  DEBUGGER_TYPE_GDB,
  DEBUGGER_TYPE_LLDB,
  DEBUGGER_TYPE_IDB,
  DEBUGGER_TYPE_VISUAL_STUDIO_VSDBG,
  DEBUGGER_TYPE_VISUAL_STUDIO
}
 
enum  DEBUG_MODE_OPTION {
  DEBUG_MODE_OPTION_NONE = 0,
  DEBUG_MODE_OPTION_STOP_AT_ENTRY = (1 << 0),
  DEBUG_MODE_OPTION_SILENT = (1 << 1),
  DEBUG_MODE_OPTION_ALLOW_REMOTE = (1 << 2)
}
 

Functions

VOID PIN_InterceptDebuggingEvent (DEBUGGING_EVENT eventType, INTERCEPT_DEBUGGING_EVENT_CALLBACK fun, VOID *arg)
 
VOID PIN_AddDebuggerRegisterEmulator (unsigned numRegisters, const DEBUGGER_REG_DESCRIPTION *registerDescriptions, GET_EMULATED_REGISTER_CALLBACK getFun, SET_EMULATED_REGISTER_CALLBACK setFun, GET_TARGET_DESCRIPTION_CALLBACK getDescriptionFun, VOID *val)
 
PIN_CALLBACK PIN_AddDebugInterpreter (DEBUG_INTERPRETER_CALLBACK fun, VOID *val)
 
VOID PIN_RemoveDebugInterpreter (DEBUG_INTERPRETER_CALLBACK fun)
 
PIN_CALLBACK PIN_AddBreakpointHandler (DEBUG_BREAKPOINT_CALLBACK fun, VOID *val)
 
VOID PIN_RemoveBreakpointHandler (DEBUG_BREAKPOINT_CALLBACK fun)
 
VOID PIN_ResetBreakpointAt (ADDRINT addr)
 
VOID PIN_ApplicationBreakpoint (const CONTEXT *ctxt, THREADID tid, BOOL waitIfNoDebugger, const std::string &msg)
 
BOOL PIN_SetDebugMode (const DEBUG_MODE *mode)
 
DEBUG_STATUS PIN_GetDebugStatus ()
 
BOOL PIN_GetDebugConnectionInfo (DEBUG_CONNECTION_INFO *info)
 
DEBUGGER_TYPE PIN_GetDebuggerType ()
 
BOOL PIN_WaitForDebuggerToConnect (unsigned timeout)
 
BOOL PIN_GetStoppedThreadPendingToolBreakpoint (THREADID tid, std::string *msg)
 
BOOL PIN_ChangePendingToolBreakpointOnStoppedThread (THREADID tid, BOOL squash, const std::string &msg)
 
VOID * IMG_GetLoaderInfo (IMG img)
 
VOID IMG_SetLoaderInfo (IMG img, VOID *loaderInfo)
 

Detailed Description

This API allows the user to debug the application that is running on top of Pin. It also allows a tool to interact with the debugger and provide extended commands to the debugger. Also see the tutorial section on this topic: The Pin Advanced Debugging Extensions.

Typedef Documentation

◆ DEBUG_BREAKPOINT_CALLBACK

typedef BOOL(* DEBUG_BREAKPOINT_CALLBACK) (ADDRINT addr, UINT size, BOOL insert, VOID *v)

Call-back function to handle breakpoint set requests from a debugger.

Once a callback accepted control over a breakpoint at the given address, Pin and PinADX will not stop at that address. The stop responsibility is handled solely by the tool.

However, PinADX does keep track of the breakpoint, in case the tool wants to "reset" the breakpoint and give the control back to PinADX.

Parameters
[in]addrThe address of the requested breakpoint.
[in]sizeThe size of the breakpoint (HW/SW)
[in]insertWhether if this is a breakpoint insertion or deletion.
[in]vThe tool's call-back value.
Returns
TRUE if this callback function takes control over the breakpoint. FALSE if it does not. If FALSE is returned, Pin will call the next registered interpreter to see if it understands cmd.

◆ DEBUG_INTERPRETER_CALLBACK

typedef BOOL(* DEBUG_INTERPRETER_CALLBACK) (THREADID threadIndex, CONTEXT *ctxt, const std::string &cmd, std::string *reply, VOID *v)

Pin client functions for the application-level debugger.

Call-back function to handle commands from a debugger.

The format of the cmd and reply strings may vary depending on which debugger is connected to Pin. Tools can call PIN_GetDebuggerType() to tell which debugger is connected.

When the debugger is GDB, cmd is the text string that the user types after the "monitor" command and reply is displayed verbatim as a response to the command.

Pin reserves all command strings that start with the prefix "pin " or "pin:". Pin interprets these commands itself and does not pass them on to the tool.

Parameters
[in]threadIndexThe Pin thread ID of the debugger's "focus" thread.
[in]ctxtApplication register state of the debugger's "focus" thread. The interpreter can change this state if it handles cmd. When the debugger resumes this thread, it will use the new register state in ctxt.
[in]cmdThe debugger command.
[out]replyReceives the reply to the command, if the interpreter understands cmd.
[in]vThe tool's call-back value.
Returns
TRUE if this interpreter function understands cmd. FALSE if it does not. If FALSE is returned, Pin will call the next registered interpreter to see if it understands cmd.

◆ GET_EMULATED_REGISTER_CALLBACK

typedef VOID(* GET_EMULATED_REGISTER_CALLBACK) (unsigned toolRegId, THREADID tid, CONTEXT *ctxt, VOID *data, VOID *v)

Call-back function that Pin calls to get the value of a register emulated by the tool.

Parameters
[in]toolRegIdIdentifies the emulated register (from the registerDescriptions parameter to PIN_AddDebuggerRegisterEmulator()).
[in]tidIdentifies the thread whose register is read.
[in]ctxtArchitected register state for the thread.
[out]dataPoints to a buffer that receives the value of the register. The value must be stored in little-endian format (least significant bytes first). If the register size is not an even multiple of bytes, the upper bits of the last byte (most significant byte) are unused. If the register size is 2, 4, or 8 bytes, data is naturally aligned, so it may be cast to a pointer of the appropriate type.
[in]vThe tool's call-back value.

◆ GET_TARGET_DESCRIPTION_CALLBACK

typedef USIZE(* GET_TARGET_DESCRIPTION_CALLBACK) (const std::string &name, USIZE size, VOID *buf, VOID *v)

Call-back function that Pin calls to get the content of a document that describes an emulated target processor to an application-level debugger. This is useful, for example, when a Pin tool emulates additional registers beyond those defined by the native CPU. A debugger can use this document to understand the emulated registers and how to display them.

The format of the returned document varies depending on the debugger that is connected to Pin. Tools can use PIN_GetDebuggerType() to tell which debugger is connected.

When used with GDB, the description should be an XML "target feature" document, as described in the GDB user manual, "Debugging With GDB". See the appendix titled "Target Descriptions" for details of the XML document format. GDB starts by asking for a document titled "target.xml". However, this document may reference other documents via "include" statements. If so, GDB will ask for those additional documents by their names.

Parameters
[in]nameThe name of the requested document.
[in]sizeSize (bytes) of the buf buffer.
[out]bufPoints to a buffer that receives the content of the document. If the document requires more than size bytes, the tool need not write anything into buf. Instead, the tool should return the required size.
[in]vThe tool's call-back value.
Returns
If the tool knows how to provide the document named name, it returns the size (bytes) of that document. If that size is less than or equal to size, the tool should also write the content of the document to buf. If the tool does not know how to provide this document, it should return zero.

◆ INTERCEPT_DEBUGGING_EVENT_CALLBACK

typedef BOOL(* INTERCEPT_DEBUGGING_EVENT_CALLBACK) (THREADID tid, DEBUGGING_EVENT eventType, CONTEXT *ctxt, VOID *arg)

Call-back function when the tool intercepts a debugging event with PIN_InterceptDebuggingEvent().

Parameters
[in]tidThe Pin thread ID of the thread that received the debugging event.
[in]eventTypeTells the debugging event.
[in,out]ctxtOn input, gives the register state at the point the thread received the event. The tool may change ctxt. If the event is passed on to the debugger, the debugger sees the modified register state. If the event is not passed on to the debugger, the thread resumes execution at the new register state.
[in]argThe tool's call-back value.
Returns
Returning TRUE tells Pin to pass the debugging event on to the debugger. Returning FALSE tells Pin to squash the event and the thread resumes without stopping in the debugger.

The following scenarios are not allowed:

  • The call-back may not return FALSE for DEBUGGING_EVENT_ASYNC_BREAK.
  • If the call-back returns TRUE for DEBUGGING_EVENT_BREAKPOINT or DEBUGGING_EVENT_SINGLE_STEP, it may not change the value of REG_INST_PC in ctxt. This restriction exists because debuggers typically make assumptions on the PC value when these events trigger.

◆ SET_EMULATED_REGISTER_CALLBACK

typedef VOID(* SET_EMULATED_REGISTER_CALLBACK) (unsigned toolRegId, THREADID tid, CONTEXT *ctxt, const VOID *data, VOID *v)

Call-back function that Pin calls to set the value of a register emulated by the tool.

Parameters
[in]toolRegIdIdentifies the emulated register (from the registerDescriptions parameter to PIN_AddDebuggerRegisterEmulator()).
[in]tidIdentifies the thread whose register is written.
[in]ctxtArchitected register state for the thread.
[in]dataPoints to the new value for the register. The value is stored in the same format as described in GET_EMULATED_REGISTER_CALLBACK.
[in]vThe tool's call-back value.

Enumeration Type Documentation

◆ DEBUG_CONNECTION_TYPE

Possible connection types for an application debugger. The connection type can be specified either via the -appdebug knobs or by PIN_SetDebugMode().

Enumerator
DEBUG_CONNECTION_TYPE_NONE 

Application debugging is disabled in this session.

DEBUG_CONNECTION_TYPE_TCP_SERVER 

Pin opens a TCP port and waits for a debugger to connect.

DEBUG_CONNECTION_TYPE_TCP_CLIENT 

Pin connects to a TCP port opened by the debugger.

◆ DEBUG_MODE_OPTION

Options which affect application debugging.

Enumerator
DEBUG_MODE_OPTION_NONE 

No options specified.

DEBUG_MODE_OPTION_STOP_AT_ENTRY 

If this option is set, Pin stops the application at the first instruction and execution remains stopped until a debugger connects and continues the application. If this option is cleared, the application immediately runs when PIN_StartProgram() is called.

DEBUG_MODE_OPTION_SILENT 

If debugging is enabled Pin normally prints a message to the console when PIN_StartProgram() is called which tells the user how to connect a debugger. This option suppresses the message.

DEBUG_MODE_OPTION_ALLOW_REMOTE 

By default, Pin only listens for a debugger's TCP connection on the local machine. If this option is enabled, Pin will also listen for a connection from a remote machine.

◆ DEBUG_STATUS

Possible status codes telling the state of application level debugging.

Enumerator
DEBUG_STATUS_DISABLED 

Application debugging is not enabled in this Pin session.

DEBUG_STATUS_UNCONNECTABLE 

Application debugging is enabled, but it is too early to allow a debugger to connect.

DEBUG_STATUS_UNCONNECTED 

Application debugging is enabled, but no debugger is connected yet.

DEBUG_STATUS_CONNECTED 

Application debugging is enabled and a debugger is connected.

◆ DEBUGGER_TYPE

Application debugger types that could be connected to Pin.

Enumerator
DEBUGGER_TYPE_UNKNOWN 

No debugger connected, or type is unknown.

DEBUGGER_TYPE_GDB 

The GNU debugger.

DEBUGGER_TYPE_LLDB 

The LLVM debugger.

DEBUGGER_TYPE_IDB 

The Intel debugger.

DEBUGGER_TYPE_VISUAL_STUDIO_VSDBG 

Visual Studio via VSDBG.

DEBUGGER_TYPE_VISUAL_STUDIO 

Visual Studio via native connection.

◆ DEBUGGING_EVENT

Possible debugging events that can be intercepted with PIN_InterceptDebuggingEvent().

Enumerator
DEBUGGING_EVENT_BREAKPOINT 

Thread triggered a breakpoint. This does not include breakpoints trigged via PIN_ApplicationBreakpoint().

DEBUGGING_EVENT_SINGLE_STEP 

Thread completed a single-step.

DEBUGGING_EVENT_ASYNC_BREAK 

Thread stopped due to a request from the debugger or because another thread has stopped in the debugger.

Function Documentation

◆ IMG_GetLoaderInfo()

VOID* IMG_GetLoaderInfo ( IMG  img)

Gets a read-only copy of loader information for the image which is used in PIN ADX debugger.

Parameters
imgThe image object to act on
Returns
Pointer to OS specific structure that holds data about loader information. On Linux, this is a pointer to struct LINUX_LOADER_IMAGE_INFO.
Availability:
Mode: JIT
O/S: Linux
CPU: All

◆ IMG_SetLoaderInfo()

VOID IMG_SetLoaderInfo ( IMG  img,
VOID *  loaderInfo 
)

Sets the loader information for the image which are used in PIN ADX debugger.

Parameters
imgThe image object to act on
loaderInfoPoints to OS specific structure that holds data about loader information. On Linux, this is a pointer to struct LINUX_LOADER_IMAGE_INFO.
Availability:
Mode: JIT
O/S: Linux
CPU: All

◆ PIN_AddBreakpointHandler()

PIN_CALLBACK PIN_AddBreakpointHandler ( DEBUG_BREAKPOINT_CALLBACK  fun,
VOID *  val 
)

Register a handler that can intercept breakpoint set/delete commands sent from an application debugger. This API allows a tool to take control over specific breakpoints stop behavior.

A tool may install more than one handler function. Pin calls each one until it reaches an handler that understand the command.

Parameters
[in]funThe breakpoint handler function.
[in]valValue to pass to the handler function.
Note
The pin client lock is obtained during the call of this API.
Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Availability:
Mode: JIT
O/S: Linux, Windows, macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_AddDebuggerRegisterEmulator()

VOID PIN_AddDebuggerRegisterEmulator ( unsigned  numRegisters,
const DEBUGGER_REG_DESCRIPTION registerDescriptions,
GET_EMULATED_REGISTER_CALLBACK  getFun,
SET_EMULATED_REGISTER_CALLBACK  setFun,
GET_TARGET_DESCRIPTION_CALLBACK  getDescriptionFun,
VOID *  val 
)

This API is useful for Pin tools that emulate registers that do not exist in the host machine's ISA. If an application debugger is attached to Pin, this API informs the debugger about the extended registers, allowing users to display and manipulate the emulated registers as though they were native registers. Of course, not all debuggers have this capability. Calling this API for such a non-conforming debugger is legal, but ineffective. A non-conforming debugger will ignore the emulated registers and just display the native ones.

When using this API, the set of registers presented to the debugger is specified in two redundant ways, and it is the tool's responsibility to ensure that they are consistent. One specification is a text document that the debugger reads. This document can have any format that the tool and the debugger agree upon, and could convey information about the registers, how they should be displayed in the debugger, etc. The tool provides this document via the getDescriptionFun call-back. The second register specification is through the registerDescriptions parameter, which Pin uses when communicating the register values to the debugger.

If this API is called, it must be called before calling PIN_StartProgram(). Also, a tool can install only one debugger register emulator, so a call to PIN_AddDebuggerRegisterEmulator() will overwrite any previous call.

When used with GDB, this API is effective only for versions of GDB that support register extensions in the XML "feature document". This includes GDB versions 7.2 and later, as well as some distributions of earlier GDB versions.

Parameters
[in]numRegistersThe number of entries in registerDescriptions.
[in]registerDescriptionsAn array describing each register that the debugger will know about. This includes both native registers and emulated registers.
[in]getFunCall-back function that Pin calls to get the value of an emulated register.
[in]setFunCall-back function that Pin calls to set the value of an emulated register.
[in]getDescriptionFunCall-back function that Pin calls to get the content of a text document that tells the debugger about the registers defined in registerDescriptions.
[in]valValue passed to the call-back functions.
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_AddDebugInterpreter()

PIN_CALLBACK PIN_AddDebugInterpreter ( DEBUG_INTERPRETER_CALLBACK  fun,
VOID *  val 
)

Register a handler that can interpret commands sent from an application debugger. This API allows a tool to extend the normal set of commands understood by a debugger that is connected to Pin.

A tool may install more than one interpreter function. Pin calls each one until it reaches an interpreter that understand the command.

Parameters
[in]funThe debug interpreter function.
[in]valValue to pass to the interpreter function.
Note
The pin client lock is obtained during the call of this API.
Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_ApplicationBreakpoint()

VOID PIN_ApplicationBreakpoint ( const CONTEXT ctxt,
THREADID  tid,
BOOL  waitIfNoDebugger,
const std::string &  msg 
)

A tool can call this API to stop execution in an application debugger as though a breakpoint was hit. The ctxt parameter tells the register state that the debugger sees when the application stops. If application level debugging is not enabled in this Pin session, execution does not stop, but resumes immediately at ctxt. Tools can tell if application level debugging is enabled by calling PIN_GetDebugStatus().

The semantics of this API are very similar to PIN_ExecuteAt(). Both APIs abandon the current analysis function and resume execution at a new CONTEXT. The only difference is that PIN_ApplicationBreakpoint() also stops at a breakpoint in the application debugger.

This API can be called from an analysis function or a replacement routine, but not from a callback.

When this API is called from an analysis function or replacement function, and if they execute the current routine or instruction being analyzed, then execution will resume at the instrumented routine or instruction and the analysis function will be called again. It is the pintool's responsibility to avoid going into an infinite loop of calls to the analysis function.

The expected format of the msg string may depend on which debugger is connected to Pin. Tools can call PIN_GetDebuggerType() to find the debugger type.

When used with GDB, the msg string is displayed verbatim to the user when the debugger stops. The debugger adds a newline to the end of the string before displaying it.

Parameters
[in]ctxtThe register state that is reported to the debugger. When the debugger resumes this thread, it resumes execution at this register state (unless the debugger changes the register state).
[in]tidThe ID of the calling thread.
[in]waitIfNoDebuggerIf waitIfNoDebugger is TRUE and the status is DEBUG_STATUS_UNCONNECTED, PIN_ApplicationBreakpoint() blocks until a debugger connects. Tools can call PIN_GetDebugStatus() to get the status. If waitIfNoDebugger is FALSE or if the status is DEBUG_STATUS_DISABLED or DEBUG_STATUS_UNCONNECTABLE, PIN_ApplicationBreakpoint() resumes immediately at the new context when no debugger is connected.
[in]msgTells the reason why the breakpoint was triggered.
Returns
This API never returns.
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_ChangePendingToolBreakpointOnStoppedThread()

BOOL PIN_ChangePendingToolBreakpointOnStoppedThread ( THREADID  tid,
BOOL  squash,
const std::string &  msg 
)

If the given stopped thread has a pending tool breakpoint, this function can change the message associated with that breakpoint request or it can squash the breakpoint request entirely. The debugger will see the effect of the changed breakpoint after it resumes execution of the thread. If the tool changes the breakpoint message, the debugger will receive the breakpoint event with the new message. If the tool squashes the breakpoint request, the thread will not stop at the breakpoint at all. Instead, it continues executing at the ctxt parameter that was passed to PIN_ApplicationBreakpoint().

Parameters
[in]tidPin ID of a stopped thread.
[in]squashIf TRUE, the breakpoint request is squashed. The msg parameter is ignored in this case.
[in]msgThe new breakpoint message for this breakpoint request.
Returns
TRUE if thread tid is stopped and has a pending breakpoint from PIN_ApplicationBreakpoint().

◆ PIN_GetDebugConnectionInfo()

BOOL PIN_GetDebugConnectionInfo ( DEBUG_CONNECTION_INFO info)

This function retrieves the information that an application level debugger will need in order to connect to this Pin session.

Parameters
[out]infoReceives the connection information.
Returns
TRUE if application level debugging is enabled for this Pin session.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetDebuggerType()

DEBUGGER_TYPE PIN_GetDebuggerType ( )

This function tells the type of application level debugger (if any) that is connected to Pin. If no debugger is connected, returns DEBUGGER_TYPE_UNKNOWN.

Returns
The type of the application level debugger that is connected to Pin.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetDebugStatus()

DEBUG_STATUS PIN_GetDebugStatus ( )

This function tells whether application level debugging is enabled in this Pin session. If so, it tells whether an application debugger is currently connected to Pin.

Returns
A code telling the status of application level debugging.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetStoppedThreadPendingToolBreakpoint()

BOOL PIN_GetStoppedThreadPendingToolBreakpoint ( THREADID  tid,
std::string *  msg 
)

Tells whether a stopped thread has called PIN_ApplicationBreakpoint(), but the breakpoint has NOT yet been reported to the debugger. For example, this can occur if two threads call PIN_ApplicationBreakpoint() simultaneously and the debugger has asked Pin to report one debugger event at a time. In this case, Pin reports one breakpoint to the debugger and leaves the other breakpoint pending.

Parameters
[in]tidPin ID of a stopped thread.
[out]msgIf there is a pending breakpoint and if msg is not NULL, msg receives the breakpoint message.
Returns
TRUE if thread tid is stopped and has a pending breakpoint from PIN_ApplicationBreakpoint().

◆ PIN_InterceptDebuggingEvent()

VOID PIN_InterceptDebuggingEvent ( DEBUGGING_EVENT  eventType,
INTERCEPT_DEBUGGING_EVENT_CALLBACK  fun,
VOID *  arg 
)

Establish an interceptor function for debugging events that Pin sends to an external debugger. This API allows a tool to filter these events before they are visible to the debugger.

A tool can set only one "intercept" function for a particular event, so a new function overwrites any previous one for the same event. To disable an interceptor, pass a NULL function pointer.

Parameters
[in]eventTypeTells the type of events to intercept.
[in]funThe tool's interceptor function, or NULL.
[in]valValue to pass to the interceptor function.
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_RemoveBreakpointHandler()

VOID PIN_RemoveBreakpointHandler ( DEBUG_BREAKPOINT_CALLBACK  fun)

Remove a previously installed breakpoint handler function.

Parameters
[in]funThe breakpoint handler to remove.
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows, macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_RemoveDebugInterpreter()

VOID PIN_RemoveDebugInterpreter ( DEBUG_INTERPRETER_CALLBACK  fun)

Remove a previously installed debug interpreter function.

Parameters
[in]funThe interpreter function to remove.
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_ResetBreakpointAt()

VOID PIN_ResetBreakpointAt ( ADDRINT  addr)

Resets the breakpoint address, and returns the control back to PinADX.

Parameters
[in]addrThe breakpoint address.
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows, macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetDebugMode()

BOOL PIN_SetDebugMode ( const DEBUG_MODE mode)

Set whether application debugging is enabled or disabled in this Pin session and set the debugging mode if debugging is enabled. This API overrides the following knobs if they are specified on the command line:

If the tool calls this API, it must be called before PIN_StartProgram().

Parameters
[in]modeTells whether application debugging is enabled and specifies the mode. If mode->_tcpClient->_ip is set, this method makes a copy of the string.
Returns
TRUE on success, FALSE on failure or if called after PIN_StartProgram().
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_WaitForDebuggerToConnect()

BOOL PIN_WaitForDebuggerToConnect ( unsigned  timeout)

Waits for an application level debugger to connect to this Pin session. This function may only be called after PIN_StartProgram(). If the debugger status is DEBUG_STATUS_DISABLED or DEBUG_STATUS_UNCONNECTABLE, it returns FALSE immediately.

After a successful return, an application level debugger is connected to Pin. The debugger will stop the application soon, but there is no guarantee that this will happen immediately after this API returns. If the tool wants to guarantee an immediate stop, it should call PIN_ApplicationBreakpoint().

Parameters
[in]timeoutA timeout value (milliseconds). This function returns (with FALSE) if a debugger has not connected by the end of the timeout period. A timeout value of zero means wait forever.
Returns
TRUE if an application level debugger is connected.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures