RTN: Routine Object

Typedefs
typedef VOID(*	LEVEL_PINCLIENT::RTN_INSTRUMENT_CALLBACK )(RTN rtn, VOID *v)
Functions
SEC	LEVEL_PINCLIENT::RTN_Sec (RTN x)
RTN	LEVEL_PINCLIENT::RTN_Next (RTN x)
RTN	LEVEL_PINCLIENT::RTN_Prev (RTN x)
RTN	LEVEL_PINCLIENT::RTN_Invalid ()
BOOL	LEVEL_PINCLIENT::RTN_Valid (RTN x)
BBL	LEVEL_PINCLIENT::RTN_BblHead (RTN x)
BBL	LEVEL_PINCLIENT::RTN_BblTail (RTN x)
const string &	LEVEL_PINCLIENT::RTN_Name (RTN x)
AFUNPTR	LEVEL_PINCLIENT::RTN_Funptr (RTN x)
INT32	LEVEL_PINCLIENT::RTN_No (RTN x)
VOID	LEVEL_PINCLIENT::RTN_AddInstrumentFunction (RTN_INSTRUMENT_CALLBACK fun, VOID *val)
USIZE	LEVEL_PINCLIENT::RTN_Size (RTN rtn)
string	LEVEL_PINCLIENT::RTN_FindNameByAddress (ADDRINT address)
RTN	LEVEL_PINCLIENT::RTN_FindByAddress (ADDRINT address)
RTN	LEVEL_PINCLIENT::RTN_FindByName (IMG img, const CHAR *name)
VOID	LEVEL_PINCLIENT::RTN_Open (RTN rtn)
VOID	LEVEL_PINCLIENT::RTN_Close (RTN rtn)
INS	LEVEL_PINCLIENT::RTN_InsHead (RTN rtn)
VOID	LEVEL_PINCLIENT::RTN_InsertCall (RTN rtn, IPOINT action, AFUNPTR funptr,...)
ADDRINT	LEVEL_PINCLIENT::RTN_Address (RTN rtn)
VOID	LEVEL_PINCLIENT::RTN_ReplaceWithUninstrumentedRoutine (RTN replacedRtn, AFUNPTR replacementFun)
VOID	LEVEL_PINCLIENT::RTN_Replace (RTN replacedRtn, AFUNPTR replacementFun)
AFUNPTR	LEVEL_PINCLIENT::RTN_ReplaceProbed (RTN replacedRtn, AFUNPTR replacementFun)

---

Detailed Description

A RTN represents the functions/routines/procedures typically produced by a compiler for a procedural programming language such as C. Pin finds routines by using the symbol table information. You must call PIN_InitSymbols() so that symbol table information will be available. Can be accessed at instrumentation time and analysis time.

Iteration idioms:

  // Forward pass over all routines in a section
  for( RTN rtn= SEC_RtnHead(sec); RTN_Valid(rtn); rtn = RTN_Next(rtn) )

  // Reverse pass over all routines in a section
  for( RTN rtn= SEC_RtnTail(sec); RTN_Valid(rtn); rtn = RTN_Prev(rtn) )

---

Typedef Documentation

typedef VOID(* LEVEL_PINCLIENT::RTN_INSTRUMENT_CALLBACK)(RTN rtn, VOID *v)

Call back function used to instrument routines

---

Function Documentation

VOID LEVEL_PINCLIENT::RTN_AddInstrumentFunction (  RTN_INSTRUMENT_CALLBACK  fun, VOID *  val )

Add a function used to instrument at routine granularity Parameters: fun  Instrumentation function for routines val  Passed as the second argument to the instrumentation function

ADDRINT LEVEL_PINCLIENT::RTN_Address (  RTN  rtn  )

Returns: Address in memory of rtn

BBL LEVEL_PINCLIENT::RTN_BblHead (  RTN  x  )

Returns: First bbl of rtn

BBL LEVEL_PINCLIENT::RTN_BblTail (  RTN  x  )

Returns: Last bbl of rtn

VOID LEVEL_PINCLIENT::RTN_Close (  RTN  rtn  )

Close rtn, must be called before opening a new rtn

RTN LEVEL_PINCLIENT::RTN_FindByAddress (  ADDRINT  address  )

