Typedefs
typedef VOID(*	LEVEL_PINCLIENT::IMAGECALLBACK) (IMG, VOID *)

Enumerations
enum	LEVEL_CORE::IMG_TYPE { IMG_TYPE_INVALID, LEVEL_CORE::IMG_TYPE_STATIC, LEVEL_CORE::IMG_TYPE_SHARED, LEVEL_CORE::IMG_TYPE_SHAREDLIB, LEVEL_CORE::IMG_TYPE_RELOCATABLE, LEVEL_CORE::IMG_TYPE_DYNAMIC_CODE, LEVEL_CORE::IMG_TYPE_API_CREATED, IMG_TYPE_LAST }

enum	LEVEL_CORE::IMG_PROPERTY { IMG_PROPERTY_INVALID, LEVEL_CORE::IMG_PROPERTY_SHSTK_ENABLED, LEVEL_CORE::IMG_PROPERTY_IBT_ENABLED, IMG_PROPERTY_LAST }

Functions
IMG	LEVEL_PINCLIENT::IMG_Next (IMG img)

IMG	LEVEL_PINCLIENT::IMG_Prev (IMG img)

IMG	LEVEL_PINCLIENT::IMG_Invalid ()

BOOL	LEVEL_PINCLIENT::IMG_Valid (IMG img)

SEC	LEVEL_PINCLIENT::IMG_SecHead (IMG img)

SEC	LEVEL_PINCLIENT::IMG_SecTail (IMG img)

SYM	LEVEL_PINCLIENT::IMG_RegsymHead (IMG img)

ADDRINT	LEVEL_PINCLIENT::IMG_EntryAddress (IMG img)

BOOL	LEVEL_PINCLIENT::IMG_HasProperty (IMG img, IMG_PROPERTY property)

const std::string &	LEVEL_PINCLIENT::IMG_Name (IMG img)

ADDRINT	LEVEL_PINCLIENT::IMG_Gp (IMG img)

ADDRINT	LEVEL_PINCLIENT::IMG_LoadOffset (IMG img)

ADDRINT	LEVEL_PINCLIENT::IMG_LowAddress (IMG img)

ADDRINT	LEVEL_PINCLIENT::IMG_HighAddress (IMG img)

ADDRINT	LEVEL_PINCLIENT::IMG_StartAddress (IMG img)

USIZE	LEVEL_PINCLIENT::IMG_SizeMapped (IMG img)

IMG_TYPE	LEVEL_PINCLIENT::IMG_Type (IMG img)

BOOL	LEVEL_PINCLIENT::IMG_IsMainExecutable (IMG x)

BOOL	LEVEL_PINCLIENT::IMG_hasLinesData (IMG x)

BOOL	LEVEL_PINCLIENT::IMG_IsInterpreter (IMG x)

BOOL	LEVEL_PINCLIENT::IMG_IsStaticExecutable (IMG x)

BOOL	LEVEL_PINCLIENT::IMG_IsVDSO (IMG img)

UINT32	LEVEL_PINCLIENT::IMG_NumRegions (IMG img)

ADDRINT	LEVEL_PINCLIENT::IMG_RegionHighAddress (IMG img, UINT32 n)

ADDRINT	LEVEL_PINCLIENT::IMG_RegionLowAddress (IMG img, UINT32 n)

UINT32	LEVEL_PINCLIENT::IMG_Id (IMG x)

VOID *	LEVEL_PINCLIENT::IMG_DynamicRawData (IMG img)

IMG	LEVEL_PINCLIENT::IMG_FindImgById (UINT32 id)

IMG	LEVEL_PINCLIENT::IMG_FindByAddress (ADDRINT address)

PIN_CALLBACK	LEVEL_PINCLIENT::IMG_AddInstrumentFunction (IMAGECALLBACK fun, VOID *v)

PIN_CALLBACK	LEVEL_PINCLIENT::IMG_AddUnloadFunction (IMAGECALLBACK fun, VOID *v)

IMG	LEVEL_PINCLIENT::IMG_Open (const std::string &filename)

VOID	LEVEL_PINCLIENT::IMG_Close (IMG img)

IMG	LEVEL_PINCLIENT::APP_ImgHead ()

IMG	LEVEL_PINCLIENT::APP_ImgTail ()

Detailed Description

Example tools:

Detecting the Loading and Unloading of Images (Image Instrumentation)

Iteration idioms:

