PinCRT
Classes | Enumerations | Functions
Memory

Classes

struct  OS_MEMORY_AT_ADDR_INFORMATION
 

Enumerations

enum  OS_PAGE_PROTECTION_TYPE {
  OS_PAGE_PROTECTION_TYPE_NOACCESS = 0,
  OS_PAGE_PROTECTION_TYPE_READ = (1<<0),
  OS_PAGE_PROTECTION_TYPE_WRITE = (1<<1),
  OS_PAGE_PROTECTION_TYPE_EXECUTE = (1<<2),
  OS_PAGE_PROTECTION_TYPE_GUARD = (1<<3)
}
 
enum  OS_MEMORY_FLAGS {
  OS_MEMORY_FLAGS_PRIVATE = 0,
  OS_MEMORY_FLAGS_FIXED_ADDRESS = (1<<0),
  OS_MEMORY_FLAGS_STACK = (1<<1),
  OS_MEMORY_FLAGS_SHARED = (1<<3)
}
 

Functions

OS_RETURN_CODE OS_AllocateMemory (NATIVE_PID processId, UINT protectionType, USIZE size, OS_MEMORY_FLAGS flags, VOID **base)
 
OS_RETURN_CODE OS_MapFileToMemory (NATIVE_PID processId, UINT protectionType, USIZE size, OS_MEMORY_FLAGS flags, NATIVE_FD fd, UINT64 offset, VOID **base)
 
OS_RETURN_CODE OS_FreeMemory (NATIVE_PID processId, VOID *base, USIZE size)
 
OS_RETURN_CODE OS_GetPageSize (USIZE *size)
 
OS_RETURN_CODE OS_QueryMemory (NATIVE_PID processId, VOID *memoryAddr, OS_MEMORY_AT_ADDR_INFORMATION *info)
 
OS_RETURN_CODE OS_ProtectMemory (NATIVE_PID processId, VOID *base, USIZE size, UINT newProtectionType)
 

Detailed Description

Enumeration Type Documentation

◆ OS_MEMORY_FLAGS

Flags for memory mapping.

Enumerator
OS_MEMORY_FLAGS_PRIVATE 

The memory should be private to the process.

OS_MEMORY_FLAGS_FIXED_ADDRESS 

The memory should be mapped exactly at the specified address.

OS_MEMORY_FLAGS_STACK 

The memory should be mapped as stack (grows down).

OS_MEMORY_FLAGS_SHARED 

The memory might be shared among processes.

◆ OS_PAGE_PROTECTION_TYPE

Page protection types

Function Documentation

◆ OS_AllocateMemory()

OS_RETURN_CODE OS_AllocateMemory ( NATIVE_PID  processId,
UINT  protectionType,
USIZE  size,
OS_MEMORY_FLAGS  flags,
VOID **  base 
)

Allocates size bytes of memory in the process identified by processId with protectionType protection.

Warning
If base is not null, will try to allocate at that address, otherwise will fail!
Parameters
[in]processIdPID of the target process
[in]protectionTypeor'ed protection options
[in]sizeSize of memory to allocate
[in]flagsProperties of the region to allocate. This is a bitwise OR of the enum values in OS_MEMORY_FLAGS.
[in,out]basein: Target memory address
out: Where the memory was allocated
Return values
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_MEMORY_MAP_FAILEDIf the operation Failed
Remarks
Unix:
The processId is irrelevant as it is only applicable on the current process.
On Unix system, memory can only be allocated for the calling process.
The given pid is expected to be that of the current process. Hence the behavior of this function in case 'processId' is not of the current process is not defined. Windows:
Windows supports memory allocation on a different process on a single syscall.
Availability:
O/S: Windows, Linux & macOS*
CPU: All

◆ OS_FreeMemory()

OS_RETURN_CODE OS_FreeMemory ( NATIVE_PID  processId,
VOID *  base,
USIZE  size 
)

Free's size bytes of memory at base address in the process identified by processId.

