PCRE2\_MATCH(3) Library Functions Manual PCRE2\_MATCH(3)

# [NAME](#NAME)

PCRE2 - Perl-compatible regular expressions (revised API)

# [SYNOPSIS](#SYNOPSIS)

**#include <pcre2.h>**

```
int 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 *mcontext);
```

# [DESCRIPTION](#DESCRIPTION)

This function matches a compiled regular expression against a given subject string, using a matching algorithm that is similar to Perl's. It returns offsets to what it has matched and to captured substrings via the **match\_data** block, which can be processed by functions with names that start with **pcre2\_get\_ovector\_...()** or **pcre2\_substring\_...()**. The return from **pcre2\_match()** is one more than the highest numbered capturing pair that has been set (for example, 1 if there are no captures), zero if the vector of offsets is too small, or a negative error code for no match and other errors. The function arguments are:

*code* Points to the compiled pattern  
*subject* Points to the subject string  
*length* Length of the subject string  
*startoffset* Offset in the subject at which to start matching  
*options* Option bits  
*match\_data* Points to a match data block, for results  
*mcontext* Points to a match context, or is NULL

A match context is needed only if you want to:

Set up a callout function  
Set a matching offset limit  
Change the heap memory limit  
Change the backtracking match limit  
Change the backtracking depth limit  
Set custom memory management specifically for the match

The *length* and *startoffset* values are code units, not characters. The length may be given as PCRE2\_ZERO\_TERMINATED for a subject that is terminated by a binary zero code unit. The options are:

PCRE2\_ANCHORED Match only at the first position  
PCRE2\_COPY\_MATCHED\_SUBJECT  
On success, make a private subject copy  
PCRE2\_DISABLE\_RECURSELOOP\_CHECK  
Only useful in rare cases; use with care  
PCRE2\_ENDANCHORED Pattern can match only at end of subject  
PCRE2\_NOTBOL Subject string is not the beginning of a line  
PCRE2\_NOTEOL Subject string is not the end of a line  
PCRE2\_NOTEMPTY An empty string is not a valid match  
PCRE2\_NOTEMPTY\_ATSTART An empty string at the start of the subject  
is not a valid match  
PCRE2\_NO\_JIT Do not use JIT matching  
PCRE2\_NO\_UTF\_CHECK Do not check the subject for UTF  
validity (only relevant if PCRE2\_UTF  
was set at compile time)  
PCRE2\_PARTIAL\_HARD Return PCRE2\_ERROR\_PARTIAL for a partial  
match even if there is a full match  
PCRE2\_PARTIAL\_SOFT Return PCRE2\_ERROR\_PARTIAL for a partial  
match if no full matches are found

For details of partial matching, see the **pcre2partial** page. There is a complete description of the PCRE2 native API in the **pcre2api** page and a description of the POSIX API in the **pcre2posix** page.

27 January 2024 PCRE2 10.49

---

Document: pcre2_match(3) from pcre2 10.49-r2 (Chainguard OS)
Source: https://github.com/PCRE2Project/pcre2.git