pcre2.h File Reference

🔍 Centralized PCRE2 singleton pattern for efficient regex compilation More...

Go to the source code of this file.

Macros
#define	PCRE2_CODE_UNIT_WIDTH   8

Typedefs
typedef struct pcre2_singleton	pcre2_singleton_t
	Opaque handle to a compiled PCRE2 regex singleton.

Functions
pcre2_singleton_t *	asciichat_pcre2_singleton_compile (const char *pattern, uint32_t flags)
	Compile and cache a PCRE2 regex pattern with thread-safe singleton semantics.
pcre2_code *	asciichat_pcre2_singleton_get_code (pcre2_singleton_t *singleton)
	Get the compiled pcre2_code from a singleton handle.
bool	asciichat_pcre2_singleton_is_initialized (pcre2_singleton_t *singleton)
	Check if a singleton was successfully initialized.
void	asciichat_pcre2_singleton_free (pcre2_singleton_t *singleton)
	Free a PCRE2 singleton and its resources.
void	asciichat_pcre2_cleanup_all (void)
	Free all PCRE2 singletons.
char *	asciichat_pcre2_extract_named_group (pcre2_code *regex, pcre2_match_data *match_data, const char *group_name, const char *subject)
	Extract named substring from PCRE2 match data.
char *	asciichat_pcre2_extract_group (pcre2_match_data *match_data, int group_num, const char *subject)
	Extract numbered capture group as allocated string.
const char *	asciichat_pcre2_extract_group_ptr (pcre2_match_data *match_data, int group_num, const char *subject, size_t *out_len)
	Extract numbered capture group as pointer into subject (non-allocating)
bool	asciichat_pcre2_extract_group_ulong (pcre2_match_data *match_data, int group_num, const char *subject, unsigned long *out_value)
	Extract numbered capture group and convert to unsigned long.
int	asciichat_pcre2_match (const pcre2_code *code, PCRE2_SPTR subject, PCRE2_SIZE length, PCRE2_SIZE startoffset, uint32_t options, pcre2_match_data *match_data, pcre2_match_context *context)

Detailed Description

🔍 Centralized PCRE2 singleton pattern for efficient regex compilation

Provides thread-safe lazy initialization of PCRE2 compiled regexes with automatic JIT compilation. Each regex pattern is compiled once per process on first use, enabling safe concurrent reads with zero initialization overhead for unused patterns.

Definition in file pcre2.h.

Macro Definition Documentation

PCRE2_CODE_UNIT_WIDTH

#define PCRE2_CODE_UNIT_WIDTH   8

Definition at line 14 of file pcre2.h.

Typedef Documentation

pcre2_singleton_t

typedef struct pcre2_singleton pcre2_singleton_t

Opaque handle to a compiled PCRE2 regex singleton.

Represents a thread-safe compiled regex with JIT optimization. Handles are returned by pcre2_singleton_compile() and are valid for the lifetime of the program.

Definition at line 25 of file pcre2.h.

Function Documentation

asciichat_pcre2_cleanup_all()

void asciichat_pcre2_cleanup_all

(

void

)

Free all PCRE2 singletons.

Automatically frees all singletons created with asciichat_pcre2_singleton_compile(). Safe to call multiple times (idempotent). Should be called once during shutdown.

Free all PCRE2 singletons.

Walks the global registry and frees all singletons. Safe to call multiple times (idempotent). Should be called once during shutdown.

