RTN: Routine Object


Typedefs

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

Enumerations

enum  LEVEL_PINCLIENT::PROBE_MODE {
  PROBE_MODE_DEFAULT = 0,
  PROBE_MODE_ALLOW_RELOCATION = (1<<0)
}

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)
const string & LEVEL_PINCLIENT::RTN_Name (RTN x)
SYM LEVEL_PINCLIENT::RTN_Sym (RTN x)
AFUNPTR LEVEL_PINCLIENT::RTN_Funptr (RTN x)
INT32 LEVEL_PINCLIENT::RTN_Id (RTN x)
VOID LEVEL_PINCLIENT::RTN_AddInstrumentFunction (RTN_INSTRUMENT_CALLBACK fun, VOID *val)
USIZE LEVEL_PINCLIENT::RTN_Range (RTN rtn)
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)
INS LEVEL_PINCLIENT::RTN_InsHeadOnly (RTN rtn)
INS LEVEL_PINCLIENT::RTN_InsTail (RTN rtn)
UINT32 LEVEL_PINCLIENT::RTN_NumIns (RTN rtn)
VOID LEVEL_PINCLIENT::RTN_InsertCall (RTN rtn, IPOINT action, AFUNPTR funptr,...)
ADDRINT LEVEL_PINCLIENT::RTN_Address (RTN rtn)
RTN LEVEL_PINCLIENT::RTN_CreateAt (ADDRINT address, string name)
VOID LEVEL_PINCLIENT::DeleteRtnCheckHistory ()
BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedInsertion (RTN rtn)
BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedInsertionEx (RTN rtn, PROBE_MODE mode)
BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedReplacement (RTN rtn)
BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedReplacementEx (RTN rtn, PROBE_MODE mode)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbed (RTN replacedRtn, AFUNPTR replacementFun,...)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbedEx (RTN replacedRtn, PROBE_MODE mode, AFUNPTR replacementFun,...)
VOID LEVEL_PINCLIENT::RTN_InsertCallProbed (RTN orgRtn, IPOINT action, AFUNPTR funptr,...)
VOID LEVEL_PINCLIENT::RTN_InsertCallProbedEx (RTN orgRtn, IPOINT action, PROBE_MODE mode, AFUNPTR funptr,...)
INT32 LEVEL_PINCLIENT::RTN_CodeRangesProbed (RTN rtn, INT32 num, PIN_CODE_RANGE *buffer)
AFUNPTR LEVEL_PINCLIENT::RTN_Replace (RTN replacedRtn, AFUNPTR replacementFun)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignature (RTN replacedRtn, AFUNPTR replacementFun,...)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceProbed (RTN replacedRtn, AFUNPTR replacementFun)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceProbedEx (RTN replacedRtn, PROBE_MODE mode, 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.
APIs from this group are available in any thread, including any internal thread spawned by the tool.

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


Enumeration Type Documentation

enum LEVEL_PINCLIENT::PROBE_MODE
 

PROBE_MODE enumerator allows user to set probe mode instrumentation other than default for a particular function. Usually, non-default mode is used when Pin can't instrument a routine in a regular way. A non default mode is usually less safe and tool-writer takes responsibility for correctness in this case.

PROBE_MODE_ALLOW_RELOCATION

Doing probed instrumentation Pin inserts a jumper in the first bytes of the instrumented routine. If the first basic block calculated within static discovery is not long enough, Pin can't insert a jumper and the instrumentation request is rejected. One more chance to insert a jumper in such case is to relocate the whole routine. It is not always possible, of course. The routine can be relocated by Pin if

  • the size is known
  • there is no jumps outside function and
  • the routine does not contain indirect jumps

The routine relocation may destabilize the application since ability to propagate exceptions is not preserved. Doing static analysis Pin also does not see additional entry points in the routine code.

In PROBE_MODE_ALLOW_RELOCATION mode Pin tries to keep the instrumented routine in place, and considers relocation when "in-place" instrumentation is impossible. In PROBE_MODE_DEFAULT the relocation is not allowed. Routine relocation is not supported on Windows and IA-64.


Function Documentation

VOID LEVEL_PINCLIENT::DeleteRtnCheckHistory  ) 
 

Clear history of routine check

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
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

ADDRINT LEVEL_PINCLIENT::RTN_Address RTN  rtn  ) 
 

Returns:
Address in memory of rtn
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::RTN_Close RTN  rtn  ) 
 

Close the given rtn. This must be called before opening a new rtn.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

INT32 LEVEL_PINCLIENT::RTN_CodeRangesProbed RTN  rtn,
INT32  num,
PIN_CODE_RANGE buffer
 

Returns all the dynamic code ranges associated with the given RTN. The buffer must be allocated by the tool, and be large enough to contain all code ranges. If num=0, the number of dynamic code ranges is returned.