// Visit every loaded image

for( IMG img= APP_ImgHead(); IMG_Valid(img); img = IMG_Next(img) )

Typedef Documentation

◆ IMAGECALLBACK

typedef VOID(* LEVEL_PINCLIENT::IMAGECALLBACK) (IMG, VOID *)

Type of function to be called when an image is loaded

Enumeration Type Documentation

◆ IMG_PROPERTY

enum LEVEL_CORE::IMG_PROPERTY

Properties available for an image. Typically defined as meta data within the image. May define some specific hardware that is used or needed or some features enabled by the image. Property may be OS/CPU specific.

Enumerator
IMG_PROPERTY_SHSTK_ENABLED	CET shadow stack enabled. Supported only for Linux
IMG_PROPERTY_IBT_ENABLED	CET indirect branch tracking enabled. Supported only for Linux

◆ IMG_TYPE

enum LEVEL_CORE::IMG_TYPE

Enumerator
IMG_TYPE_STATIC	Main image, linked with -static.
IMG_TYPE_SHARED	Main image, linked against shared libraries.
IMG_TYPE_SHAREDLIB	Shared library or main image linked with -pie.
IMG_TYPE_RELOCATABLE	Relocatble object (.o file)
IMG_TYPE_DYNAMIC_CODE	Dynamically created code.
IMG_TYPE_API_CREATED	Artificial image created by IMG_CreateAt ()

Function Documentation

◆ APP_ImgHead()

IMG LEVEL_PINCLIENT::APP_ImgHead ( )

Returns: The first image loaded into memory

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

◆ APP_ImgTail()

IMG LEVEL_PINCLIENT::APP_ImgTail ( )

Returns: The last image loaded into memory

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

◆ IMG_AddInstrumentFunction()

PIN_CALLBACK LEVEL_PINCLIENT::IMG_AddInstrumentFunction	(	IMAGECALLBACK	fun,
		VOID *	v
	)

Use this to register a call back to catch the loading of an image

Parameters

fun	Instrumentation function for images, it is passed an image and v
v	the value of to pass to fun when an image is loaded

Returns: PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties

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

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

◆ IMG_AddUnloadFunction()

PIN_CALLBACK LEVEL_PINCLIENT::IMG_AddUnloadFunction	(	IMAGECALLBACK	fun,
		VOID *	v
	)

Register fun as a call back to be used when an image is unloaded. This is not an instrumentation function–it doesn't make sense to instrument a function when it removed from memory.

Parameters

fun	passed an image and v when an image is unloaded
v	the value to pass to fun when an image is unloaded

Returns: PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties

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

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

◆ IMG_Close()

VOID LEVEL_PINCLIENT::IMG_Close ( IMG img )

Close the open image.

Parameters

[in] img The IMG that was previously opened.

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

◆ IMG_DynamicRawData()

VOID* LEVEL_PINCLIENT::IMG_DynamicRawData ( IMG img )

Returns the pointer to the object that was passed by the application for reporting the creation of a dynamic image via the Jit Profiling API. The pointer is available only for dynamic images, and only during the image load and routine instrumentation callbacks. In all other cases, the function returns NULL.

Parameters

[in] img The Pin image handle.

Returns: pointer to the object, or NULL.

Availability:: Mode: JIT
O/S: Linux*
CPU: All

◆ IMG_EntryAddress()

ADDRINT LEVEL_PINCLIENT::IMG_EntryAddress ( IMG img )

Parameters

[in] img Pin image handle

Returns: Address of first instruction executed when image is loaded

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

◆ IMG_FindByAddress()

IMG LEVEL_PINCLIENT::IMG_FindByAddress ( ADDRINT address )

Find image by address. For each image, check if the address is within the mapped memory region of one of its segments.

Returns: IMG object, valid or invalid

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

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

◆ IMG_FindImgById()

IMG LEVEL_PINCLIENT::IMG_FindImgById ( UINT32 id )

Find image by Id

Returns: IMG object, valid or invalid

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

◆ IMG_Gp()

ADDRINT LEVEL_PINCLIENT::IMG_Gp ( IMG img )

Returns: Global pointer (GP) of image, if a GP is used to address global data

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

◆ IMG_hasLinesData()

BOOL LEVEL_PINCLIENT::IMG_hasLinesData ( IMG x )

Returns: TRUE if img has debug information that includes the lines information.

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