Definition at line 214 of file pcre2.c.

                                       {
  if (!lifecycle_shutdown(&g_registry_lc)) {
    return; /* No singletons were ever created or already cleaned up */
  }
 
  /* Check if already cleaned up */
  if (g_singleton_registry == NULL) {
    return;
  }
 
  pcre2_singleton_t *current = g_singleton_registry;
 
  /* Clear registry first to prevent re-entry */
  g_singleton_registry = NULL;
 
  /* Now free all singletons */
  while (current) {
    pcre2_singleton_t *next = current->next;
 
    /* Free compiled code */
    pcre2_code *code = (pcre2_code *)(uintptr_t)atomic_load_u64(&current->code);
    if (code) {
      pcre2_code_free(code);
      atomic_store_u64(&current->code, 0);
    }
 
    /* Free JIT stack */
    if (current->jit_stack) {
      pcre2_jit_stack_free(current->jit_stack);
      current->jit_stack = NULL;
    }
 
    /* Free pattern string */
    SAFE_FREE(current->pattern);
 
    /* Do not free the singleton struct itself - static pointers in other
     * modules (path.c, url.c, etc.) may still reference it during late
     * shutdown logging. The struct is tiny and harmless to leak at exit. */
 
    current = next;
  }
}

References atomic_load_u64(), atomic_store_u64(), pcre2_singleton::code, pcre2_singleton::jit_stack, lifecycle_shutdown(), pcre2_singleton::next, pcre2_singleton::pattern, and SAFE_FREE.

Referenced by asciichat_shared_destroy(), and main().

asciichat_pcre2_extract_group()

char * asciichat_pcre2_extract_group	(	pcre2_match_data *	match_data,
		int	group_num,
		const char *	subject
	)

Extract numbered capture group as allocated string.

Extracts a numbered capture group from match data and returns an allocated string. The caller is responsible for freeing the returned string with SAFE_FREE().

Parameters

match_data	Match data from pcre2_match() or pcre2_jit_match()
group_num	Capture group number (1-based, 0 = entire match)
subject	Original subject string that was matched

Returns

Allocated string containing the matched substring, or NULL if group not matched

Example:

char *foundation = asciichat_pcre2_extract_group(match_data, 1, line);
if (foundation) {
  // Use foundation...
  SAFE_FREE(foundation);
}

Definition at line 308 of file pcre2.c.

                                                                                                      {
  if (!match_data || !subject || group_num < 0) {
    return NULL;
  }
 
  /* Get ovector (output vector with match offsets) */
  PCRE2_SIZE *ovector = pcre2_get_ovector_pointer(match_data);
  PCRE2_SIZE start = ovector[2 * group_num];
  PCRE2_SIZE end = ovector[2 * group_num + 1];
 
  if (start == PCRE2_UNSET || end == PCRE2_UNSET) {
    return NULL; /* Group not matched */
  }
 
  /* Allocate and copy substring */
  size_t len = end - start;
  char *result = SAFE_MALLOC(len + 1, char *);
  if (!result) {
    log_error("asciichat_pcre2_extract_group: failed to allocate %zu bytes", len + 1);
    return NULL;
  }
 
  memcpy(result, subject + start, len);
  result[len] = '\0';
 
  return result;
}

References log_error, and SAFE_MALLOC.

asciichat_pcre2_extract_group_ptr()

const char * asciichat_pcre2_extract_group_ptr	(	pcre2_match_data *	match_data,
		int	group_num,
		const char *	subject,
		size_t *	out_len
	)

Extract numbered capture group as pointer into subject (non-allocating)

Returns a pointer to the matched substring within the original subject string. No memory allocation occurs - the returned pointer is only valid as long as the subject string remains valid.

Parameters

match_data	Match data from pcre2_match() or pcre2_jit_match()
group_num	Capture group number (1-based, 0 = entire match)
subject	Original subject string that was matched
out_len	Output parameter for substring length

Returns

Pointer to matched substring within subject, or NULL if group not matched

Example:

size_t len;
const char *video_id = asciichat_pcre2_extract_group_ptr(match_data, 1, url, &len);
if (video_id) {
  printf("Video ID: %.*s\n", (int)len, video_id);
}

