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

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]	addr	The address of the requested breakpoint.
[in]	size	The size of the breakpoint (HW/SW)
[in]	insert	Whether if this is a breakpoint insertion or deletion.
[in]	v	The 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]	threadIndex	The Pin thread ID of the debugger's "focus" thread.
[in]	ctxt	Application 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]	cmd	The debugger command.
[out]	reply	Receives the reply to the command, if the interpreter understands cmd.
[in]	v	The 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]	toolRegId	Identifies the emulated register (from the registerDescriptions parameter to PIN_AddDebuggerRegisterEmulator()).
[in]	tid	Identifies the thread whose register is read.
[in]	ctxt	Architected register state for the thread.
[out]	data	Points 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]	v	The 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]	name	The name of the requested document.
[in]	size	Size (bytes) of the buf buffer.
[out]	buf	Points 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]	v	The 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]	tid	The Pin thread ID of the thread that received the debugging event.
[in]	eventType	Tells the debugging event.
[in,out]	ctxt	On 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]	arg	The 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]	toolRegId	Identifies the emulated register (from the registerDescriptions parameter to PIN_AddDebuggerRegisterEmulator()).
[in]	tid	Identifies the thread whose register is written.
[in]	ctxt	Architected register state for the thread.
[in]	data	Points to the new value for the register. The value is stored in the same format as described in GET_EMULATED_REGISTER_CALLBACK.
[in]	v	The tool's call-back value.

Enumeration Type Documentation

◆ DEBUG_CONNECTION_TYPE

enum 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

enum 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

enum 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

enum 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

enum 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

img	The 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

img	The image object to act on
loaderInfo	Points 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]	fun	The breakpoint handler function.
[in]	val	Value 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]	numRegisters	The number of entries in registerDescriptions.
[in]	registerDescriptions	An array describing each register that the debugger will know about. This includes both native registers and emulated registers.
[in]	getFun	Call-back function that Pin calls to get the value of an emulated register.
[in]	setFun	Call-back function that Pin calls to set the value of an emulated register.
[in]	getDescriptionFun	Call-back function that Pin calls to get the content of a text document that tells the debugger about the registers defined in registerDescriptions.
[in]	val	Value 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]	fun	The debug interpreter function.
[in]	val	Value 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]	ctxt	The 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]	tid	The ID of the calling thread.
[in]	waitIfNoDebugger	If 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]	msg	Tells 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 \i ctxt parameter that was passed to PIN_ApplicationBreakpoint().

Parameters

[in]	tid	Pin ID of a stopped thread.
[in]	squash	If TRUE, the breakpoint request is squashed. The msg parameter is ignored in this case.
[in]	msg	The 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] info Receives 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]	tid	Pin ID of a stopped thread.
[out]	msg	If 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]	eventType	Tells the type of events to intercept.
[in]	fun	The tool's interceptor function, or NULL.
[in]	val	Value 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] fun The 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] fun The 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] addr The 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] mode Tells 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] timeout A 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

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ DEBUG_BREAKPOINT_CALLBACK

◆ DEBUG_INTERPRETER_CALLBACK

◆ GET_EMULATED_REGISTER_CALLBACK

◆ GET_TARGET_DESCRIPTION_CALLBACK

◆ INTERCEPT_DEBUGGING_EVENT_CALLBACK

◆ SET_EMULATED_REGISTER_CALLBACK

Enumeration Type Documentation

◆ DEBUG_CONNECTION_TYPE

◆ DEBUG_MODE_OPTION

◆ DEBUG_STATUS

◆ DEBUGGER_TYPE

◆ DEBUGGING_EVENT

Function Documentation

◆ IMG_GetLoaderInfo()

◆ IMG_SetLoaderInfo()

◆ PIN_AddBreakpointHandler()

◆ PIN_AddDebuggerRegisterEmulator()

◆ PIN_AddDebugInterpreter()

◆ PIN_ApplicationBreakpoint()

◆ PIN_ChangePendingToolBreakpointOnStoppedThread()

◆ PIN_GetDebugConnectionInfo()

◆ PIN_GetDebuggerType()

◆ PIN_GetDebugStatus()

◆ PIN_GetStoppedThreadPendingToolBreakpoint()

◆ PIN_InterceptDebuggingEvent()

◆ PIN_RemoveBreakpointHandler()

◆ PIN_RemoveDebugInterpreter()

◆ PIN_ResetBreakpointAt()

◆ PIN_SetDebugMode()

◆ PIN_WaitForDebuggerToConnect()