◆ IMG_HasProperty()

BOOL LEVEL_PINCLIENT::IMG_HasProperty	(	IMG	img,
		IMG_PROPERTY	property
	)

Checks if image has the specificfied property

Parameters

[in]	img	Pin image handle
[in]	property	the property to check of type IMG_PROPERTY

Returns: if image supports specific property in specific mode

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

◆ IMG_HighAddress()

ADDRINT LEVEL_PINCLIENT::IMG_HighAddress ( IMG img )

Tells the highest address of any code or data loaded by the image. This is the address of the last byte loaded by the image.

Remarks: If the image is split in memory, regions from other images might be mapped between its regions. In this case, the function will return the high address of the text segment. See IMG_NumRegions.

Parameters

[in] img The Pin image handle.

Returns: The image's highest address or the text segment high address if the image is split.

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

◆ IMG_Id()

UINT32 LEVEL_PINCLIENT::IMG_Id ( IMG x )

Returns a unique ID for the image. If an image is unloaded, the ID is not reused for a different image. If an image is unloaded and the same one is loaded back, the ID is different.

Returns: Unique ID for the image.

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

◆ IMG_Invalid()

IMG LEVEL_PINCLIENT::IMG_Invalid ( )

Returns: Used to indicate no image

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

◆ IMG_IsInterpreter()

BOOL LEVEL_PINCLIENT::IMG_IsInterpreter ( IMG x )

On operating systems that have the concept of loader image. (i.e. another program that is resposible to load the application), this function return TRUE for the image of the loader. In operating system that don't have the concept of loader, this function returns FALSE on all images.

Parameters

[in] img The Pin image handle.

Returns: TRUE if this is the image of the application's loader (interpreter).

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

◆ IMG_IsMainExecutable()

BOOL LEVEL_PINCLIENT::IMG_IsMainExecutable ( IMG x )

Returns: TRUE for the image Pin was applied on in the command line (i.e. first param after –)

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

◆ IMG_IsStaticExecutable()

BOOL LEVEL_PINCLIENT::IMG_IsStaticExecutable ( IMG x )

Returns: TRUE if this is the static executable

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

◆ IMG_IsVDSO()

BOOL LEVEL_PINCLIENT::IMG_IsVDSO ( IMG img )

On Linux this function return TRUE for the image of the VDSO. On other operating systems return FALSE for all images.

Parameters

[in] img The Pin image handle.

Returns: TRUE if this is the VDSO image.

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

◆ IMG_LoadOffset()

ADDRINT LEVEL_PINCLIENT::IMG_LoadOffset ( IMG img )

Returns: Offset from the image's link-time address to its load-time address.

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

◆ IMG_LowAddress()

ADDRINT LEVEL_PINCLIENT::IMG_LowAddress ( IMG img )

Tells the lowest address of any code or data loaded by the image.

Remarks: If the image is split in memory, regions from other images might be mapped between its regions. In this case, the function will return the low address of the text segment. See IMG_NumRegions.

Parameters

[in] img The Pin image handle.

Returns: The image's lowest address or the text segment low address if the image is split.

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

◆ IMG_Name()

const std::string& LEVEL_PINCLIENT::IMG_Name ( IMG img )

Returns: Fully qualified actual file name of image. Image names are encoded in UTF8 (a superset of ASCII), this is supported for Linux (only for locales encoded in UTF8) and Windows

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

◆ IMG_Next()

IMG LEVEL_PINCLIENT::IMG_Next ( IMG img )

Returns: Of the list of currently loaded images in memory it returns the image loaded after image x, or IMG_Invalid() if x is the last image

Skip shadow image (vdso or dynamic code)

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

◆ IMG_NumRegions()

UINT32 LEVEL_PINCLIENT::IMG_NumRegions ( IMG img )

Returns: number of consecutive regions of the image in memory

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

◆ IMG_Open()

IMG LEVEL_PINCLIENT::IMG_Open ( const std::string & filename )

Allows one to open an image and browse it statically. There can only be one image open at a time. File names are encoded in UTF8 (a superset of ASCII).

Note: This API can only be used at a safe point, which is before calling PIN_StartProgram()(/or similar)

Parameters

[in] filename The image file name.

Returns: The opened image, or IMG_INVALID() if the image cannot be opened.

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

◆ IMG_Prev()

IMG LEVEL_PINCLIENT::IMG_Prev ( IMG img )