Definition at line 339 of file pcre2.c.

                                                               {
  if (!match_data || !subject || !out_len || group_num < 0) {
    return NULL;
  }
 
  /* Get ovector (output vector with match offsets) */
  PCRE2_SIZE *ovector = pcre2_get_ovector_pointer(match_data);
  PCRE2_SIZE start = ovector[2 * group_num];
  PCRE2_SIZE end = ovector[2 * group_num + 1];
 
  if (start == PCRE2_UNSET || end == PCRE2_UNSET) {
    return NULL; /* Group not matched */
  }
 
  *out_len = end - start;
  return subject + start;
}

Referenced by stun_servers_parse().

asciichat_pcre2_extract_group_ulong()

bool asciichat_pcre2_extract_group_ulong	(	pcre2_match_data *	match_data,
		int	group_num,
		const char *	subject,
		unsigned long *	out_value
	)

Extract numbered capture group and convert to unsigned long.

Extracts a numbered capture group and converts it to an unsigned long integer. Handles extraction and parsing in one step.

Parameters

match_data	Match data from pcre2_match() or pcre2_jit_match()
group_num	Capture group number (1-based, 0 = entire match)
subject	Original subject string that was matched
out_value	Output parameter for parsed integer value

Returns

true if extraction and parsing succeeded, false otherwise

Example:

unsigned long component_id;
if (asciichat_pcre2_extract_group_ulong(match_data, 2, line, &component_id)) {
  candidate->component_id = (uint32_t)component_id;
}

Definition at line 361 of file pcre2.c.

                                                                   {
  if (!match_data || !subject || !out_value || group_num < 0) {
    return false;
  }
 
  /* Get ovector (output vector with match offsets) */
  PCRE2_SIZE *ovector = pcre2_get_ovector_pointer(match_data);
  PCRE2_SIZE start = ovector[2 * group_num];
  PCRE2_SIZE end = ovector[2 * group_num + 1];
 
  if (start == PCRE2_UNSET || end == PCRE2_UNSET) {
    return false; /* Group not matched */
  }
 
  /* Extract substring into temporary buffer */
  size_t len = end - start;
  if (len == 0 || len > 63) { /* Sanity check for reasonable number length */
    return false;
  }
 
  char temp[64];
  memcpy(temp, subject + start, len);
  temp[len] = '\0';
 
  /* Parse as unsigned long */
  char *endptr;
  errno = 0;
  unsigned long value = strtoul(temp, &endptr, 10);
 
  if (errno != 0 || endptr == temp || *endptr != '\0') {
    return false; /* Parse failed */
  }
 
  *out_value = value;
  return true;
}

References errno.

asciichat_pcre2_extract_named_group()

char * asciichat_pcre2_extract_named_group	(	pcre2_code *	regex,
		pcre2_match_data *	match_data,
		const char *	group_name,
		const char *	subject
	)

Extract named substring from PCRE2 match data.

Extracts a named capture group from match data and returns an allocated string. The caller is responsible for freeing the returned string with SAFE_FREE().

Parameters

regex	Compiled PCRE2 regex with named groups
match_data	Match data from pcre2_match() or pcre2_jit_match()
group_name	Name of the capture group to extract
subject	Original subject string that was matched

Returns

Allocated string containing the matched substring, or NULL if group not matched

Example:

pcre2_match_data *match_data = pcre2_match_data_create_from_pattern(regex, NULL);
int rc = pcre2_jit_match(regex, (PCRE2_SPTR)subject, strlen(subject), 0, 0, match_data, NULL);
if (rc >= 0) {
  char *value = asciichat_pcre2_extract_named_group(regex, match_data, "fieldname", subject);
  if (value) {
    // Use value...
    SAFE_FREE(value);
  }
}
pcre2_match_data_free(match_data);

Extracts a named capture group from match data and returns an allocated string. The caller is responsible for freeing the returned string with SAFE_FREE().

Parameters

regex	Compiled PCRE2 regex with named groups
match_data	Match data from pcre2_match() or pcre2_jit_match()
group_name	Name of the capture group to extract
subject	Original subject string that was matched

Returns

Allocated string containing the matched substring, or NULL if group not matched