Parameters:
[in] rtn function that was replaced
[in] num number of elements, or zero.
[out] buffer buffer large enough for all of the code ranges.
Returns:
the number of dynamic code ranges copied into buffer. If num=0,it returns the number of dynamic code ranges associated with the RTN.
PIN_StartProgramProbed() must be used when using this API.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

RTN LEVEL_PINCLIENT::RTN_CreateAt ADDRINT  address,
string  name
 

Create a routine object at given address. In some situations user can calculate address of routine, but Pin doesn't see it because there is no symbol at this point. RTN_CreateAt() allows user to create a routine at a given address and assign a name to it. When it is done, the routine can be searched for by address or by name. The information is kept in Pin as long as the containing image is in memory.

The address should point to code (an executable section or segment). Since the whole code is "covered" by routine objects, the address should fall in one of the existing routines. Pin shortens the routine, which contains the given address, and creates a new routine which starts at the given address and continues till the next routine or the end of the code section. Close any open routine before calling this interface with RTN_Close().

Parameters:
[in] address The start address of the new routine
[in] name The assigned name of the new routine
Returns:
RTN object The routine object is valid if the address fails into code section and there is no another routine object which starts at the same address.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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 is unnecessary (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
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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()
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

string LEVEL_PINCLIENT::RTN_FindNameByAddress ADDRINT  address  ) 
 

Return the name of a function. If more than one name is associated with this address, the first name found is returned.

Parameters:
Address Memory address that corresponds to the RTN
Returns:
Name of routine, or "" if it is not found
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_Funptr RTN  x  ) 
 

an rtn to a funptr

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

INT32 LEVEL_PINCLIENT::RTN_Id RTN  x  ) 
 

Pin assigns each routine a unique ID. The ID is globally unique, i.e. an ID will not appear in two images. If the same routine name exists in two different images (i.e. they are in different addresses), each will have a different ID. If an image is unloaded and then reloaded, the routines within it will most likely have different IDs than before.

Returns:
Unique ID for the routine.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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 NOTE: IPOINT_AFTER is implemented by instrumenting each return instruction in a routine. Pin tries to find all return instructions, but success is not guaranteed
funptr Analysis function to call
... IARG_TYPE. Arguments to pass to funptr
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::RTN_InsertCallProbed RTN  orgRtn,
IPOINT  action,
AFUNPTR  funptr,
  ...
 

Insert a call to an analysis routine relative to a RTN.

Parameters:
orgRtn the application routine to instrument
action use IPOINT_BEFORE or IPOINT_AFTER to call funptr before or after execution.
funptr the analysis function
... IARG_TYPE. If using IPOINT_AFTER, one IARG_TYPE must be IARG_PROTOTYPE. The list must end with IARG_END.
PIN_StartProgramProbed() must be used when using this API.

Use RTN_IsSafeForProbedInsertion() to determine if a function is a suitable candidate for probed function insertion.

Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information. IARG_THREAD_ID is not supported.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

VOID LEVEL_PINCLIENT::RTN_InsertCallProbedEx RTN  orgRtn,
IPOINT  action,
PROBE_MODE  mode,
AFUNPTR  funptr,
  ...
 

Insert a call to an analysis routine relative to a RTN.

Parameters:
orgRtn the application routine to instrument
action use IPOINT_BEFORE or IPOINT_AFTER to call funptr before or after execution.
mode 
funptr the analysis function
... IARG_TYPE. If using IPOINT_AFTER, one IARG_TYPE must be IARG_PROTOTYPE. The list must end with IARG_END.
PIN_StartProgramProbed() must be used when using this API.

Use RTN_IsSafeForProbedInsertionEx() to determine if a function is a suitable candidate for probed function insertion.

Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information. IARG_THREAD_ID is not supported.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

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 INS_Invalid() if no instructions.
Note that Pin find the INSs of the RTN through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN. If you need completely reliable instructions, use normal JIT time instrumentation, where Pin can guarantee that the instructions are correct.

See also:
RTN_InsHeadOnly(), which is provided for performance purposes. If a tool wishes to examine only the first INS of an RTN it should use RTN_InsHeadOnly() instead of RTN_InsHead().
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

INS LEVEL_PINCLIENT::RTN_InsHeadOnly RTN  rtn  ) 
 

You must call RTN_Open() before the first time this is called for an rtn

Returns:
First instruction of rtn, or INS_Invalid() if no instructions.
Note that tools should use this function when they want to examine ONLY the first INS of an RTN, and NO others. The INS_Next() of the INS returned by this function may be INS_Invalid() even if there are more INSs in the RTN. Tools that want to examine further INSs of the RTN should call the RTN_InsHead() function instead of this one.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

INS LEVEL_PINCLIENT::RTN_InsTail RTN  rtn  ) 
 

