Module

Edit on GitHub
#include <Module.h>
Header Source
SReturnNameParameters
Module (void)
Module (const Process& process, const string& name, const string& path, uintptr base, uintptr size)
bool IsValid (void) const
string GetName (void) const
string GetPath (void) const
uintptr GetBase (void) const
uintptr GetSize (void) const
Process GetProcess (void) const
SegmentList GetSegments (void) const
bool Contains (uintptr address) const
bool operator < (uintptr address) const
bool operator > (uintptr address) const
bool operator <= (uintptr address) const
bool operator >= (uintptr address) const
bool operator < (const Module& module) const
bool operator > (const Module& module) const
bool operator <= (const Module& module) const
bool operator >= (const Module& module) const
bool operator == (const Module& module) const
bool operator != (const Module& module) const

Description

Represents a single module loaded within a process. A module is an executable file or shared library which has been loaded into a process and each process may consist of one or more of these modules. To retrieve a snapshot of all modules within a process, use the GetModules function within the Process class. When implementing a custom snapshot routine, a module can be created through the Constructor. There are no resources to be freed and all information is cached and immutable.

After a module has been created, to check whether the information in that module is valid, use the IsValid function. To retrieve the name and path of the module, use the GetName and GetPath functions. To retrieve the loaded base address and size of the module, use the GetBase and GetSize functions. The process in which this module is loaded into can be retrieved through the GetProcess function. And on Mac, because all segments of the module reside in different regions of the virtual address space, the GetSegments function can be used to retrieve all relevant information about them.

The Module class also offers a wide range of useful functionality. For example, the Contains function can be used to check whether an address is contained within the module. And various relational operators help in cases where a module needs to be compared to other modules, as in the case of sorting. Comparison is supported as well.

Types

typedef vector<Segment> Module::SegmentList;

Constructors

    

        



            Module
            (void)

Constructs an invalid module with all components set to default values. 

    

        



            Module
            (const Process& process,
 const string& name,
 const string& path,
 uintptr base, uintptr size)

Constructs a valid module with all components set to the parameters.

Functions

    

        


            bool
            IsValid
            (void) const

Returns true if this module has been assigned data through the Constructor. 

    

        


            string
            GetName
            (void) const

Returns the name of this module, as a UTF-8 encoded string. This function does not return the platform-dependent module name but rather just the last portion of GetPath. Returns an empty string if no name is available. 

    

        


            string
            GetPath
            (void) const

Returns the full path of this module, as a UTF-8 encoded string. A forward slash (/) is always used to represent directories across all platforms. Returns an empty string if no path is available. 

    

        


            uintptr
            GetBase
            (void) const
        

        


            uintptr
            GetSize
            (void) const

Returns the load address of this module and the size it occupies within the process, in bytes.

Mac: GetSize will always return zero because modules are not linearly stored within the virtual address space of the process. To determine the size of specific segments, use the GetSegments function and iterate through the results until the desired segment is found. 

    

        


            Process
            GetProcess
            (void) const

Returns the process this module is loaded into. 

    

        


            SegmentList
            GetSegments
            (void) const

On Mac, returns a list of all Mach-O segments in the module. The resulting list is guaranteed to be sorted from the lowest base address to the highest and will never contain any duplicate entries. Segments are retrieved and cached the first time this function is called with subsequent calls returning the cached results immediately. On Linux and Windows, this function will always return an empty list. 

    

        


            bool
            Contains
            (uintptr address) const

Returns true if address is in the range [Base, Base + Size) of this module.

Operators

    

        


            bool
            operator <
            (uintptr address) const
        

        


            bool
            operator >
            (uintptr address) const
        

        


            bool
            operator <=
            (uintptr address) const
        

        


            bool
            operator >=
            (uintptr address) const

Performs relational comparison using the base of this module and address. 

    

        


            bool
            operator <
            (const Module& module) const
        

        


            bool
            operator >
            (const Module& module) const
        

        


            bool
            operator <=
            (const Module& module) const
        

        


            bool
            operator >=
            (const Module& module) const

Performs relational comparison using the base of this module and module. 

    

        


            bool
            operator ==
            (const Module& module) const
        

        


            bool
            operator !=
            (const Module& module) const

Performs equality comparison to determine whether or not two modules have the same validity, base, size and process. No other properties are compared.

Segment

