Pin
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Macros | Typedefs | Functions
Pin Deprecated API

Macros

#define PIN_DEPRECATED_WARNINGS   1
 

Typedefs

typedef VOID(* LEVEL_PINCLIENT::SIGNAL_BEFORE_CALLBACK )(THREADID threadIndex, INT32 sig, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)
 
typedef VOID(* LEVEL_PINCLIENT::SIGNAL_AFTER_CALLBACK )(THREADID threadIndex, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)
 
typedef VOID(* LEVEL_PINCLIENT::THREAD_BEGIN_CALLBACK )(THREADID threadIndex, VOID *sp, int flags, VOID *v)
 
typedef VOID(* LEVEL_PINCLIENT::THREAD_END_CALLBACK )(THREADID threadIndex, INT32 code, VOID *v)
 
typedef BOOL(* LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK )(THREADID threadIndex, INT32 sig, CONTEXT *ctxt, BOOL hasHndlr, VOID *v)
 

Functions

PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsRewritableMemOpBaseLimited (INS ins, MEMORY_TYPE mtype, REG &base)
 
PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsRewritableMemOpBase (INS ins, MEMORY_TYPE mtype, REG &base)
 
PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsDynamicRewritableMemOpBase (INS ins, MEMORY_TYPE mtype, REG &reg)
 
PIN_DEPRECATED_API ADDRINT LEVEL_CORE::INS_MemoryOffset (INS ins)
 
PIN_DEPRECATED_API ADDRDELTA LEVEL_CORE::INS_MemoryDisplacementSigned (INS ins)
 
PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_OperandReadAndWriten (INS ins, UINT32 n)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_FindLineFileByAddress (ADDRINT address, INT32 *line, const CHAR **file)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_FindColumnLineFileByAddress (ADDRINT address, INT32 *column, INT32 *line, const CHAR **file)
 
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalBeforeFunction (SIGNAL_BEFORE_CALLBACK fun, VOID *val)
 
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalAfterFunction (SIGNAL_AFTER_CALLBACK fun, VOID *val)
 
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalInterceptFunction (INT32 sig, SIGNAL_INTERCEPT_CALLBACK fun, VOID *val)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_AddThreadBeginFunction (THREAD_BEGIN_CALLBACK fun, VOID *val)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_AddThreadEndFunction (THREAD_END_CALLBACK fun, VOID *val)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_StartProbedProgram ()
 
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbe (RTN rtn)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::RTN_ReplaceWithUninstrumentedRoutine (RTN replacedRtn, AFUNPTR replacementFun)
 
PIN_DEPRECATED_API BBL LEVEL_PINCLIENT::RTN_BblHead (RTN x)
 
PIN_DEPRECATED_API BBL LEVEL_PINCLIENT::RTN_BblTail (RTN x)
 
PIN_DEPRECATED_API INT32 LEVEL_PINCLIENT::RTN_No (RTN x)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_RegisterItcAuxCallBackPushFun (AFUNPTR callBackPushFun)
 
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::RTN_ComplexReplaceWithUninstrumentedRoutine (RTN replacedRtn, AFUNPTR replacementFun)
 
PIN_DEPRECATED_API ADDRINT LEVEL_PINCLIENT::PIN_FindAlternateAppStack ()
 
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::ParseCommandLine (int xargc, CHAR **xargv)
 
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_ChangeMemOpToBaseRegisterAddressMode (INS ins, MEMORY_TYPE mtype, REG newBase)
 
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_RewriteMemoryAddressingToBaseRegisterOnly (INS ins, MEMORY_TYPE mtype, REG newBase)
 
BOOL LEVEL_PINCLIENT::PIN_SetThreadData (TLS_KEY key, const VOID *data)
 
VOID * LEVEL_PINCLIENT::PIN_GetThreadData (TLS_KEY key)
 

Detailed Description

APIs from older versions of Pin that have been replaced by more powerful, or simpler, interfaces in the current version of Pin. The newer APIs should be used instead of these interfaces.

Macro Definition Documentation

#define PIN_DEPRECATED_WARNINGS   1

By default Pin will annotate deprecated parts of the API so that their use in tools will generate compiler warnings. If you want to suppress these warnings during the compilation of your tool, you can do so by defining the macro PIN_DEPRECATED_WARNINGS with the value zero.

Typedef Documentation

typedef VOID(* LEVEL_PINCLIENT::SIGNAL_AFTER_CALLBACK)(THREADID threadIndex, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)

Call back function when application signal handler returns.

