Typedefs
typedef VOID(*	RTN_INSTRUMENT_CALLBACK) (RTN rtn, VOID *v)

Enumerations
enum	PROBE_MODE { PROBE_MODE_DEFAULT = 0 , PROBE_MODE_ALLOW_RELOCATION = (1 << 0) , PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET = (1 << 1) }

Functions
SEC	RTN_Sec (RTN rtn)

RTN	RTN_Next (RTN rtn)

RTN	RTN_Prev (RTN rtn)

RTN	RTN_Invalid ()

BOOL	RTN_Valid (RTN rtn)

const std::string &	RTN_Name (RTN rtn)

BOOL	RTN_IsArtificial (RTN rtn)

SYM	RTN_Sym (RTN rtn)

UINT	RTN_DynamicMethodId (RTN rtn)

AFUNPTR	RTN_Funptr (RTN rtn)

UINT32	RTN_Id (RTN rtn)

PIN_CALLBACK	RTN_AddInstrumentFunction (RTN_INSTRUMENT_CALLBACK fun, VOID *val)

USIZE	RTN_Range (RTN rtn)

USIZE	RTN_Size (RTN rtn)

RTN	RTN_IFuncResolver (RTN rtn)

RTN	RTN_IFuncImplementation (RTN rtn)

std::string	RTN_FindNameByAddress (ADDRINT address)

RTN	RTN_FindByAddress (ADDRINT address)

RTN	RTN_FindByName (IMG img, const CHAR *name)

VOID	RTN_Open (RTN rtn)

VOID	RTN_Close (RTN rtn)

INS	RTN_InsHead (RTN rtn)

INS	RTN_InsHeadOnly (RTN rtn)

INS	RTN_InsTail (RTN rtn)

UINT32	RTN_NumIns (RTN rtn)

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

ADDRINT	RTN_Address (RTN rtn)

RTN	RTN_CreateAt (ADDRINT address, std::string name)

BOOL	RTN_IsDynamic (RTN rtn)

BOOL	RTN_IsSafeForProbedInsertion (RTN rtn)

BOOL	RTN_IsSafeForProbedInsertionEx (RTN rtn, PROBE_MODE mode)

BOOL	RTN_IsSafeForProbedReplacement (RTN rtn)

BOOL	RTN_IsSafeForProbedReplacementEx (RTN rtn, PROBE_MODE mode)

AFUNPTR	RTN_ReplaceSignatureProbed (RTN replacedRtn, AFUNPTR replacementFun,...)

AFUNPTR	RTN_ReplaceSignatureProbedEx (RTN replacedRtn, PROBE_MODE mode, AFUNPTR replacementFun,...)

BOOL	RTN_InsertCallProbed (RTN orgRtn, IPOINT action, AFUNPTR funptr,...)

BOOL	RTN_InsertCallProbedEx (RTN orgRtn, IPOINT action, PROBE_MODE mode, AFUNPTR funptr,...)

AFUNPTR	RTN_Replace (RTN replacedRtn, AFUNPTR replacementFun)

AFUNPTR	RTN_ReplaceSignature (RTN replacedRtn, AFUNPTR replacementFun,...)

AFUNPTR	RTN_ReplaceProbed (RTN replacedRtn, AFUNPTR replacementFun)

AFUNPTR	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

◆ RTN_INSTRUMENT_CALLBACK

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

Call back function used to instrument routines

Enumeration Type Documentation

◆ PROBE_MODE

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

PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET

In PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET mode Pin will allow inserting a probe on top of what might be a potential branch target.
A potential branch target are bytes that come after an unconditional branch.
If Pin can identify direct jumps to those bytes then it is considered a branch target and instrumentation is rejected.
Otherwise they are considered a potential branch target.
It is possible, by using PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET mode, to place a probe on those bytes.
However please be advised that if there is a branch to this address somewhere in the application then the application will crash as the bytes of the original instruction in this address have changed.