Definition at line 269 of file pcre2.c.

                                                               {
  if (!regex || !match_data || !group_name || !subject) {
    log_error("pcre2_extract_named_group: invalid parameters");
    return NULL;
  }
 
  /* Get group number from name */
  int group_number = pcre2_substring_number_from_name(regex, (PCRE2_SPTR)group_name);
  if (group_number < 0) {
    return NULL; /* Group doesn't exist */
  }
 
  /* Get ovector (output vector with match offsets) */
  PCRE2_SIZE *ovector = pcre2_get_ovector_pointer(match_data);
  PCRE2_SIZE start = ovector[2 * group_number];
  PCRE2_SIZE end = ovector[2 * group_number + 1];
 
  if (start == PCRE2_UNSET || end == PCRE2_UNSET) {
    return NULL; /* Group not matched */
  }
 
  /* Allocate and copy substring */
  size_t len = end - start;
  char *result = SAFE_MALLOC(len + 1, char *);
  if (!result) {
    log_error("pcre2_extract_named_group: failed to allocate %zu bytes", len + 1);
    return NULL;
  }
 
  memcpy(result, subject + start, len);
  result[len] = '\0';
 
  return result;
}

References log_error, and SAFE_MALLOC.

Referenced by crypto_regex_extract_gpg_keygrip(), crypto_regex_extract_pem_base64(), crypto_regex_match_known_hosts(), crypto_regex_match_public_key(), and url_parse().

asciichat_pcre2_match()

int asciichat_pcre2_match	(	const pcre2_code *	code,
		PCRE2_SPTR	subject,
		PCRE2_SIZE	length,
		PCRE2_SIZE	startoffset,
		uint32_t	options,
		pcre2_match_data *	match_data,
		pcre2_match_context *	context
	)

Match with the JIT fast path, using the interpreter when JIT is unavailable. Returns the native PCRE2 capture count or negative PCRE2 error code.

Definition at line 399 of file pcre2.c.

                                                                                                        {
  int result = pcre2_jit_match(code, subject, length, startoffset, options, match_data, context);
  if (result == PCRE2_ERROR_JIT_BADOPTION || result == PCRE2_ERROR_JIT_STACKLIMIT)
    return pcre2_match(code, subject, length, startoffset, options | PCRE2_NO_JIT, match_data, context);
  return result;
}

References pcre2_singleton::code.

Referenced by parse_port(), url_is_valid(), and url_parse().

asciichat_pcre2_singleton_compile()

pcre2_singleton_t * asciichat_pcre2_singleton_compile	(	const char *	pattern,
		uint32_t	flags
	)

Compile and cache a PCRE2 regex pattern with thread-safe singleton semantics.

Allocates a singleton structure to store the pattern and flags. Actual compilation happens lazily on first call to asciichat_pcre2_singleton_get_code().

This function returns immediately without doing expensive regex compilation. Compilation happens later when the code is first accessed.

Parameters

pattern	PCRE2 regex pattern (e.g., "^[a-z]+$")
flags	PCRE2 compile flags (e.g., PCRE2_CASELESS | PCRE2_MULTILINE)

Returns

Opaque singleton handle, or NULL on allocation failure

Example:

static pcre2_singleton_t *g_email_regex = NULL;
 
void init_validators() {
  g_email_regex = asciichat_pcre2_singleton_compile(
      "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$",
      PCRE2_CASELESS
  );
}

Allocates a singleton structure and stores the pattern/flags. The actual compilation happens lazily on first call to asciichat_pcre2_singleton_get_code().

This function returns immediately without doing expensive regex compilation.

Parameters

pattern	PCRE2 regex pattern string
flags	PCRE2 compile flags

Returns

Opaque singleton handle, or NULL on allocation failure

< Per-object lifecycle for lazy compilation