You must call RTN_Open() before the first time this is called for an rtn

Returns:
Last instruction of rtn, or INS_Invalid() if no instructions
Note that Pin finds the INSs of the RTN through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN. If you need completely reliable instructions, use normal JIT time instrumentation, where Pin can guarantee that the instructions are correct.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_Invalid  ) 
 

Returns:
RTN value that indicates no valid image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedInsertion RTN  rtn  ) 
 

Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise. This API should be called before attempting to insert a call to an analysis function using RTN_InsertCallProbed(). If you want to replace the given RTN with RTN_ReplaceSignatureProbed() or RTN_ReplaceProbed() you should use RTN_IsSafeForProbedReplacement()

Parameters:
rtn the application routine to be replaced.
Returns:
TRUE if the function can be instrumented, FALSE if it cannot.
PIN_StartProgramProbed() must be used when using this API.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedInsertionEx RTN  rtn,
PROBE_MODE  mode
 

Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise. This API should be called before attempting to insert a call to an analysis function using RTN_InsertCallProbedEx(). If you want to replace the given RTN with RTN_ReplaceSignatureProbedEx() or RTN_ReplaceProbedEx() you should use RTN_IsSafeForProbedReplacementEx()

Parameters:
rtn the application routine to be replaced.
mode instrumentation mode, see PROBE_MODE
Returns:
TRUE if the function can be instrumented, FALSE if it cannot.
PIN_StartProgramProbed() must be used when using this API.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedReplacement RTN  rtn  ) 
 

Return TRUE if the given RTN is a candidate for probed function replacement, and FALSE otherwise. This API should be called before attempting to replace a function using RTN_ReplaceSignatureProbed() or RTN_ReplaceProbed(). Note that this routine does not guarantee it is safe to place a probe, it merely indicates that certain conditions are not present.

Parameters:
rtn the application routine to be replaced.
Returns:
TRUE if the function can be replaced, FALSE if it cannot.
PIN_StartProgramProbed() must be used when using this API.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedReplacementEx RTN  rtn,
PROBE_MODE  mode
 

Return TRUE if the given RTN is a candidate for probed function replacement, and FALSE otherwise. This API should be called before attempting to replace a function using RTN_ReplaceSignatureProbedEx(). Note that this routine does not guarantee it is safe to place a probe, it merely indicates that certain conditions are not present.

Parameters:
rtn the application routine to be replaced.
mode instrumentation mode, see PROBE_MODE
Returns:
TRUE if the function can be replaced, FALSE if it cannot.
PIN_StartProgramProbed() must be used when using this API.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

const string& LEVEL_PINCLIENT::RTN_Name RTN  x  ) 
 

Returns:
Name of routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_Next RTN  x  ) 
 

Returns:
Routine that follows x, or RTN_Invalid() if x is the last in the section
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

UINT32 LEVEL_PINCLIENT::RTN_NumIns RTN  rtn  ) 
 

Compute number of static INSs inside RTN.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::RTN_Open RTN  rtn  ) 
 

Open the given rtn. This must be called before RTN_InsHead() or RTN_InsertCall() or RTN_InsHeadOnly()

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_Prev RTN  x  ) 
 

Returns:
Routine that precedes x, or RTN_Invalid() if x is the first in the section
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

USIZE LEVEL_PINCLIENT::RTN_Range RTN  rtn  ) 
 

Returns:
range of routine in bytes (until the beginning of next known symbol).
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_Replace RTN  replacedRtn,
AFUNPTR  replacementFun
 

Replace a routine in the application (replacedRtn) by another function defined in the Pin tool (replacementFun). The replacement function is not instrumented. The signature of the replacement function must be exactly the same as the replaced application routine. However, see RTN_ReplaceSignature(), which allows you to have a different signature.

This API returns a function pointer to the replaced application routine's entry point, which allows the replacement function to call back to the original routine. If you do this, be sure to call the original routine via PIN_CallApplicationFunction(). Directly calling the application's function pointer from the replacement function may result in a crash.

This API works in JIT mode, so you must start the application with PIN_StartProgram().

Parameters:
[in] replacedRtn The application routine to be replaced.
[in] replacementFun The replacement function.
Returns:
A function pointer to the replaced application routine's entry point.
Availability:
Mode: JIT only.
O/S: Linux & Windows
CPU: All.

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 or jump to 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 replaced application routine's entry point. This allows the replacement function to execute the replaced routine.
PIN_StartProgramProbed() must be used when using this API.

Use RTN_IsSafeForProbedReplacement() to determine if a function is a suitable candidate for probed function replacement.

Availability:
Mode: Probe
O/S: Linux & Windows
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceProbedEx RTN  replacedRtn,
PROBE_MODE  mode,
AFUNPTR  replacementFun
 

