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

typedef BOOL(*	IMAGE_PRE_DEBUG_INFO_PROCESS_CALLBACK) (IMG, VOID *)

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

enum	IMG_PROPERTY { IMG_PROPERTY_INVALID , IMG_PROPERTY_SHSTK_ENABLED , IMG_PROPERTY_IBT_ENABLED , IMG_PROPERTY_LAST }

Functions
IMG	IMG_Next (IMG img)

IMG	IMG_Prev (IMG img)

IMG	IMG_Invalid ()

BOOL	IMG_Valid (IMG img)

SEC	IMG_SecHead (IMG img)

SEC	IMG_SecTail (IMG img)

SYM	IMG_RegsymHead (IMG img)

ADDRINT	IMG_EntryAddress (IMG img)

BOOL	IMG_HasProperty (IMG img, IMG_PROPERTY property)

const std::string &	IMG_Name (IMG img)

ADDRINT	IMG_Gp (IMG img)

ADDRINT	IMG_LoadOffset (IMG img)

ADDRINT	IMG_LowAddress (IMG img)

ADDRINT	IMG_HighAddress (IMG img)

ADDRINT	IMG_StartAddress (IMG img)

USIZE	IMG_SizeMapped (IMG img)

IMG_TYPE	IMG_Type (IMG img)

BOOL	IMG_IsMainExecutable (IMG img)

BOOL	IMG_hasLinesData (IMG img)

BOOL	IMG_IsInterpreter (IMG img)

BOOL	IMG_IsStaticExecutable (IMG img)

BOOL	IMG_IsVDSO (IMG img)

UINT32	IMG_NumRegions (IMG img)

ADDRINT	IMG_RegionHighAddress (IMG img, UINT32 n)

ADDRINT	IMG_RegionLowAddress (IMG img, UINT32 n)

UINT32	IMG_Id (IMG img)

VOID *	IMG_DynamicRawData (IMG img)

IMG	IMG_FindImgById (UINT32 id)

IMG	IMG_FindByAddress (ADDRINT address)

PIN_CALLBACK	IMG_AddInstrumentFunction (IMAGECALLBACK fun, VOID *v)

PIN_CALLBACK	IMG_AddUnloadFunction (IMAGECALLBACK fun, VOID *v)

VOID	IMG_AddPreDebugInfoProcessCallback (IMAGE_PRE_DEBUG_INFO_PROCESS_CALLBACK fun, VOID *v)

IMG	IMG_Open (const std::string &filename)

VOID	IMG_Close (IMG img)

IMG	APP_ImgHead ()

IMG	APP_ImgTail ()

Detailed Description

An IMG represents all the data structures corresponding to a binary (executable). Can be accessed at instrumentation time and analysis time. Note: Shared libraries are also represented by the IMG abstraction. Moreover, the IMG objects are created in a lazy fashion. Only if a shared library is loaded and IMG is created. Over the lifetime of a process the number IMG objects created may hence increase.
APIs from this group are available in any thread, including any internal thread spawned by the tool.

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

IMG_Valid

BOOL IMG_Valid(IMG img)

Checks if the image is valid.

APP_ImgHead

IMG APP_ImgHead()

Returns the first image loaded into memory.

IMG_Next

IMG IMG_Next(IMG img)

Returns the image loaded after the given image, or IMG_Invalid() if it is the last image.

Typedef Documentation

◆ IMAGE_PRE_DEBUG_INFO_PROCESS_CALLBACK

typedef BOOL(* IMAGE_PRE_DEBUG_INFO_PROCESS_CALLBACK) (IMG, VOID *)

Type of function to be called before processing symbols of an image. If the function returns FALSE, the symbol processing is skipped for the image.

◆ IMAGECALLBACK

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

Type of function to be called when an image is loaded

Enumeration Type Documentation

◆ IMG_PROPERTY

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

This file contains IMG primitives

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

extern

Returns the first image loaded into memory.

Returns: The first image loaded into memory

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

◆ APP_ImgTail()

IMG APP_ImgTail ( )

extern

Returns the last image loaded into memory.

