- Main Page
- Modules
- Classes

- Search for |

# Pin Deprecated API

## Defines

#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.

## Define 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:

  | threadIndex | The Pin thread ID of the thread that handled the signal.
  | ctxtFrom | Application's register state at end of handler.
  | ctxtTo | Application's register state to which the handler is returning.
  | v | The 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:

  | threadIndex | The Pin thread ID of the thread that handles the signal.
  | sig | The signal number.
  | ctxtFrom | Application's register state when it was interrupted by the signal.
  | ctxtTo | Application's register state at start of handler.
  | v | The 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:

  | threadIndex | The Pin thread ID of the thread that handled the signal.
  | sig | The signal number.
  | ctxt | Application'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.
  | hndlr | Boolean indicating if the application has a registered signal handler.
  | v | The 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]` | ins | input instruction
  `[in]` | mtype | controls which operand to rewrite (read, write or second read operand)
  `[in]` | newBase | register 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:

  | fun | Call back function to execute immediately after the application's signal handler.
  | val | Value 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:

  | fun | Call back function to execute immediately before the application's signal handler.
  | val | Value 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:

  | sig | The signal number to handle.
  | fun | The tool's handler function, or NULL to return ownership of the signal back to the application.
  | val | Value 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:

  | fun | Call back function to execute after new thread has been created
  | val | Value 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:

  | fun | Call back function to execute before new thread ends
  | val | Value 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]` | address | The code address to lookup.
  `[out]` | column | A 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]` | line | A pointer to the variable that will hold the line number. Returns zero if the address has no valid line information.
  `[out]` | file | A 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]` | address | The code address to lookup.
  `[out]` | line | A pointer to the variable that will hold the line number. Returns zero if the address has no valid line information.
  `[out]` | file | A 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 funtion).

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().