Parameters
threadIndexThe Pin thread ID of the thread that handled the signal.
ctxtFromApplication's register state at end of handler.
ctxtToApplication's register state to which the handler is returning.
vThe tool's call-back value.
Note
DEPRECATED: See PIN_AddContextChangeFunction().
typedef VOID(* LEVEL_PINCLIENT::SIGNAL_BEFORE_CALLBACK)(THREADID threadIndex, INT32 sig, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)

Call back function when application handles a signal.

Parameters
threadIndexThe Pin thread ID of the thread that handles the signal.
sigThe signal number.
ctxtFromApplication's register state when it was interrupted by the signal.
ctxtToApplication's register state at start of handler.
vThe tool's call-back value.
Note
DEPRECATED: See PIN_AddContextChangeFunction().
typedef BOOL(* LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK)(THREADID threadIndex, INT32 sig, CONTEXT *ctxt, BOOL hasHndlr, VOID *v)

Call back function when tool creates its own signal handler.

Parameters
threadIndexThe Pin thread ID of the thread that handled the signal.
sigThe signal number.
ctxtApplication's register state when it was interrupted by the signal. The tool may change this context if desired. If so, the application continues at the modified context. Or, if the application's signal handler is invoked, that handler returns to the modified context.
hndlrBoolean indicating if the application has a registered signal handler.
vThe tool's call-back value.
Returns
Returning TRUE tells Pin to pass the signal on to the application's handler (if any). If the tool returns FALSE or if the application has no handler, execution continues at ctxt.
Note
DEPRECATED: See PIN_InterceptSignal() and PIN_UnblockSignal().
typedef VOID(* LEVEL_PINCLIENT::THREAD_BEGIN_CALLBACK)(THREADID threadIndex, VOID *sp, int flags, VOID *v)

Call back function when thread begins

Note
DEPRECATED: See PIN_AddThreadStartFunction().
typedef VOID(* LEVEL_PINCLIENT::THREAD_END_CALLBACK)(THREADID threadIndex, INT32 code, VOID *v)

Call back function when thread ends

Note
DEPRECATED: See PIN_AddThreadFiniFunction().

Function Documentation

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_ChangeMemOpToBaseRegisterAddressMode ( INS  ins,
MEMORY_TYPE  mtype,
REG  newBase 
)

Change this memory access instruction use a base register addressing mode. On IA-32/Intel(R) 64, it will not rewrite all references; See INS_IsRewritableMemOpBaseLimited() for details.

Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
Note
DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().
PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsDynamicRewritableMemOpBase ( INS  ins,
MEMORY_TYPE  mtype,
REG &  reg 
)

Test if this memory operation can be rewritten dynamically and return the base register

Note
DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().
PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsRewritableMemOpBase ( INS  ins,
MEMORY_TYPE  mtype,
REG &  base 
)
Returns
true if this instruction has a memory op that can be rewritten. Exclude anything with implicit memory operations, but allow the string ops. Exclude a write if has the same base register as a read because we'll rewrite it when we do the read.

Exclude some implicit stack operations (associated w/call,ret) as they cannot be rewritten.

Note
DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().
PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsRewritableMemOpBaseLimited ( INS  ins,
MEMORY_TYPE  mtype,
REG &  base 
)
Returns
true if this instruction has a memory op that can be rewritten. Exclude memory accesses with rIP or rSP as the base register. Exclude anything with no base register. (This will exclude instructions that have an index reg with no base reg). (This will exclude instructions that just use a displacement to access memory). Exclude anything with a segment prefix. Exclude LEAVE operations. Exclude a write if has the same base register as a read because we'll rewrite it when we do the read.
Note
DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().
PIN_DEPRECATED_API ADDRDELTA LEVEL_CORE::INS_MemoryDisplacementSigned ( INS  ins)
Note
DEPRECATED: See INS_MemoryDisplacement().
PIN_DEPRECATED_API ADDRINT LEVEL_CORE::INS_MemoryOffset ( INS  ins)
Note
DEPRECATED: See INS_MemoryDisplacement().
PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_OperandReadAndWriten ( INS  ins,
UINT32  n 
)

Old name for the previous function; this name is a typo. For backward compatibility we keep it.

Note
DEPRECATED: See INS_OperandReadAndWritten().
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_RewriteMemoryAddressingToBaseRegisterOnly ( INS  ins,
MEMORY_TYPE  mtype,
REG  newBase 
)

Change this memory access instruction to reference the virtual memory location contained in the given register.

