Pin
Typedefs | Enumerations | Functions
IMG: Image Object

Typedefs

typedef VOID(* IMAGECALLBACK) (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 x)
 
BOOL IMG_hasLinesData (IMG x)
 
BOOL IMG_IsInterpreter (IMG x)
 
BOOL IMG_IsStaticExecutable (IMG x)
 
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 x)
 
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)
 
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) )

Typedef Documentation

◆ IMAGECALLBACK

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

Type of function to be called when an image is loaded

Enumeration Type Documentation

◆ 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 ( )
Returns
The first image loaded into memory
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ APP_ImgTail()

IMG APP_ImgTail ( )
Returns
The last image loaded into memory
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ IMG_AddInstrumentFunction()

PIN_CALLBACK IMG_AddInstrumentFunction ( IMAGECALLBACK  fun,
VOID *  v 
)

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

Parameters
funInstrumentation function for images, it is passed an image and v
vthe 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 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
funpassed an image and v when an image is unloaded
vthe 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 IMG_Close ( IMG  img)

Close the open image.

Parameters
[in]imgThe IMG that was previously opened.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ IMG_DynamicRawData()

VOID* 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]imgThe 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)
Parameters
[in]imgPin 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 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 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 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 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 IMG_HasProperty ( IMG  img,
IMG_PROPERTY  property 
)

Checks if image has the specificfied property

Parameters
[in]imgPin image handle
[in]propertythe 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)

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]imgThe 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 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 IMG_Invalid ( )
Returns
Used to indicate no image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ IMG_IsInterpreter()

BOOL 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]imgThe 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 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 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 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]imgThe 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 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 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]imgThe 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& 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 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 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 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]filenameThe 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 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 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 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 IMG_RegsymHead ( IMG  img)
Returns
First regular symbol in image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ IMG_SecHead()

SEC IMG_SecHead ( IMG  img)
Returns
First section in image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ IMG_SecTail()

SEC IMG_SecTail ( IMG  img)
Returns
Last section in image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ IMG_SizeMapped()

USIZE 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]imgThe 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 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]imgThe 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 IMG_Type ( IMG  img)
Returns
Image type
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ IMG_Valid()

BOOL IMG_Valid ( IMG  img)
Returns
True if x is not IMG_Invalid()
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All