|
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
} |
|
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:
◆ IMAGECALLBACK
typedef VOID(* IMAGECALLBACK) (IMG, VOID *) |
Type of function to be called when an image is loaded
◆ 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
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 ()
|
◆ APP_ImgHead()
- Returns
- The first image loaded into memory
- Availability:
- Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All
◆ APP_ImgTail()
- Returns
- The last image loaded into memory
- Availability:
- Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All
◆ IMG_AddInstrumentFunction()
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()
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 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* 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 IMG_EntryAddress |
( |
IMG |
img | ) |
|
- Parameters
-
- 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()
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 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.
- 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()
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()
- 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] | 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 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] | 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 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.
- 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& 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()
- 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] | 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()
- 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
- 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
- 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] | 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 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()
- 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