From 66c47d87c15a3b56d092ffe68061ebfa8573c5fa Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 7 Feb 2026 00:30:39 +0000 Subject: [PATCH] Add Roboto Condensed font and documentation for new features Co-authored-by: orange-cpp <59374393+orange-cpp@users.noreply.github.com> --- docs/collision/collider_interface.md | 93 ++++++++++++++ docs/containers/encrypted_variable.md | 115 +++++++++++++++++ docs/styles/fonts.css | 172 ++++++++++++++++++++++++++ docs/utility/elf_pattern_scan.md | 142 +++++++++++++++++++++ docs/utility/macho_pattern_scan.md | 142 +++++++++++++++++++++ docs/utility/section_scan_result.md | 58 +++++++++ mkdocs.yml | 1 + 7 files changed, 723 insertions(+) create mode 100644 docs/collision/collider_interface.md create mode 100644 docs/containers/encrypted_variable.md create mode 100644 docs/styles/fonts.css create mode 100644 docs/utility/elf_pattern_scan.md create mode 100644 docs/utility/macho_pattern_scan.md create mode 100644 docs/utility/section_scan_result.md diff --git a/docs/collision/collider_interface.md b/docs/collision/collider_interface.md new file mode 100644 index 0000000..7346af5 --- /dev/null +++ b/docs/collision/collider_interface.md @@ -0,0 +1,93 @@ +# `omath::collision::ColliderInterface` — Abstract collider base class + +> Header: `omath/collision/collider_interface.hpp` +> Namespace: `omath::collision` +> Depends on: `omath/linear_algebra/vector3.hpp` + +`ColliderInterface` is the abstract base class for all colliders used by the GJK and EPA algorithms. Any shape that can report its furthest vertex along a given direction can implement this interface and be used for collision detection. + +--- + +## API + +```cpp +namespace omath::collision { + +template> +class ColliderInterface { +public: + using VectorType = VecType; + + virtual ~ColliderInterface() = default; + + // Return the world-space position of the vertex furthest along `direction`. + [[nodiscard]] + virtual VectorType find_abs_furthest_vertex_position( + const VectorType& direction) const = 0; + + // Get the collider's origin (center / position). + [[nodiscard]] + virtual const VectorType& get_origin() const = 0; + + // Reposition the collider. + virtual void set_origin(const VectorType& new_origin) = 0; +}; + +} // namespace omath::collision +``` + +--- + +## Implementing a custom collider + +To create a new collider shape, derive from `ColliderInterface` and implement the three pure-virtual methods: + +```cpp +#include "omath/collision/collider_interface.hpp" + +class SphereCollider final + : public omath::collision::ColliderInterface> +{ +public: + SphereCollider(omath::Vector3 center, float radius) + : m_center(center), m_radius(radius) {} + + [[nodiscard]] + omath::Vector3 find_abs_furthest_vertex_position( + const omath::Vector3& direction) const override + { + return m_center + direction.normalized() * m_radius; + } + + [[nodiscard]] + const omath::Vector3& get_origin() const override + { return m_center; } + + void set_origin(const omath::Vector3& new_origin) override + { m_center = new_origin; } + +private: + omath::Vector3 m_center; + float m_radius; +}; +``` + +--- + +## Notes + +* **Template parameter**: The default vector type is `Vector3`, but any vector type with a `dot()` method can be used. +* **GJK/EPA compatibility**: Both `GjkAlgorithm` and `EpaAlgorithm` accept any type satisfying the `ColliderInterface` contract through their template parameters. + +--- + +## See also + +* [GJK Algorithm](gjk_algorithm.md) — collision detection using GJK. +* [EPA Algorithm](epa_algorithm.md) — penetration depth via EPA. +* [Mesh Collider](mesh_collider.md) — concrete collider wrapping a `Mesh`. +* [Simplex](simplex.md) — simplex data structure used by GJK/EPA. + +--- + +*Last updated: Feb 2026* diff --git a/docs/containers/encrypted_variable.md b/docs/containers/encrypted_variable.md new file mode 100644 index 0000000..b9bfe7c --- /dev/null +++ b/docs/containers/encrypted_variable.md @@ -0,0 +1,115 @@ +# `omath::EncryptedVariable` — Compile-time XOR-encrypted variable + +> Header: `omath/containers/encrypted_variable.hpp` +> Namespace: `omath` +> Depends on: ``, ``, ``, `` + +`EncryptedVariable` keeps a value XOR-encrypted in memory at rest, using a **compile-time generated random key**. It is designed to hinder static analysis and memory scanners from reading sensitive values (e.g., game constants, keys, thresholds) directly from process memory. + +--- + +## Key concepts + +* **Compile-time key generation** — a unique random byte array is produced at compile time via SplitMix64 + FNV-1a seeded from `__FILE__`, `__DATE__`, and `__TIME__`. Each `OMATH_DEF_CRYPT_VAR` expansion receives a distinct key. +* **XOR cipher** — `encrypt()` / `decrypt()` toggle the encrypted state by XOR-ing the raw bytes of the stored value with the key. +* **VarAnchor (RAII guard)** — `drop_anchor()` returns a `VarAnchor` that decrypts on construction and re-encrypts on destruction, ensuring the plaintext window is as short as possible. + +--- + +## API + +```cpp +namespace omath { + +template key> +class EncryptedVariable final { +public: + using value_type = std::remove_cvref_t; + + constexpr explicit EncryptedVariable(const value_type& data); + + [[nodiscard]] constexpr bool is_encrypted() const; + + constexpr void decrypt(); + constexpr void encrypt(); + + [[nodiscard]] constexpr value_type& value(); + [[nodiscard]] constexpr const value_type& value() const; + + [[nodiscard]] constexpr auto drop_anchor(); // returns VarAnchor + + constexpr ~EncryptedVariable(); // decrypts on destruction +}; + +template +class VarAnchor final { +public: + constexpr VarAnchor(EncryptedVarType& var); // decrypts + constexpr ~VarAnchor(); // re-encrypts +}; + +} // namespace omath +``` + +### Helper macros + +```cpp +// Generate a compile-time random byte array of length N +#define OMATH_CT_RAND_ARRAY_BYTE(N) /* ... */ + +// Declare a type alias for EncryptedVariable with KEY_SIZE random bytes +#define OMATH_DEF_CRYPT_VAR(TYPE, KEY_SIZE) /* ... */ +``` + +--- + +## Usage examples + +### Basic encrypt / decrypt + +```cpp +#include "omath/containers/encrypted_variable.hpp" + +// Define an encrypted float with a 16-byte key +using EncFloat = OMATH_DEF_CRYPT_VAR(float, 16); + +EncFloat secret(3.14f); // encrypted immediately +// secret.value() is XOR-scrambled in memory + +secret.decrypt(); +float v = secret.value(); // v == 3.14f +secret.encrypt(); // scrambled again +``` + +### RAII guard with `drop_anchor()` + +```cpp +EncFloat secret(42.0f); + +{ + auto anchor = secret.drop_anchor(); // decrypts + float val = secret.value(); // safe to read + // ... use val ... +} // anchor destroyed → re-encrypts automatically +``` + +--- + +## Notes & edge cases + +* **Force-inline**: When `OMATH_ENABLE_FORCE_INLINE` is defined, encrypt/decrypt operations use compiler-specific force-inline attributes to reduce the call-site footprint visible in disassembly. +* **Not cryptographically secure**: XOR with a static key is an obfuscation technique, not encryption. It raises the bar for casual memory scanning but does not resist a determined attacker who can read the binary. +* **Destructor decrypts**: The destructor calls `decrypt()` so the value is in plaintext at the end of its lifetime (e.g., for logging or cleanup). +* **Thread safety**: No internal synchronization. Protect concurrent access with external locks. +* **`constexpr` support**: All operations are `constexpr`-friendly (C++20). + +--- + +## See also + +* [Pattern Scan](../utility/pattern_scan.md) — scan memory for byte patterns. +* [Getting Started](../getting_started.md) — quick start with OMath. + +--- + +*Last updated: Feb 2026* diff --git a/docs/styles/fonts.css b/docs/styles/fonts.css new file mode 100644 index 0000000..a180d71 --- /dev/null +++ b/docs/styles/fonts.css @@ -0,0 +1,172 @@ +/* cyrillic-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 300; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19-7DRs5.woff2) format('woff2'); + unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F; +} +/* cyrillic */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 300; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19a7DRs5.woff2) format('woff2'); + unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; +} +/* greek-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 300; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-1967DRs5.woff2) format('woff2'); + unicode-range: U+1F00-1FFF; +} +/* greek */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 300; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19G7DRs5.woff2) format('woff2'); + unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF; +} +/* vietnamese */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 300; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-1927DRs5.woff2) format('woff2'); + unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB; +} +/* latin-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 300; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19y7DRs5.woff2) format('woff2'); + unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; +} +/* latin */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 300; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19K7DQ.woff2) format('woff2'); + unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; +} +/* cyrillic-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 400; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19-7DRs5.woff2) format('woff2'); + unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F; +} +/* cyrillic */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 400; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19a7DRs5.woff2) format('woff2'); + unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; +} +/* greek-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 400; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-1967DRs5.woff2) format('woff2'); + unicode-range: U+1F00-1FFF; +} +/* greek */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 400; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19G7DRs5.woff2) format('woff2'); + unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF; +} +/* vietnamese */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 400; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-1927DRs5.woff2) format('woff2'); + unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB; +} +/* latin-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 400; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19y7DRs5.woff2) format('woff2'); + unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; +} +/* latin */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 400; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19K7DQ.woff2) format('woff2'); + unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; +} +/* cyrillic-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 700; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19-7DRs5.woff2) format('woff2'); + unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F; +} +/* cyrillic */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 700; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19a7DRs5.woff2) format('woff2'); + unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; +} +/* greek-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 700; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-1967DRs5.woff2) format('woff2'); + unicode-range: U+1F00-1FFF; +} +/* greek */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 700; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19G7DRs5.woff2) format('woff2'); + unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF; +} +/* vietnamese */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 700; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-1927DRs5.woff2) format('woff2'); + unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB; +} +/* latin-ext */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 700; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19y7DRs5.woff2) format('woff2'); + unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; +} +/* latin */ +@font-face { + font-family: 'Roboto Condensed'; + font-style: normal; + font-weight: 700; + src: url(https://fonts.gstatic.com/s/robotocondensed/v31/ieVl2ZhZI2eCN5jzbjEETS9weq8-19K7DQ.woff2) format('woff2'); + unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; +} + +body { + font-family: 'Roboto Condensed', sans-serif; +} diff --git a/docs/utility/elf_pattern_scan.md b/docs/utility/elf_pattern_scan.md new file mode 100644 index 0000000..1c08472 --- /dev/null +++ b/docs/utility/elf_pattern_scan.md @@ -0,0 +1,142 @@ +# `omath::ElfPatternScanner` — Scan ELF binaries for byte patterns + +> Header: `omath/utility/elf_pattern_scan.hpp` +> Namespace: `omath` +> Platform: **Linux / ELF (Executable and Linkable Format) binaries** +> Depends on: ``, ``, ``, ``, `omath/utility/section_scan_result.hpp` +> Companion: works well with `omath::PatternScanner` (same pattern grammar) + +`ElfPatternScanner` searches **ELF** binaries for a hex pattern (with wildcards). You can scan: + +* a **loaded module** in the current process, or +* an **ELF file on disk** (by section name; defaults to **`.text`**). + +--- + +## Pattern string grammar (same as `PatternScanner`) + +* **Hex byte**: two hex digits → one byte (`90`, `4F`, `00`, `ff`). +* **Wildcard byte**: `?` or `??` matches **any byte**. +* **Whitespace**: ignored (use to group tokens). + +✔️ `"48 8B ?? ?? 89"`, `"55 48 89 E5"`, `"??"` +❌ odd digit counts, non-hex characters (besides `?` and whitespace) + +--- + +## API + +```cpp +namespace omath { + +class ElfPatternScanner final { +public: + // Scan a module already loaded in *this* process. + // module_base_address: base address of the loaded ELF (e.g., from dlopen / /proc/self/maps) + // Returns absolute address (process VA) of the first match, or nullopt. + static std::optional + scan_for_pattern_in_loaded_module( + const void* module_base_address, + const std::string_view& pattern, + const std::string_view& target_section_name = ".text"); + + // Scan an ELF file on disk, by section name (default ".text"). + // Returns section bases (virtual + raw) and match offset within the section, or nullopt. + static std::optional + scan_for_pattern_in_file( + const std::filesystem::path& path_to_file, + const std::string_view& pattern, + const std::string_view& target_section_name = ".text"); +}; + +} // namespace omath +``` + +--- + +## Return values + +* **Loaded module**: `std::optional` + + * `value()` = **process virtual address** of the first match. + * `nullopt` = no match or parse/ELF error. + +* **File scan**: `std::optional` + + * `virtual_base_addr` = virtual address base of the scanned section. + * `raw_base_addr` = file offset of section start. + * `target_offset` = offset from section base to the first matched byte. + * To get addresses: + + * **Virtual address** of hit = `virtual_base_addr + target_offset` + * **Raw file offset** of hit = `raw_base_addr + target_offset` + +--- + +## Usage examples + +### Scan a loaded module (current process) + +```cpp +#include +#include "omath/utility/elf_pattern_scan.hpp" + +using omath::ElfPatternScanner; + +void* handle = dlopen("libexample.so", RTLD_LAZY); +if (handle) { + auto addr = ElfPatternScanner::scan_for_pattern_in_loaded_module( + handle, "55 48 89 E5 ?? ?? 48" + ); + if (addr) { + std::uintptr_t hit_va = *addr; + // ... + } + dlclose(handle); +} +``` + +### Scan an ELF file on disk + +```cpp +#include "omath/utility/elf_pattern_scan.hpp" +using omath::ElfPatternScanner; + +auto res = ElfPatternScanner::scan_for_pattern_in_file( + "/usr/lib/libexample.so", "55 48 89 E5" +); +if (res) { + auto va_hit = res->virtual_base_addr + res->target_offset; + auto raw_hit = res->raw_base_addr + res->target_offset; +} +``` + +### Scan another section (e.g., ".rodata") + +```cpp +auto res = ElfPatternScanner::scan_for_pattern_in_file( + "myapp", "48 8D 0D ?? ?? ?? ??", ".rodata" +); +``` + +--- + +## Notes & edge cases + +* **ELF only**: these functions assume a valid ELF layout. Non-ELF files or corrupted headers yield `nullopt`. +* **Section name**: defaults to **`.text`**; pass a different name to target other sections. +* **Performance**: Pattern matching is **O(N × M)** (sliding window with wildcards). For large binaries, prefer scanning only necessary sections. +* **Architecture**: works for 32-bit and 64-bit ELF binaries. + +--- + +## See also + +* [`omath::PatternScanner`](pattern_scan.md) — raw buffer/iterator scanning with the same pattern grammar. +* [`omath::PePatternScanner`](pe_pattern_scan.md) — PE (Windows) binary scanner. +* [`omath::MachOPatternScanner`](macho_pattern_scan.md) — Mach-O (macOS) binary scanner. +* [`omath::SectionScanResult`](section_scan_result.md) — return type for file-based scans. + +--- + +*Last updated: Feb 2026* diff --git a/docs/utility/macho_pattern_scan.md b/docs/utility/macho_pattern_scan.md new file mode 100644 index 0000000..2dc9449 --- /dev/null +++ b/docs/utility/macho_pattern_scan.md @@ -0,0 +1,142 @@ +# `omath::MachOPatternScanner` — Scan Mach-O binaries for byte patterns + +> Header: `omath/utility/macho_pattern_scan.hpp` +> Namespace: `omath` +> Platform: **macOS / Mach-O binaries** +> Depends on: ``, ``, ``, ``, `omath/utility/section_scan_result.hpp` +> Companion: works well with `omath::PatternScanner` (same pattern grammar) + +`MachOPatternScanner` searches **Mach-O** binaries for a hex pattern (with wildcards). You can scan: + +* a **loaded module** in the current process, or +* a **Mach-O file on disk** (by section name; defaults to **`__text`**). + +--- + +## Pattern string grammar (same as `PatternScanner`) + +* **Hex byte**: two hex digits → one byte (`90`, `4F`, `00`, `ff`). +* **Wildcard byte**: `?` or `??` matches **any byte**. +* **Whitespace**: ignored (use to group tokens). + +✔️ `"48 8B ?? ?? 89"`, `"55 48 89 E5"`, `"??"` +❌ odd digit counts, non-hex characters (besides `?` and whitespace) + +--- + +## API + +```cpp +namespace omath { + +class MachOPatternScanner final { +public: + // Scan a module already loaded in *this* process. + // module_base_address: base address of the loaded Mach-O image + // Returns absolute address (process VA) of the first match, or nullopt. + static std::optional + scan_for_pattern_in_loaded_module( + const void* module_base_address, + const std::string_view& pattern, + const std::string_view& target_section_name = "__text"); + + // Scan a Mach-O file on disk, by section name (default "__text"). + // Returns section bases (virtual + raw) and match offset within the section, or nullopt. + static std::optional + scan_for_pattern_in_file( + const std::filesystem::path& path_to_file, + const std::string_view& pattern, + const std::string_view& target_section_name = "__text"); +}; + +} // namespace omath +``` + +--- + +## Return values + +* **Loaded module**: `std::optional` + + * `value()` = **process virtual address** of the first match. + * `nullopt` = no match or parse/Mach-O error. + +* **File scan**: `std::optional` + + * `virtual_base_addr` = virtual address base of the scanned section. + * `raw_base_addr` = file offset of section start. + * `target_offset` = offset from section base to the first matched byte. + * To get addresses: + + * **Virtual address** of hit = `virtual_base_addr + target_offset` + * **Raw file offset** of hit = `raw_base_addr + target_offset` + +--- + +## Usage examples + +### Scan a loaded module (current process) + +```cpp +#include +#include "omath/utility/macho_pattern_scan.hpp" + +using omath::MachOPatternScanner; + +void* handle = dlopen("libexample.dylib", RTLD_LAZY); +if (handle) { + auto addr = MachOPatternScanner::scan_for_pattern_in_loaded_module( + handle, "55 48 89 E5 ?? ?? 48" + ); + if (addr) { + std::uintptr_t hit_va = *addr; + // ... + } + dlclose(handle); +} +``` + +### Scan a Mach-O file on disk + +```cpp +#include "omath/utility/macho_pattern_scan.hpp" +using omath::MachOPatternScanner; + +auto res = MachOPatternScanner::scan_for_pattern_in_file( + "/usr/local/lib/libexample.dylib", "55 48 89 E5" +); +if (res) { + auto va_hit = res->virtual_base_addr + res->target_offset; + auto raw_hit = res->raw_base_addr + res->target_offset; +} +``` + +### Scan another section (e.g., "__cstring") + +```cpp +auto res = MachOPatternScanner::scan_for_pattern_in_file( + "myapp", "48 8D 0D ?? ?? ?? ??", "__cstring" +); +``` + +--- + +## Notes & edge cases + +* **Mach-O only**: these functions assume a valid Mach-O layout. Non-Mach-O files or corrupted headers yield `nullopt`. +* **Section name**: defaults to **`__text`** (note the double underscore, per Mach-O convention); pass a different name to target other sections. +* **Performance**: Pattern matching is **O(N × M)** (sliding window with wildcards). For large binaries, prefer scanning only necessary sections. +* **Architecture**: works for 64-bit Mach-O binaries (x86_64 and arm64). + +--- + +## See also + +* [`omath::PatternScanner`](pattern_scan.md) — raw buffer/iterator scanning with the same pattern grammar. +* [`omath::PePatternScanner`](pe_pattern_scan.md) — PE (Windows) binary scanner. +* [`omath::ElfPatternScanner`](elf_pattern_scan.md) — ELF (Linux) binary scanner. +* [`omath::SectionScanResult`](section_scan_result.md) — return type for file-based scans. + +--- + +*Last updated: Feb 2026* diff --git a/docs/utility/section_scan_result.md b/docs/utility/section_scan_result.md new file mode 100644 index 0000000..3b565ef --- /dev/null +++ b/docs/utility/section_scan_result.md @@ -0,0 +1,58 @@ +# `omath::SectionScanResult` — File-based pattern scan result + +> Header: `omath/utility/section_scan_result.hpp` +> Namespace: `omath` +> Depends on: ``, `` + +`SectionScanResult` is the return type for file-based pattern scans across all binary formats (PE, ELF, Mach-O). It carries the section's virtual and raw base addresses together with the offset to the matched pattern. + +--- + +## API + +```cpp +namespace omath { + +struct SectionScanResult final { + std::uintptr_t virtual_base_addr; // virtual address base of the scanned section + std::uintptr_t raw_base_addr; // file offset of the section start + std::ptrdiff_t target_offset; // offset from section base to the first matched byte +}; + +} // namespace omath +``` + +--- + +## Computing addresses from a result + +```cpp +omath::SectionScanResult res = /* ... */; + +// Virtual address of the match (as if the binary were loaded at its preferred base) +auto va_hit = res.virtual_base_addr + res.target_offset; + +// Raw file offset of the match +auto raw_hit = res.raw_base_addr + res.target_offset; +``` + +--- + +## Notes + +* `virtual_base_addr` is computed from the section header (RVA for PE, `sh_addr` for ELF, `addr` for Mach-O). +* `raw_base_addr` is the file offset where the section data begins on disk. +* `target_offset` is always relative to the section base — add it to either address to locate the match. + +--- + +## See also + +* [`omath::PePatternScanner`](pe_pattern_scan.md) — PE (Windows) binary scanner. +* [`omath::ElfPatternScanner`](elf_pattern_scan.md) — ELF (Linux) binary scanner. +* [`omath::MachOPatternScanner`](macho_pattern_scan.md) — Mach-O (macOS) binary scanner. +* [`omath::PatternScanner`](pattern_scan.md) — raw buffer/iterator scanning. + +--- + +*Last updated: Feb 2026* diff --git a/mkdocs.yml b/mkdocs.yml index c40b40d..cd9bdcd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,7 @@ site_name: OMATH Docs theme: name: darkly extra_css: + - styles/fonts.css - styles/center.css - styles/custom-header.css - styles/links.css \ No newline at end of file