Definition at line 47 of file pcre2.c.

                                                                                          {
  if (!pattern) {
    log_error("PCRE2 singleton: pattern is NULL");
    return NULL;
  }
 
  /* Allocate singleton structure */
  pcre2_singleton_t *singleton = SAFE_MALLOC(sizeof(pcre2_singleton_t), pcre2_singleton_t *);
  if (!singleton) {
    log_error("PCRE2 singleton: failed to allocate singleton structure");
    return NULL;
  }
 
  /* Copy pattern string to avoid stack-use-after-return bugs */
  size_t pattern_len = strlen(pattern);
  singleton->pattern = SAFE_MALLOC(pattern_len + 1, char *);
  if (!singleton->pattern) {
    log_error("PCRE2 singleton: failed to allocate pattern buffer");
    SAFE_FREE(singleton);
    return NULL;
  }
  memcpy(singleton->pattern, pattern, pattern_len + 1);
 
  /* Initialize fields */
  singleton->lc = (lifecycle_t)LIFECYCLE_INIT; 
  atomic_store_u64(&singleton->code, 0);
  singleton->jit_stack = NULL;
  singleton->flags = flags;
 
  /* Register singleton in global list for automatic cleanup */
  singleton->next = g_singleton_registry;
  g_singleton_registry = singleton;
 
  /* Mark registry as initialized (one-time per process) */
  lifecycle_init(&g_registry_lc, "pcre2_registry");
 
  return singleton;
}

References atomic_store_u64(), pcre2_singleton::code, pcre2_singleton::flags, pcre2_singleton::jit_stack, pcre2_singleton::lc, LIFECYCLE_INIT, lifecycle_init(), log_error, pcre2_singleton::next, pcre2_singleton::pattern, SAFE_FREE, and SAFE_MALLOC.

Referenced by grep_init(), log_search_enter_mode(), log_search_exit_mode(), log_search_handle_key(), and log_search_init().

asciichat_pcre2_singleton_free()

void asciichat_pcre2_singleton_free

(

pcre2_singleton_t *

singleton

)

Free a PCRE2 singleton and its resources.

Frees the compiled regex code, JIT stack, and singleton structure. After calling this, the singleton pointer is invalid and should not be used.

Parameters

singleton

Handle returned by asciichat_pcre2_singleton_compile()

Definition at line 185 of file pcre2.c.

                                                                  {
  if (!singleton) {
    return;
  }
 
  /* Free compiled code if it exists */
  pcre2_code *code = (pcre2_code *)(uintptr_t)atomic_load_u64(&singleton->code);
  if (code) {
    pcre2_code_free(code);
  }
 
  /* Free JIT stack if it exists */
  if (singleton->jit_stack) {
    pcre2_jit_stack_free(singleton->jit_stack);
  }
 
  /* Free pattern string */
  SAFE_FREE(singleton->pattern);
 
  /* Free the singleton structure itself */
  SAFE_FREE(singleton);
}

References atomic_load_u64(), pcre2_singleton::code, pcre2_singleton::jit_stack, pcre2_singleton::pattern, and SAFE_FREE.

asciichat_pcre2_singleton_get_code()

pcre2_code * asciichat_pcre2_singleton_get_code

(

pcre2_singleton_t *

singleton

)

Get the compiled pcre2_code from a singleton handle.

Lazily compiles the regex on first call. Subsequent calls return the cached code. Thread-safe: multiple threads can call this concurrently; compilation happens once.

Parameters

singleton

Handle returned by asciichat_pcre2_singleton_compile()

Returns

Compiled regex code (read-only), or NULL if compilation failed

Lazily compiles the regex on first call. Fast path (subsequent calls) only reads a single atomic variable with no synchronization overhead.

Thread-safe: If multiple threads call this concurrently on first use, only one will compile; others will wait for the code to become non-NULL.

Parameters

singleton

Handle returned by asciichat_pcre2_singleton_compile()

Returns

Compiled regex code (read-only), or NULL if compilation failed