Please note it is possible to combine two enum values in the call, i.e. (PROBE_MODE_ALLOW_RELOCATION | PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET)

Function Documentation

◆ RTN_AddInstrumentFunction()

PIN_CALLBACK RTN_AddInstrumentFunction	(	RTN_INSTRUMENT_CALLBACK	fun,
		VOID *	val
	)

extern

Adds a function used to instrument at routine granularity.

Parameters

[in]	fun	Instrumentation function for routines
[in]	val	Passed as the second argument to the instrumentation function

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: All

◆ RTN_Address()

ADDRINT RTN_Address ( RTN rtn )

extern

Returns the address in memory of the RTN.

Parameters

[in] rtn The routine object

Returns: Address in memory of rtn

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

◆ RTN_Close()

VOID RTN_Close ( RTN rtn )

extern

Closes the given RTN.

This must be called before opening a new RTN.

Parameters

[in] rtn The routine object to close

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

◆ RTN_CreateAt()

RTN RTN_CreateAt	(	ADDRINT	address,
		std::string	name
	)

extern

Creates 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
[in]	isIFunc	True if the symbol's type which corresponds to the new routine location is ifunc symbol.

Returns: RTN object The routine object is valid if the address fails into code section.

Note: The pin client lock is obtained during the call of this API.; If there is another routine object which starts at the same address this function replaces its name.

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

◆ RTN_DynamicMethodId()

UINT RTN_DynamicMethodId ( RTN rtn )

extern

Returns the method ID associated with the given routine (JIT Profiling).

Parameters

[in] rtn The routine object

Returns: Method ID associated with the given routine (JIT Profiling)

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

◆ RTN_FindByAddress()

RTN RTN_FindByAddress ( ADDRINT address )

extern

Finds the routine that contains the given memory address.

Parameters

[in] address Memory address that corresponds to an RTN

Returns: Handle to the RTN found. If not found returns RTN_Invalid()

Note: If a valid RTN handle is returned then it means that the given address was within the RTN range. To verify that the given address is the start of the RTN, you can compare it with the address returned by RTN_Address.; In a multithreaded program, the returned RTN handle could go stale if another thread unloads 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; The pin client lock must be obtained before calling this API from outside an instrumentation callback.

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

◆ RTN_FindByName()

RTN RTN_FindByName	(	IMG	img,
		const CHAR *	name
	)

extern

Finds a routine in an image by name.

This API will also go over mangled names and demangle them for comparison.

Parameters

[in]	img	Image in which to search for RTN
[in]	name	Name of the RTN to search in IMG

Returns: Handle to the RTN found. If not found returns RTN_Invalid()