Returns: The last image loaded into memory

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

◆ IMG_AddInstrumentFunction()

PIN_CALLBACK IMG_AddInstrumentFunction	(	IMAGECALLBACK	fun,
		VOID *	v
	)

extern

Registers a callback to catch the loading of an image.

Parameters

[in]	fun	Instrumentation function for images, it is passed an image and v
[in]	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 must be obtained before calling this API from outside main() or instrumentation callbacks.

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

◆ IMG_AddPreDebugInfoProcessCallback()

VOID IMG_AddPreDebugInfoProcessCallback	(	IMAGE_PRE_DEBUG_INFO_PROCESS_CALLBACK	fun,
		VOID *	v
	)

extern

Registers a callback to be invoked before processing debug information for the image.

If the callback returns FALSE, debug information processing is skipped for the image. This API can be used to optimize symbol (SYM) processing when the tool is interested only in symbols (SYM/RTN) from certain images. In some cases, skipping debug information processing can significantly reduce Pin's initialization time or image load processing time.

By the time the callback is called, the image is already loaded and most image information is available. However, RTNs are not yet created, and only symbols (SYM) from the export/symbol table are available. It is recommended not to emit any instrumentation from within this callback; use it only to decide whether to process debug information symbols for the image.

Parameters

[in]	fun	passed an image and v before processing symbols from the image's debug information
[in]	v	the value to pass to fun when it is called

Note: Symbols (SYM) from the export/symbol table are always processed, regardless of the return value of this callback.; Skipping debug information processing only affects RTN construction and SYM APIs. It does not affect PIN_GetSourceLocation API.; The pin client lock must be obtained before calling this API from outside main() or instrumentation callbacks.

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

◆ IMG_AddUnloadFunction()

PIN_CALLBACK IMG_AddUnloadFunction	(	IMAGECALLBACK	fun,
		VOID *	v
	)

extern

Registers a callback 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

[in]	fun	passed an image and v when an image is unloaded
[in]	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 must be obtained before calling this API from outside main() or instrumentation callbacks.

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

◆ IMG_Close()

VOID IMG_Close ( IMG img )

extern

Closes the open image.

Parameters

[in] img The IMG that was previously opened.

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

◆ IMG_DynamicRawData()

VOID * IMG_DynamicRawData ( IMG img )

extern

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 IMG_EntryAddress ( IMG img )

extern

Returns the address of first instruction executed when image is loaded.

Parameters

[in] img Pin image handle

Returns: Address of first instruction executed when image is loaded

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

◆ IMG_FindByAddress()

IMG IMG_FindByAddress ( ADDRINT address )

extern

Finds an image by address.

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

Parameters

[in] address The address to search for

Returns: IMG object, valid or invalid

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

◆ IMG_FindImgById()

IMG IMG_FindImgById ( UINT32 id )

extern

Finds an image by its ID.

Parameters

[in] id The image ID to search for

Returns: IMG object, valid or invalid

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

◆ IMG_Gp()

ADDRINT IMG_Gp ( IMG img )

extern

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

Parameters

[in] img The image object

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

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

◆ IMG_hasLinesData()

BOOL IMG_hasLinesData ( IMG img )

extern

Checks if the image has debug information that includes the lines information.

Parameters

[in] img The image object

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

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

◆ IMG_HasProperty()

BOOL IMG_HasProperty	(	IMG	img,
		IMG_PROPERTY	property
	)

extern

Checks if image has the specified 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 IMG_HighAddress ( IMG img )

extern

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

◆ IMG_Id()

UINT32 IMG_Id ( IMG img )

extern

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.

Parameters

[in] img The image object

Returns: Unique ID for the image.

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

◆ IMG_Invalid()

IMG IMG_Invalid ( )

extern

Returns an invalid image value used to indicate no image.

Returns: Used to indicate no image

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

◆ IMG_IsInterpreter()

BOOL IMG_IsInterpreter ( IMG img )

extern

Checks if this is the image of the application's loader (interpreter).

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

◆ IMG_IsMainExecutable()

BOOL IMG_IsMainExecutable ( IMG img )

extern

