From 99817aeb5dc89a3866b9781642dab703113a05b6 Mon Sep 17 00:00:00 2001
From: Cole Munz <145523609+munzzyy@users.noreply.github.com>
Date: Tue, 14 Jul 2026 05:23:03 -0500
Subject: [PATCH] docs: document the YR_RE_SCAN_LIMIT regular expression scan
 limit (#2223)

Fixes #2194.

The regexp engines cap how much data they scan at `YR_RE_SCAN_LIMIT` (4096 bytes, defined in `libyara/include/yara/limits.h`), so a match that needs more than that simply isn't reported. @plusvic pointed at the constant in the issue thread, but the limit isn't mentioned anywhere in the docs, which was the reporter's actual complaint: rules with wide wildcards fail silently and there's nothing in the manual explaining why.

This adds a warning box to the "Regular expressions" section of writingrules.rst stating the default limit, the silent-miss behavior, and that it can be raised at compile time.

Checked against HEAD (fa372eb) before writing the note:

- built yara and ran `/foo.*bar/` over a file with `foo` and `bar` 4000 bytes apart (matches) and one with them 5000 bytes apart (no match, no error, exit 0)
- rebuilt with `CPPFLAGS='-DYR_RE_SCAN_LIMIT=8192'`: the 5000-byte gap now matches and a 9000-byte one doesn't, so the compile-time override wording is accurate
- sphinx-build runs with no new warnings and the box renders at the end of the regexp section
---
 docs/writingrules.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/writingrules.rst b/docs/writingrules.rst
index bdad0191..439fae40 100644
--- a/docs/writingrules.rst
+++ b/docs/writingrules.rst
@@ -717,6 +717,16 @@ Starting with version 3.3.0 these zero-width assertions are also recognized:
    * - ``\B``
      - Match except at a word boundary
 
+.. warning:: The regular expression engine scans a limited amount of data
+    while evaluating a match. This limit is 4096 bytes by default and is
+    controlled by the ``YR_RE_SCAN_LIMIT`` constant defined in
+    *libyara/include/yara/limits.h*. A match that would require scanning
+    beyond this limit is not reported and no error is raised, which usually
+    shows up with wildcards or large repetitions: a regular expression like
+    ``/foo.*bar/`` won't match if *foo* and *bar* are separated by more than
+    4096 bytes. If you need a larger limit you can define
+    ``YR_RE_SCAN_LIMIT`` at compile time.
+
 
 Private strings
 ---------------