Note: If more than one RTN matches the name, the first one found will be returned. This can happen for overloaded functions. To find the exact overload, the correct mangled name should be passed.; Because this function will iterate over all RTNs in the image, and will demangle each name if the given name is not an exact match, it may have severe performance implications. For finding several RTNs per image or for matching all overloads, it is recommended that the caller iterates over the RTNs manually and decides on the search criteria themselves. See PIN_UndecorateSymbolName for information about name demangling.; This function internally uses SYM APIs. So PIN_InitSymbols should be called for this API to work.; The pin client lock must be obtained before calling this API from outside an instrumentation callback.; In case this function is an Ifunc the return value will be the RTN that holds the implementation of that ifunc (Notice! this RTN can be on another image. If the resolver function is needed use RTN_IFuncResolver().

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

◆ RTN_FindNameByAddress()

std::string RTN_FindNameByAddress ( ADDRINT address )

extern

Returns the name of a routine containing the given address.

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

See RTN_FindByAddress for more information.

Parameters

[in] address Memory address that corresponds to the RTN

Returns: Name of routine, or "" if it is not found

Note: The pin client lock is obtained during the call of this API.

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

◆ RTN_Funptr()

AFUNPTR RTN_Funptr ( RTN rtn )

extern

Converts an RTN to a function pointer.

Parameters

[in] rtn The routine object

Returns: function pointer

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

◆ RTN_Id()

UINT32 RTN_Id ( RTN rtn )

extern

Returns a unique ID for the routine.

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.

Parameters

[in] rtn The routine object

Returns: Unique ID for the routine.

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

◆ RTN_IFuncImplementation()

RTN RTN_IFuncImplementation ( RTN rtn )

extern

Returns the implementation function that this ifunc points to.

Parameters

[in] rtn The routine object

Returns: The implementation function that this ifunc points to

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

◆ RTN_IFuncResolver()

RTN RTN_IFuncResolver ( RTN rtn )

extern

Returns the resolver function that led to this implementation (ifunc).

Parameters

[in] rtn The routine object

Returns: The resolver function that led to this implementation (ifunc)

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

◆ RTN_InsertCall()

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

extern

Inserts a call relative to an RTN.

Parameters

[in]	rtn	Routine to instrument
[in]	action	Use IPOINT_BEFORE to call funptr before execution, or IPOINT_AFTER for immediately before the return
[in]	funptr	Analysis function to call
[in]	...	IARG_TYPE. Arguments to pass to funptr

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; Pin does not support calling this function from either the TRACE or INS InstrumentationFunction callback

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

◆ RTN_InsertCallProbed()

BOOL RTN_InsertCallProbed	(	RTN	orgRtn,
		IPOINT	action,
		AFUNPTR	funptr,
			...
	)

extern

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 of the original application function. The list must end with IARG_END.

Returns: TRUE if the probe was successfully inserted

PIN_StartProgramProbed() must be used when using this API.

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

Availability:: Mode: Probe
O/S: All
CPU: All

◆ RTN_InsertCallProbedEx()

BOOL RTN_InsertCallProbedEx	(	RTN	orgRtn,
		IPOINT	action,
		PROBE_MODE	mode,
		AFUNPTR	funptr,
			...
	)

extern

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 of the original application function. The list must end with IARG_END.

Returns: TRUE if the probe was successfully inserted

PIN_StartProgramProbed() must be used when using this API.

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

Availability:: Mode: Probe
O/S: All
CPU: All

◆ RTN_InsHead()

INS RTN_InsHead ( RTN rtn )

extern

Returns the first instruction of the RTN, or INS_Invalid() if no instructions.

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

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: Routine Object it should use RTN_InsHeadOnly() instead of RTN_InsHead().

Parameters

[in] rtn The routine object

Returns: First instruction of rtn, or INS_Invalid() if no instructions.

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

◆ RTN_InsHeadOnly()

INS RTN_InsHeadOnly ( RTN rtn )

extern

Returns the first instruction of the RTN, or INS_Invalid() if no instructions.

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

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.

Parameters

[in] rtn The routine object

Returns: First instruction of rtn, or INS_Invalid() if no instructions.

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

◆ RTN_InsTail()

INS RTN_InsTail ( RTN rtn )

extern

Returns the last instruction of the RTN, or INS_Invalid() if no instructions.

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

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.

Parameters

[in] rtn The routine object

Returns: Last instruction of rtn, or INS_Invalid() if no instructions

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

◆ RTN_Invalid()

RTN RTN_Invalid ( )

extern

Returns an RTN value that indicates no valid image.

Returns: RTN value that indicates no valid image

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

◆ RTN_IsArtificial()

BOOL RTN_IsArtificial ( RTN rtn )

extern

Checks if the RTN is artificial.

An artificial RTN is an RTN which was introduced by PIN for internal management and does not really represent an actual routine in the application. For example, PIN might cover code pieces that are not associated with symbols with artificial RTNs in order to meet the requirement that all code must be covered with RTNs.

Parameters

[in] rtn The routine object

Returns: TRUE if RTN is artificial.

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

◆ RTN_IsDynamic()

BOOL RTN_IsDynamic ( RTN rtn )

extern

Checks if the routine is dynamically created.

A routine can be marked as dynamically created using Jit Profiling API only.

Parameters

[in] rtn The routine object

Returns: TRUE if the routine is dynamically created

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

◆ RTN_IsSafeForProbedInsertion()

BOOL RTN_IsSafeForProbedInsertion ( RTN rtn )

extern

Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise.
This API is expected to be deprecated in future Pin versions. It is recommended to evaluate the return value of RTN_InsertCallProbed() instead. If you want to replace the given RTN with RTN_ReplaceSignatureProbed() or RTN_ReplaceProbed(), please refer to 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

◆ RTN_IsSafeForProbedInsertionEx()

BOOL RTN_IsSafeForProbedInsertionEx	(	RTN	rtn,
		PROBE_MODE	mode
	)

extern

Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise.
This API is expected to be deprecated in future Pin versions. It is recommended to evaluate the return value of RTN_InsertCallProbedEx() instead. If you want to replace the given RTN with RTN_ReplaceSignatureProbedEx() or RTN_ReplaceProbedEx(), please refer to 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

◆ RTN_IsSafeForProbedReplacement()

BOOL RTN_IsSafeForProbedReplacement ( RTN rtn )

extern

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

◆ RTN_IsSafeForProbedReplacementEx()

BOOL RTN_IsSafeForProbedReplacementEx	(	RTN	rtn,
		PROBE_MODE	mode
	)

extern

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

◆ RTN_Name()

const std::string & RTN_Name ( RTN rtn )

extern

Returns the name of the routine.

Parameters

[in] rtn The routine object

Returns: Name of routine

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

◆ RTN_Next()

RTN RTN_Next ( RTN rtn )

extern

Returns the routine that follows this routine, or RTN_Invalid() if it is the last.

Parameters

[in] rtn The routine object

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

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

◆ RTN_NumIns()

UINT32 RTN_NumIns ( RTN rtn )

extern

Computes the number of static INSs inside the RTN.

Parameters

[in] rtn The routine object

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

◆ RTN_Open()

VOID RTN_Open ( RTN rtn )

extern

Opens the given RTN.

This must be called before RTN_InsHead() or RTN_InsertCall() or RTN_InsHeadOnly()

Parameters

[in] rtn The routine object to open

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

◆ RTN_Prev()

RTN RTN_Prev ( RTN rtn )

extern

Returns the routine that precedes this routine, or RTN_Invalid() if it is the first.

Parameters

[in] rtn The routine object

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

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

◆ RTN_Range()

USIZE RTN_Range ( RTN rtn )

extern

Returns the range of routine in bytes.

(until the next known symbol or end of current code region).

Parameters

[in] rtn The routine object

Returns: range of routine in bytes

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

◆ RTN_Replace()

AFUNPTR RTN_Replace	(	RTN	replacedRtn,
		AFUNPTR	replacementFun
	)

extern

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.

Note: The pin client lock is obtained during the call of this API.

Availability:: Mode: JIT only.
O/S: Linux & Windows
CPU: All.
NOTE: Pin does not support calling this function from either the TRACE or INS InstrumentationFunction callback

◆ RTN_ReplaceProbed()

AFUNPTR RTN_ReplaceProbed	(	RTN	replacedRtn,
		AFUNPTR	replacementFun
	)

extern

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. If the replacement failed the function returns NULL.

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.

Note: This API assumes that the application stack (which is used by replacementFun) is aligned according to calling conventions when calling to replacement function, but that is not always guaranteed in Linux 32-bit. In case the stack is not aligned as expected then it may result in segmentation fault. To avoid this, add 'force_align_arg_pointer' function attribute to replacementFun or use RTN_ReplaceSignatureProbed() instead.; The pin client lock is obtained during the call of this API.

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

◆ RTN_ReplaceProbedEx()

AFUNPTR RTN_ReplaceProbedEx	(	RTN	replacedRtn,
		PROBE_MODE	mode,
		AFUNPTR	replacementFun
	)

extern

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. If the replacement failed the function returns NULL.

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

◆ RTN_ReplaceSignature()

AFUNPTR RTN_ReplaceSignature	(	RTN	replacedRtn,
		AFUNPTR	replacementFun,
			...
	)

extern

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.

Note: The pin client lock is obtained during the call of this API.

Availability:: Mode: JIT only.
O/S: Linux & Windows
CPU: All.
NOTE: Pin does not support calling this function from either the TRACE or INS InstrumentationFunction callback

◆ RTN_ReplaceSignatureProbed()

AFUNPTR RTN_ReplaceSignatureProbed	(	RTN	replacedRtn,
		AFUNPTR	replacementFun,
			...
	)

extern

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 of the original application function, 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. If the replacement failed the function returns NULL.

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.

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

◆ RTN_ReplaceSignatureProbedEx()

AFUNPTR RTN_ReplaceSignatureProbedEx	(	RTN	replacedRtn,
		PROBE_MODE	mode,
		AFUNPTR	replacementFun,
			...
	)

extern

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 of the original application function, 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. If the replacement failed the function returns NULL.

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

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

◆ RTN_Sec()

SEC RTN_Sec ( RTN rtn )

extern

Returns the section that contains this routine.

Parameters

[in] rtn The routine object

Returns: Section that contains this routine

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

◆ RTN_Size()

USIZE RTN_Size ( RTN rtn )

extern

Returns the size of routine in bytes.

Parameters

[in] rtn The routine object

Returns: size of routine in bytes

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

◆ RTN_Sym()

SYM RTN_Sym ( RTN rtn )

extern

Returns the SYM associated with the given routine.

Parameters

[in] rtn The routine object

Returns: SYM associated with the given routine

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

◆ RTN_Valid()

BOOL RTN_Valid ( RTN rtn )

extern

Checks if the RTN is valid.

RTN_Valid() returns FALSE in certain cases when there is no static image of the code available, including dynamically generated code.

Parameters

[in] rtn The routine object to check

Returns: True if rtn is not RTN_Invalid().

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

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ RTN_INSTRUMENT_CALLBACK

Enumeration Type Documentation

◆ PROBE_MODE

Function Documentation

◆ RTN_AddInstrumentFunction()

◆ RTN_Address()

◆ RTN_Close()

◆ RTN_CreateAt()

◆ RTN_DynamicMethodId()

◆ RTN_FindByAddress()

◆ RTN_FindByName()

◆ RTN_FindNameByAddress()

◆ RTN_Funptr()

◆ RTN_Id()

◆ RTN_IFuncImplementation()

◆ RTN_IFuncResolver()

◆ RTN_InsertCall()

◆ RTN_InsertCallProbed()

◆ RTN_InsertCallProbedEx()

◆ RTN_InsHead()

◆ RTN_InsHeadOnly()

◆ RTN_InsTail()

◆ RTN_Invalid()

◆ RTN_IsArtificial()

◆ RTN_IsDynamic()

◆ RTN_IsSafeForProbedInsertion()

◆ RTN_IsSafeForProbedInsertionEx()

◆ RTN_IsSafeForProbedReplacement()

◆ RTN_IsSafeForProbedReplacementEx()

◆ RTN_Name()

◆ RTN_Next()

◆ RTN_NumIns()

◆ RTN_Open()

◆ RTN_Prev()

◆ RTN_Range()

◆ RTN_Replace()

◆ RTN_ReplaceProbed()

◆ RTN_ReplaceProbedEx()

◆ RTN_ReplaceSignature()

◆ RTN_ReplaceSignatureProbed()

◆ RTN_ReplaceSignatureProbedEx()

◆ RTN_Sec()

◆ RTN_Size()

◆ RTN_Sym()

◆ RTN_Valid()