IMG: Image Object


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
}

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_Entry (IMG img)
const 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_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)
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 string &filename)
VOID LEVEL_PINCLIENT::IMG_Close (IMG img)
IMG LEVEL_PINCLIENT::APP_ImgHead ()
IMG LEVEL_PINCLIENT::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

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

Type of function to be called when an image is loaded


Enumeration Type Documentation

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  Container for all dynamically created functions.
IMG_TYPE_API_CREATED  Artificial image created by IMG_CreateAt ().


Function Documentation

IMG LEVEL_PINCLIENT::APP_ImgHead  ) 
 

Returns:
The first image loaded into memory
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

IMG LEVEL_PINCLIENT::APP_ImgTail  ) 
 

Returns:
The last image loaded into memory
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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

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

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

ADDRINT LEVEL_PINCLIENT::IMG_Entry IMG  img  ) 
 

Returns:
Address of first instruction executed when image is loaded
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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

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

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

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 LEVEL_PINCLIENT::IMG_Invalid  ) 
 

Returns:
Used to indicate no image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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

BOOL LEVEL_PINCLIENT::IMG_IsMainExecutable IMG  x  ) 
 

Returns:
TRUE if this is the main executable of an application
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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

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

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

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

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

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 LEVEL_PINCLIENT::IMG_Open const 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), this is supported for Linux (only for locales encoded in UTF8) and Windows.

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

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

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

SYM LEVEL_PINCLIENT::IMG_RegsymHead IMG  img  ) 
 

Returns:
First regular symbol in image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

SEC LEVEL_PINCLIENT::IMG_SecHead IMG  img  ) 
 

Returns:
First section in image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

SEC LEVEL_PINCLIENT::IMG_SecTail IMG  img  ) 
 

Returns:
Last section in image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

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

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 LEVEL_PINCLIENT::IMG_Type IMG  img  ) 
 

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

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


Generated on Sun Aug 27 14:28:10 2017 for Pin by  doxygen 1.4.6