---
name: "pcre2_match"
section: "3"
platform: "linux"
package: "pcre2"
version: "10.49-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pcre2_match"
---

# pcre2\_match(3)

Perl-compatible regular expressions (revised API)

## NAME

PCRE2 - Perl-compatible regular expressions (revised API)

## 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

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.