Replace a routine in the application (replacedRtn) by another function defined in the Pintool (replacementFun) using probes. This API is an analog to RTN_ReplaceProbed.

Parameters:
replacedRtn the application routine to be replaced.
mode instrumentation mode, see PROBE_MODE
replacementFun the replacement function
Returns:
a function pointer to replaced application routine's entry point.
PIN_StartProgramProbedEx() must be used when using this API.

Use RTN_IsSafeForProbedReplacementEx(rtn, mode) to determine if a function is a suitable candidate for probed function replacement.

Availability:
Mode: Probe
O/S: Linux & Windows
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignature RTN  replacedRtn,
AFUNPTR  replacementFun,
  ...
 

Replace a routine in the application (replacedRtn) by another function defined in the Pin tool (replacementFun). The replacement function is not instrumented. The signature of the replacement function can be different from the replaced application routine's signature, which allows the tool to pass more (or fewer) parameters than were passed to the original application routine.

The IARG_ORIG_FUNCPTR argument is especially useful because it allows the replacement function to call back to the original routine. Other useful arguments are IARG_FUNCARG_ENTRYPOINT_VALUE, which allows you to pass a parameter from the original routine to the replacement function, and IARG_PROTOTYPE, which allows you define the prototype of the original routine. The IARG_PROTOTYPE argument is recommended whenever you use IARG_FUNCARG_ENTRYPOINT_VALUE. It is required if the original routine has any parameters that are not simple integral or pointer values.

If your replacement function calls back to the original application routine, be sure to do so via PIN_CallApplicationFunction(). Directly calling the application's function pointer from the replacement function may result in a crash.

This API works in JIT mode, so you must start the application with PIN_StartProgram().

Parameters:
[in] replacedRtn The application routine to be replaced.
[in] replacementFun The replacement function.
[in] ... Any additional arguments define parameters that are passed to the replacement function, see IARG_TYPE. This list must end with IARG_END.
Returns:
A function pointer to the replaced application routine's entry point. The replacement function can use this pointer to call back to the original application routine, or it can use IARG_ORIG_FUNCPTR for this purpose.
Availability:
Mode: JIT only.
O/S: Linux & Windows
CPU: All.

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbed RTN  replacedRtn,
AFUNPTR  replacementFun,
  ...
 

Replace a routine in the application (orgRtn) by another function defined in the Pintool (replacementFunptr) using probes. The replacement function is not instrumented. Replacement functions typically need to call the replaced routines. However, calls to RTN_Funptr(orgRtn) will be redirected to replacementFunptr. Replacement functions must instead call the returned function pointer, which is a copy of the entry point that is not redirected. The replacement function signature does not have to be the same as the replaced function. In fact while the replaced function may have the CALLINGSTD_REGPARMS calling convention, the replacement function calling convention must not be PIN_FAST_ANALYSIS_CALL (i.e. the replaced function may have register parameters, the replacement function must not). The replacement function arguments must be passed to the replacement function using the Pin IARG_TYPEs, in the same way as RTN_InsertCall(). A prototype of the routine in the application must also be passed in as an argument. See PROTO_Allocate for more information.

Parameters:
orgRtn the application routine to be replaced.
replacementFunptr the replacement function
... IARG_TYPE. One IARG_TYPE must be IARG_PROTOTYPE, and the list must end with IARG_END.
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.

Use RTN_IsSafeForProbeReplacement() to determine if a function is a suitable candidate for probed function replacement.

Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information. IARG_THREAD_ID is not supported.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbedEx RTN  replacedRtn,
PROBE_MODE  mode,
AFUNPTR  replacementFun,
  ...
 

Replace a routine in the application (orgRtn) by another function defined in the Pintool (replacementFunptr) using probes.

Parameters:
replacedRtn the application routine to be replaced.
mode instrumentation mode, see PROBE_MODE
replacementFun the replacement function
... IARG_TYPE. One IARG_TYPE must be IARG_PROTOTYPE, and the list must end with IARG_END.
Returns:
a function pointer to the relocated application function entry point. This allows the replacement routine to execute the replaced routine.
Use RTN_IsSafeForProbeReplacementEx() to determine if a function is a suitable candidate for probed function replacement.

Availability:
Mode: Probe
O/S: Linux, Windows
CPU: All

SEC LEVEL_PINCLIENT::RTN_Sec RTN  x  ) 
 

Returns:
Section that contains this routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

USIZE LEVEL_PINCLIENT::RTN_Size RTN  rtn  ) 
 

Returns:
size of routine in bytes
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

SYM LEVEL_PINCLIENT::RTN_Sym RTN  x  ) 
 

Returns:
SYM associated with the given routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All


Generated on Tue Nov 22 12:28:40 2011 for Pin by  doxygen 1.4.6