Parameters: Address  Memory address that corresponds to the RTN Returns: Handle to the RTN found. If not found returns RTN_Invalid() In a multithreaded program, the returned RTN handle could go stale if another thread unloaded the shared object that contains the RTN. Use PIN_LockClient() before calling this routine and PIN_UnlockClient() after the last use of the returned RTN handle. Locking is automatic from an instrumentation routine, so it unecessary (but harmless) to lock calls to this function from an instrumentation routine. If you just want the name, call RTN_FindNameByAddress, which automatically does the locking and returns a string which will not go stale if the shared library is unloaded

RTN LEVEL_PINCLIENT::RTN_FindByName (  IMG  img, const CHAR *  name )

Parameters: Img  Image in which to search for RTN Name  Name of the RTN to search in IMG Returns: Handle to the RTN found. If not found returns RTN_Invalid()

string LEVEL_PINCLIENT::RTN_FindNameByAddress (  ADDRINT  address  )

Parameters: Address  Memory address that corresponds to the RTN Returns: Name of routine, or "" if it is not found

AFUNPTR LEVEL_PINCLIENT::RTN_Funptr (  RTN  x  )

an rtn to a funptr

VOID LEVEL_PINCLIENT::RTN_InsertCall (  RTN  rtn, IPOINT  action, AFUNPTR  funptr,   ... )

Insert call relative to a rtn. Parameters: rtn  Routine to instrument action  Use IPOINT_BEFORE to call funptr before execution, or IPOINT_AFTER for immediately before the return funptr  Analysis function to call ...  Arguments to pass to funptr

INS LEVEL_PINCLIENT::RTN_InsHead (  RTN  rtn  )

You must call RTN_Open before the first time this is called for an rtn Returns: First instruction of rtn, or RTN_Invalid() if no instructions

RTN LEVEL_PINCLIENT::RTN_Invalid (   )

Returns: RTN value that indicates no valid image

const string& LEVEL_PINCLIENT::RTN_Name (  RTN  x  )

Returns: Name of routine

RTN LEVEL_PINCLIENT::RTN_Next (  RTN  x  )

Returns: Routine that follows x, or RTN_Invalid() if x is the last in the section

INT32 LEVEL_PINCLIENT::RTN_No (  RTN  x  )

Returns: Number of routine

VOID LEVEL_PINCLIENT::RTN_Open (  RTN  rtn  )

Open rtn, must be called before RTN_InsHead or RTN_InsertCall().

RTN LEVEL_PINCLIENT::RTN_Prev (  RTN  x  )

Returns: Routine that precedes x, or RTN_Invalid() if x is the first in the section

VOID LEVEL_PINCLIENT::RTN_Replace (  RTN  replacedRtn, AFUNPTR  replacementFun )

Replace a function in the application (replacedRtn) by another function defined in the Pintool (replacementFun). PIN_StartProgram() must be used when using this API.

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceProbed (  RTN  replacedRtn, AFUNPTR  replacementFun )

Replace a routine in the application (replacedRtn) by another function defined in the Pintool (replacementFun) using probes. The replacement function is not instrumented. The signature of the replacement function must be the same as the replaced application routine. Replacement functions typically need to call the replaced routines. However, calls to RTN_Funptr(replacedRtn) will be redirected to replacementFun. Replacement functions must instead call the returned function pointer, which is a copy of the entry point that is not redirected. Parameters: replacedRtn  the application routine to be replaced. replacementFun  the replacement function Returns: a function pointer to the relocated application function entry point. This allows the replacement routine to execute the replaced routine. PIN_StartProgramProbed() must be used when using this API. "-probe" must be used on the command line.

VOID LEVEL_PINCLIENT::RTN_ReplaceWithUninstrumentedRoutine (  RTN  replacedRtn, AFUNPTR  replacementFun )

DEPRECATED - use RTN_ReplaceProbed() or RTN_Replace() instead. Replace a function in the application (replacedRtn) by another function defined in the Pintool (replacementFun). The replacement function is not instrumented.

SEC LEVEL_PINCLIENT::RTN_Sec (  RTN  x  )

Returns: Section that contains this routine

USIZE LEVEL_PINCLIENT::RTN_Size (  RTN  rtn  )

Returns: size of routine in bytes

BOOL LEVEL_PINCLIENT::RTN_Valid (  RTN  x  )

Returns: True if x is not RTN_Invalid(). RTN_Valid() returns false in certain cases when there is no static image of the code available, includiing dynamically generated code.

---