Checks if this is the main executable image.

Parameters

[in] img The image object

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

◆ IMG_IsStaticExecutable()

BOOL IMG_IsStaticExecutable ( IMG img )

extern

Checks if this is the static executable.

Parameters

[in] img The image object

Returns: TRUE if this is the static executable

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

◆ IMG_IsVDSO()

BOOL IMG_IsVDSO ( IMG img )

extern

Checks if this is the VDSO image.

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

◆ IMG_LoadOffset()

ADDRINT IMG_LoadOffset ( IMG img )

extern

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

Parameters

[in] img The image object

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 IMG_LowAddress ( IMG img )

extern

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

◆ IMG_Name()

const std::string & IMG_Name ( IMG img )

extern

Returns the fully qualified actual file name of the image.

Image names are encoded in UTF8 (a superset of ASCII), this is supported for Linux (only for locales encoded in UTF8) and Windows

Parameters

[in] img The image object

Returns: Fully qualified actual file name of image.

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

◆ IMG_Next()

IMG IMG_Next ( IMG img )

extern

Returns the image loaded after the given image, or IMG_Invalid() if it is the last image.

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

Skip shadow image (vdso or dynamic code)

Parameters

[in] img The image object

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

◆ IMG_NumRegions()

UINT32 IMG_NumRegions ( IMG img )

extern

Returns the number of consecutive regions of the image in memory.

Parameters

[in] img The image object

Returns: number of consecutive regions of the image in memory

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

◆ IMG_Open()

IMG IMG_Open ( const std::string & filename )

extern

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

◆ IMG_Prev()

IMG IMG_Prev ( IMG img )

extern

Returns the image loaded prior to the given image, or IMG_Invalid() if it is the first image.

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

Parameters

[in] img The image object

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

◆ IMG_RegionHighAddress()

ADDRINT IMG_RegionHighAddress	(	IMG	img,
		UINT32	n
	)

extern

Returns the high address of the n'th region.

Parameters

[in]	img	The image object
[in]	n	The region index (starts at 0)

Remarks: n starts at 0

Returns: the high address of the n'th region

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

◆ IMG_RegionLowAddress()

ADDRINT IMG_RegionLowAddress	(	IMG	img,
		UINT32	n
	)

extern

Returns the low address of the n'th region.

Parameters

[in]	img	The image object
[in]	n	The region index (starts at 0)

Remarks: n starts at 0

Returns: the low address of the n'th region

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

◆ IMG_RegsymHead()

SYM IMG_RegsymHead ( IMG img )

extern

Returns the first regular symbol in the image.

Parameters

[in] img The image object

Returns: First regular symbol in image

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

◆ IMG_SecHead()

SEC IMG_SecHead ( IMG img )

extern

Returns the first section in the image.

Parameters

[in] img The image object

Returns: First section in image

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

◆ IMG_SecTail()

SEC IMG_SecTail ( IMG img )

extern

Returns the last section in the image.

Parameters

[in] img The image object

Returns: Last section in image

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

◆ IMG_SizeMapped()

USIZE IMG_SizeMapped ( IMG img )

extern

Tells the size of the raw image mapped by Pin.

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

◆ IMG_StartAddress()

ADDRINT IMG_StartAddress ( IMG img )

extern

Returns a pointer to the start of the raw image file.

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

◆ IMG_Type()

IMG_TYPE IMG_Type ( IMG img )

extern

Returns the image type.

Parameters

[in] img The image object

Returns: Image type

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

◆ IMG_Valid()

BOOL IMG_Valid ( IMG img )

extern

Checks if the image is valid.

Parameters

[in] img The image object to check

Returns: True if img is not IMG_Invalid()

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

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ IMAGE_PRE_DEBUG_INFO_PROCESS_CALLBACK

◆ IMAGECALLBACK

Enumeration Type Documentation

◆ IMG_PROPERTY

◆ IMG_TYPE

Function Documentation

◆ APP_ImgHead()

◆ APP_ImgTail()

◆ IMG_AddInstrumentFunction()

◆ IMG_AddPreDebugInfoProcessCallback()

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