SReturnNameParameters
bool Contains (uintptr address) const
bool operator < (uintptr address) const
bool operator > (uintptr address) const
bool operator <= (uintptr address) const
bool operator >= (uintptr address) const
bool operator < (const Segment& segment) const
bool operator > (const Segment& segment) const
bool operator <= (const Segment& segment) const
bool operator >= (const Segment& segment) const
bool operator == (const Segment& segment) const
bool operator != (const Segment& segment) const
bool Valid
char* Name
uintptr Base
uintptr Size

Description

Represents a single Mach-O segment belonging to a module. On Mac, a module is made up of multiple segments and each segment can be mapped to a different region of the virtual address space. Because of this, each segment has to be retrieved manually depending on the type of information required. To retrieve a list of all segments within a module, use the GetSegments function within the Module class.

After a segment has been created, all information can be retrieved through the class properties. For instance, to check whether the segment information is valid, use the Valid property. To get the name of the segment, use the Name property. To gwt the loaded base address and size of the segment, use the Base and Size properties.

The Module class also offers a wide range of useful functionality. For example, the Contains function can be used to check whether an address is contained within the segment. And various relational operators help in cases where a segment needs to be compared to other segments, as in the case of sorting. Comparison is supported as well.

Note: The Module class is not used on Linux and Windows because both platforms store all their modules linearly within the virtual address space of the process.

Functions

    

        


            bool
            Contains
            (uintptr address) const

Returns true if address is in the range [Base, Base + Size) of this segment.

Operators

    

        


            bool
            operator <
            (uintptr address) const
        

        


            bool
            operator >
            (uintptr address) const
        

        


            bool
            operator <=
            (uintptr address) const
        

        


            bool
            operator >=
            (uintptr address) const

Performs relational comparison using the base of this segment and address. 

    

        


            bool
            operator <
            (const Segment& segment) const
        

        


            bool
            operator >
            (const Segment& segment) const
        

        


            bool
            operator <=
            (const Segment& segment) const
        

        


            bool
            operator >=
            (const Segment& segment) const

Performs relational comparison using the base of this segment and segment. 

    

        


            bool
            operator ==
            (const Segment& segment) const
        

        


            bool
            operator !=
            (const Segment& segment) const

Performs equality comparison to determine whether two segments have identical properties.

Properties

    

        


            bool
            Valid

Gets or sets a value indicating whether the information in this segment is valid. 

    

        


            char*
            Name

Gets or sets the short name of this segment (e.g. __TEXT, __LINKEDIT, etc.). 

    

        


            uintptr
            Base
            
        

        


            uintptr
            Size

Gets or sets the load address of this segment and the size it occupies, in bytes.

Examples

// C++
#include <Robot.h>
ROBOT_NS_USE_ALL;

int main (void)
{
    // Retrieve the active/calling process
    Process process = Process::GetCurrent();

    // Get all modules in the process
    auto list = process.GetModules();

    // List is an STL vector
    for (const auto& m : list)
    {
        m.GetName(); // module
        m.GetPath(); // path/to/module
        m.GetBase(); // Load address
        m.GetSize(); // Virtual size

        // Points back to process
        m.GetProcess() == process;

        // Retrieve module segments
        // Only relevant on the Mac
        auto segs = m.GetSegments();

        // Segs is an STL vector
        for (const auto& s : segs)
        {
            s.Base; // Load address
            s.Size; // Virtual size
        }
    }

    if (list.size() >= 2)
    {
        list[0] <= list[1]; // True
        list[0] >= list[1]; // False

        list[0] == list[1]; // False
        list[0] != list[1]; // True
    }

    return 0;
}

// Node
var robot = require ("robot-js");

// Retrieve the active/calling process
var process = robot.Process.getCurrent();

// Get all modules in the process
var list = process.getModules();

// List is an array
list.map (function (m)
{
    m.getName(); // module
    m.getPath(); // path/to/module
    m.getBase(); // Load address
    m.getSize(); // Virtual size

    // Points back to process
    m.getProcess().eq (process);

    // Retrieve module segments
    // Only relevant on the Mac
    var segs = m.getSegments();

    // Segs is an array
    segs.map (function (s)
    {
        s.base; // Load address
        s.size; // Virtual size
    });
});

if (list.length >= 2)
{
    list[0].le (list[1]); // True
    list[0].ge (list[1]); // False

    list[0].eq (list[1]); // False
    list[0].ne (list[1]); // True
}