On IA-32 and Intel64, the modified operand uses only base register addressing with the new base register newBase. Any index, scale, or offset fields from that operand in the original instruction are removed. In addition, if the original instruction's operand uses a segment override, the instruction is changed to use the default segment.

A memory operand can't be rewritten when:

  • the operand is implicit, but string operations are allowed
  • write operand has the same base register as read
  • some implicit stack operations (associated w/call,ret)
Parameters
[in]insinput instruction
[in]mtypecontrols which operand to rewrite (read, write or second read operand)
[in]newBaseregister used as the new memory base address
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures
Note
DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::ParseCommandLine ( int  xargc,
CHAR **  xargv 
)
Note
DEPRECATED: See the return value from PIN_Init().
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalAfterFunction ( SIGNAL_AFTER_CALLBACK  fun,
VOID *  val 
)

Register a notification function that is called immediately after the application returns from a signal handler. This notification only occurs if the application returns "normally" from the signal handler. If the application jumps out of its handler early (e.g. via longjmp), the notification does not occur.

Parameters
funCall back function to execute immediately after the application's signal handler.
valValue to pass to the function.
Returns
TRUE if succeeds, FALSE otherwise
Note
DEPRECATED: See PIN_AddContextChangeFunction().
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalBeforeFunction ( SIGNAL_BEFORE_CALLBACK  fun,
VOID *  val 
)

Register a notification function that is called immediately before the application jumps to a signal handler. The tool is only notified of a signal that the application actually handles. Unhandled signals do not trigger a notification.

Parameters
funCall back function to execute immediately before the application's signal handler.
valValue to pass to the function.
Returns
TRUE if succeeds, FALSE otherwise
Note
Function always return FALSE on Windows
DEPRECATED: See PIN_AddContextChangeFunction().
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalInterceptFunction ( INT32  sig,
SIGNAL_INTERCEPT_CALLBACK  fun,
VOID *  val 
)

Takes over ownership of a signal for the tool and establishes a tool handler for the signal. Tools should never call sigaction() directly to handle signals.

Use this function to take over "ownership" of a signal. If you want to be notified when the application receives a signal, use PIN_AddContextChangeFunction() instead.

Tools should take care when intercepting signals, because this can adversely affect the application if it also uses the signal. The application is still allowed to set up its own handler for an intercepted signal. However, the application is prevented from attempts to block the signal.

When an intercepted signal is received, the tool's handler is called first. The tool's handler then decides whether the signal should be forwarded to the application's handler (if any).

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

Parameters
sigThe signal number to handle.
funThe tool's handler function, or NULL to return ownership of the signal back to the application.
valValue to pass to the handler function.
Returns
TRUE if succeeds, FALSE otherwise
Availability:
Mode: JIT
O/S: Linux
CPU: All
Note
Intercepting a signal immediately forces the current thread to unblock that signal. This ensures that the application cannot prevent the tool from receiving the signal. Any future threads that the application creates will also be prevented from blocking the signal. However, if there are existing threads in the application when the tool intercepts a signal, those threads will not be prevented from blocking the intercepted signal until some future time. There is no guarantee on when the other threads will unblock the intercepted signal, and they may never do so if they are permanently blocked in a system call. To avoid this problem, it is safest to call PIN_AddSignalInterceptFunction() before starting the application with PIN_StartProgram().
Function always return FALSE on Windows
DEPRECATED: See PIN_InterceptSignal() and PIN_UnblockSignal().
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_AddThreadBeginFunction ( THREAD_BEGIN_CALLBACK  fun,
VOID *  val 
)

Call func immediately after a new thread has been created

Parameters
funCall back function to execute after new thread has been created
valValue to be passed to fun when it is called
Note
DEPRECATED: See PIN_AddThreadStartFunction().
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_AddThreadEndFunction ( THREAD_END_CALLBACK  fun,
VOID *  val 
)

Call func immediately before a thread ends

Parameters
funCall back function to execute before new thread ends
valValue to be passed to fun when it is called
Note
DEPRECATED: See PIN_AddThreadFiniFunction().
PIN_DEPRECATED_API ADDRINT LEVEL_PINCLIENT::PIN_FindAlternateAppStack ( )

If we are currently on a pin stack, return a location on the application stack where we can "unswitch to" and continue execution there

Note
DEPRECATED.
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_FindColumnLineFileByAddress ( ADDRINT  address,
INT32 *  column,
INT32 *  line,
const CHAR **  file 
)

Find the line number, file, and column number corresponding to a memory address. Compile your program with -g to include line number information. Pin can only read dwarf2 information, which is the default for most modern compilers. Use -gdwarf-2 if you are using gcc 2.96.