Definition at line 98 of file pcre2.c.

                                                                             {
  if (!singleton) {
    return NULL;
  }
 
  /* Fast path: check if already compiled (lock-free atomic load, no mutex) */
  pcre2_code *code = (pcre2_code *)(uintptr_t)atomic_load_u64(&singleton->code);
  if (code != NULL) {
    return code;
  }
 
  /* Check if compilation already attempted via lifecycle state */
  if (lifecycle_is_initialized(&singleton->lc)) {
    /* Already initialized but code is NULL - compilation failed previously */
    return NULL;
  }
 
  /* Try to win the compilation race using lifecycle_t */
  if (!lifecycle_init(&singleton->lc, "pcre2_pattern")) {
    /* Lost race - someone else is compiling or already compiled. Spin for their result. */
    while ((pcre2_code *)(uintptr_t)atomic_load_u64(&singleton->code) == NULL &&
           lifecycle_is_initialized(&singleton->lc)) {
      /* Spin-wait for compiler to finish */
    }
    return (pcre2_code *)(uintptr_t)atomic_load_u64(&singleton->code);
  }
 
  /* Slow path: we won the race, need to compile. */
  int errornumber;
  PCRE2_SIZE erroroffset;
 
  code = pcre2_compile((PCRE2_SPTR8)singleton->pattern, PCRE2_ZERO_TERMINATED, singleton->flags, &errornumber,
                       &erroroffset, NULL);
 
  if (!code) {
    PCRE2_UCHAR error_buf[256];
    pcre2_get_error_message(errornumber, error_buf, sizeof(error_buf));
    log_warn("Failed to compile PCRE2 regex at offset %zu: %s", erroroffset, (const char *)error_buf);
    /* Mark compilation as attempted (failed) by moving to INITIALIZED state */
    lifecycle_init_commit(&singleton->lc);
    return NULL;
  }
 
  /* Attempt JIT compilation (non-fatal if fails) */
  int jit_rc = PCRE2_ERROR_JIT_BADOPTION;
  if (!SAFE_GETENV("ASCII_CHAT_PCRE2_DISABLE_JIT")) {
    jit_rc = pcre2_jit_compile(code, PCRE2_JIT_COMPLETE);
  }
  if (jit_rc < 0) {
    log_debug("PCRE2 JIT compilation not available (code %d), using interpreted mode", jit_rc);
  } else {
    /* Create JIT stack for pattern execution */
    singleton->jit_stack = pcre2_jit_stack_create(32 * 1024, 512 * 1024, NULL);
    if (!singleton->jit_stack) {
      log_warn("Failed to create JIT stack for PCRE2 regex");
    }
  }
 
  /* Store compiled code (atomic, so subsequent calls see it immediately) */
  atomic_store_u64(&singleton->code, (uint64_t)(uintptr_t)code);
  /* Mark compilation as completed by moving to INITIALIZED state */
  lifecycle_init_commit(&singleton->lc);
 
  return code;
}

References atomic_load_u64(), atomic_store_u64(), pcre2_singleton::code, pcre2_singleton::flags, pcre2_singleton::jit_stack, pcre2_singleton::lc, lifecycle_init(), lifecycle_init_commit(), lifecycle_is_initialized(), log_debug, log_warn, pcre2_singleton::pattern, and SAFE_GETENV.

Referenced by grep_highlight(), grep_highlight_colored(), grep_init(), grep_should_output(), log_search_enter_mode(), log_search_exit_mode(), log_search_gather_and_filter_logs(), log_search_get_match_info(), and log_search_handle_key().

asciichat_pcre2_singleton_is_initialized()

bool asciichat_pcre2_singleton_is_initialized

(

pcre2_singleton_t *

singleton

)

Check if a singleton was successfully initialized.

Parameters

singleton

Handle returned by asciichat_pcre2_singleton_compile()

Returns

true if regex compiled successfully, false otherwise

Definition at line 170 of file pcre2.c.

                                                                            {
  if (!singleton) {
    return false;
  }
  return (pcre2_code *)(uintptr_t)atomic_load_u64(&singleton->code) != NULL;
}

References atomic_load_u64(), and pcre2_singleton::code.