Parameters
[in]processIdPID of the target process
[in]baseTarget memory address
[in]sizeSize in bytes of memory to free
Return values
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_MEMORY_FREE_FAILEDIf the operation failed
Remarks
Unix:
The processId is irrelevant as it is only applicable on the current process.
On Unix system, memory can only be released in the current process.
The given pid is expected to be that of the current process. Hence the behavior of this function in case 'processId' is not of the current process is not defined. Windows:
Windows supports memory deallocation on a different process.
Availability:
O/S: Windows, Linux & macOS*
CPU: All

◆ OS_GetPageSize()

OS_RETURN_CODE OS_GetPageSize ( USIZE *  size)

Query the system page size.

Parameters
[out]sizeSystem page size
Return values
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_QUERY_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
CPU: All

◆ OS_MapFileToMemory()

OS_RETURN_CODE OS_MapFileToMemory ( NATIVE_PID  processId,
UINT  protectionType,
USIZE  size,
OS_MEMORY_FLAGS  flags,
NATIVE_FD  fd,
UINT64  offset,
VOID **  base 
)

Maps a file into memory, similar to mmap (see man page of mmap(2)).

Warning
If base is not null, will try to allocate at that address, otherwise will fail!
Parameters
[in]processIdPID of the target process
[in]protectionTypeor'ed protection options
[in]sizeSize in bytes of memory to allocate
[in]flagsProperties of the region to allocate. This is a bitwise OR of the enum values in OS_MEMORY_FLAGS.
[in]fdFile descriptor of the file that we want to map to memory. This argument can be INVALID_NATIVE_FD if one wants to map an anonymous file.
[in]offsetBytes offset in the file to start mapping from.
[in,out]basein: Target memory address
out: Where the memory was allocated
Return values
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_MEMORY_MAP_FAILEDIf the operation Failed
Remarks
Unix:
The processId is irrelevant as it is only applicable on the current process.
On Unix system, files can be mapped only in the calling process memory space.
The given pid is expected to be that of the current process.
Hence the behavior of this function in case 'processId' is not of the current process is not defined. Windows:
Windows supports file mapping on a different process memory space.
Availability:
O/S: Windows, Linux & macOS*
CPU: All

◆ OS_ProtectMemory()

OS_RETURN_CODE OS_ProtectMemory ( NATIVE_PID  processId,
VOID *  base,
USIZE  size,
UINT  newProtectionType 
)

Changes protection for the target process's memory page(s) containing any part of the address range in the interval [base, base+size-1]. base must be aligned to a page boundary.

Parameters
[in]processIdPID of the target process
[in]baseThe address of the starting page - must be page aligned.
[in]sizeSize in bytes of the region to change protection - must be multiple of page size.
[in]newProtectionTypeThe new protection mode
Return values
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_MEMORY_PROTECT_FAILEDIf the operation failed

Unix:
The processId is irrelevant as it is only applicable on the current process.
On Unix system, memory protection can only be changed for the current process' memory space.
The given pid is expected to be that of the current process. Hence the behavior of this function in case 'processId' is not of the current process is not defined. Windows:
Windows supports memory protection change on a different process memory space.

Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All

◆ OS_QueryMemory()

OS_RETURN_CODE OS_QueryMemory ( NATIVE_PID  processId,
VOID *  memoryAddr,
OS_MEMORY_AT_ADDR_INFORMATION info 
)

Retrieves the information on the memory block containing memoryAddr.

Parameters
[in]processIdPID of the target process
[in]memoryAddrTarget memory address. This memory address can reside inside the page.
[out]infoThe address information On Unix, if there is no mapped memory block that contains memoryAddr the next mapped memory block will be returned. If no such mapped memory block exists, an empty memory block will be returned On Windows, we return the containing memory block regardless if it is mapped or not.
Return values
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_QUERY_FAILEDIf the operation failed
Remarks
Unix:
The processId is irrelevant as it is only applicable on the current process.
On Unix system, memory can only be queried for the current process.
The given pid is expected to be that of the current process. Hence the behavior of this function in case 'processId' is not of the current process is not defined.
Windows:
Windows supports memory query on a different process memory space.
Availability:
O/S: Windows, Linux & macOS*
CPU: All