Parameters
[in]addressThe code address to lookup.
[out]columnA pointer to the variable that will hold the column number. Returns -1 if the address has no valid column information or if the compiler did not annotate a specific column for this address.
[out]lineA pointer to the variable that will hold the line number. Returns zero if the address has no valid line information.
[out]fileA pointer to the variable that will hold the file name. Returns NULL if the address has no valid file information.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All
Note
DEPRECATED: see PIN_GetSourceLocation().
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_FindLineFileByAddress ( ADDRINT  address,
INT32 *  line,
const CHAR **  file 
)

Find the line number and file corresponding to a memory address. Compile your program with -g to include line number information. Pin can only read dwarf2 information, which is the default for most modern compilers. Use -gdwarf-2 if you are using gcc 2.96.

Parameters
[in]addressThe code address to lookup.
[out]lineA pointer to the variable that will hold the line number. Returns zero if the address has no valid line information.
[out]fileA pointer to the variable that will hold the file name. Returns NULL if the address has no valid file information.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All
Note
DEPRECATED: see PIN_GetSourceLocation().
VOID* LEVEL_PINCLIENT::PIN_GetThreadData ( TLS_KEY  key)

Get the value stored in the specified TLS slot of the thread.

Note
DEPRECATED and NO LONGER SUPPORTED. Please use the version of this function which takes a THREADID argument.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_RegisterItcAuxCallBackPushFun ( AFUNPTR  callBackPushFun)

This API is only used by the Intel Thread Checker. Calling this API to register the function that libtcheck provides to push the original function pointer of a replaced function onto Thread Checker's internal storage. Once this API is called, the function replacement bridge will call "callBackPushFun" with the original function pointer of the replaced function as the parameter.

Note
DEPRECATED.
BOOL LEVEL_PINCLIENT::PIN_SetThreadData ( TLS_KEY  key,
const VOID *  data 
)

Store specified value in the specified TLS slot of the thread.

Note
DEPRECATED and NO LONGER SUPPORTED. Please use the version of this function which takes a THREADID argument.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_StartProbedProgram ( )

Starts program executing, never returns. PIN_Init must be called first. The command line option -probe must be invoked when using PIN_StartProbedProgram(). A probed program only invokes instrumentation at explicitly inserted probe points.

Note
DEPRECATED: See PIN_StartProgramProbed().
PIN_DEPRECATED_API BBL LEVEL_PINCLIENT::RTN_BblHead ( RTN  x)
Returns
A bbl contains the INSs of the RTN.

The RTN must have been opened by RTN_Open in order to receive a valid BBL. Note that RTN is not broken up into BBLs. The returned bbl will contain all the INSs of the RTN that Pin could find through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All
Note
DEPRECATED: See RTN_InsHead().
PIN_DEPRECATED_API BBL LEVEL_PINCLIENT::RTN_BblTail ( RTN  x)
Returns
A bbl contains the INSs of the RTN.

The RTN must have been opened by RTN_Open in order to receive a valid BBL. Note that RTN is not broken up into BBLs. The returned bbl will contain all the INSs of the RTN that Pin could find through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All
Note
DEPRECATED: See RTN_InsTail().
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::RTN_ComplexReplaceWithUninstrumentedRoutine ( RTN  replacedRtn,
AFUNPTR  replacementFun 
)

Replace a function in the application (replacedRtn) by another function defined in the Pintool (replacementFun). The replacement function is not instrumented. Difference between RTN_ReplaceWithUninstrumentedRoutine() and RTN_ComplexReplaceWithUninstrumentedRoutine() is that the latter does complex replacement (i.e. a call to the callBackPushFun registered will be made before calling to the replacement function).

Note
DEPRECATED.
PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbe ( RTN  rtn)

Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise. Please use RTN_IsSafeForProbedInsertion() if you want to insert a call before or after routine.

Note
DEPRECATED: See RTN_IsSafeForProbedReplacement().
PIN_DEPRECATED_API INT32 LEVEL_PINCLIENT::RTN_No ( RTN  x)
Returns
Number of routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All
Note
DEPRECATED: See RTN_Id().
PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::RTN_ReplaceWithUninstrumentedRoutine ( RTN  replacedRtn,
AFUNPTR  replacementFun 
)

Replace a function in the application (replacedRtn) by another function defined in the Pintool (replacementFun). The replacement function is not instrumented.

Note
DEPRECATED: See RTN_Replace() and RTN_ReplaceProbed().