Returns: Of the list of currently loaded images in memory it returns the image loaded prior to image x, or IMG_Invalid() if x is the first image

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

◆ IMG_RegionHighAddress()

ADDRINT LEVEL_PINCLIENT::IMG_RegionHighAddress	(	IMG	img,
		UINT32	n
	)

Returns: the high address of the n'th region

Remarks: n starts at 0

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

◆ IMG_RegionLowAddress()

ADDRINT LEVEL_PINCLIENT::IMG_RegionLowAddress	(	IMG	img,
		UINT32	n
	)

Returns: the low address of the n'th region

Remarks: n starts at 0

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

◆ IMG_RegsymHead()

SYM LEVEL_PINCLIENT::IMG_RegsymHead ( IMG img )

Returns: First regular symbol in image

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

◆ IMG_SecHead()

SEC LEVEL_PINCLIENT::IMG_SecHead ( IMG img )

Returns: First section in image

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

◆ IMG_SecTail()

SEC LEVEL_PINCLIENT::IMG_SecTail ( IMG img )

Returns: Last section in image

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

◆ IMG_SizeMapped()

USIZE LEVEL_PINCLIENT::IMG_SizeMapped ( IMG img )

Tells the size of the raw image mapped by Pin, including the size of the image's symbolic information, which is not normally mapped by the application. Use this with IMG_StartAddress() to find the entire memory range of the raw image mapped by Pin.

Note, this does not give the address range of the image from the application's perspective. To get that, use IMG_LowAddress() and IMG_HighAddress().

On Linux, the file is mapped in image-load callback or after IMG_Open. In other cases the IMG_SizeMapped returns 0.

Parameters

[in] img The Pin image handle.

Returns: Size (bytes) of the raw image file mapped by Pin.

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

◆ IMG_StartAddress()

ADDRINT LEVEL_PINCLIENT::IMG_StartAddress ( IMG img )

On Windows, the whole image has been loaded by system loader at once. IMG_StartAddress() gives the pointer to the image, mapped by loader. If you are working inside image-load callback - IMG_LowAddress() and IMG_StartAddress() return the same value.

On Unix, the loader maps only portions of the image file that contain code and data. Additionally, Pin maps the whole image file for parsing. IMG_StartAddress() returns a pointer to the memory mapped file. After return form image-load callback the whole image file is being unmapped and the pointer becomes invalid. The IMG_StartAddress() returns 0.

Note, On Unix, the IMG_LowAddress() and IMG_StartAddress() return different values.

On IMG_Open(), Pin maps the whole image into memory and the pointer is valid until IMG_Close()

Parameters

[in] img The Pin image handle.

Returns: Pointer to the start of the raw image file.

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

◆ IMG_Type()

IMG_TYPE LEVEL_PINCLIENT::IMG_Type ( IMG img )

Returns: Image type

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

◆ IMG_Valid()

BOOL LEVEL_PINCLIENT::IMG_Valid ( IMG img )

Returns: True if x is not IMG_Invalid()

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

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ IMAGECALLBACK

Enumeration Type Documentation

◆ IMG_PROPERTY

◆ IMG_TYPE

Function Documentation

◆ APP_ImgHead()

◆ APP_ImgTail()

◆ IMG_AddInstrumentFunction()

◆ IMG_AddUnloadFunction()

◆ IMG_Close()

◆ IMG_DynamicRawData()

◆ IMG_EntryAddress()

◆ IMG_FindByAddress()

◆ IMG_FindImgById()

◆ IMG_Gp()

◆ IMG_hasLinesData()

◆ IMG_HasProperty()

◆ IMG_HighAddress()

◆ IMG_Id()

◆ IMG_Invalid()

◆ IMG_IsInterpreter()

◆ IMG_IsMainExecutable()

◆ IMG_IsStaticExecutable()

◆ IMG_IsVDSO()

◆ IMG_LoadOffset()

◆ IMG_LowAddress()

◆ IMG_Name()

◆ IMG_Next()

◆ IMG_NumRegions()

◆ IMG_Open()

◆ IMG_Prev()

◆ IMG_RegionHighAddress()

◆ IMG_RegionLowAddress()

◆ IMG_RegsymHead()

◆ IMG_SecHead()

◆ IMG_SecTail()

◆ IMG_SizeMapped()

◆ IMG_StartAddress()

◆ IMG_Type()

◆ IMG_Valid()