---
name: "pcre_exec"
section: "3"
platform: "linux"
package: "pcre"
version: "8.45-5"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pcre_exec"
---

# pcre\_exec(3)

Perl-compatible regular expressions

## NAME

PCRE - Perl-compatible regular expressions

## SYNOPSIS

**#include \<pcre.h\>**

```
int pcre_exec(const pcre *code, const pcre_extra *extra,
     const char *subject, int length, int startoffset,
     int options, int *ovector, int ovecsize);

int pcre16_exec(const pcre16 *code, const pcre16_extra *extra,
     PCRE_SPTR16 subject, int length, int startoffset,
     int options, int *ovector, int ovecsize);

int pcre32_exec(const pcre32 *code, const pcre32_extra *extra,
     PCRE_SPTR32 subject, int length, int startoffset,
     int options, int *ovector, int ovecsize);
```

## 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 captured substrings. Its arguments are:

  *code*         Points to the compiled pattern\
   *extra*        Points to an associated **pcre\[16\|32\]\_extra** structure,\
                  or is NULL\
   *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\
   *ovector*      Points to a vector of ints for result offsets\
   *ovecsize*     Number of elements in the vector (a multiple of 3)

The units for *length* and *startoffset* are bytes for **pcre\_exec()**, 16-bit data items for **pcre16\_exec()**, and 32-bit items for **pcre32\_exec()**. The options are:

  PCRE\_ANCHORED          Match only at the first position\
   PCRE\_BSR\_ANYCRLF       \\R matches only CR, LF, or CRLF\
   PCRE\_BSR\_UNICODE       \\R matches all Unicode line endings\
   PCRE\_NEWLINE\_ANY       Recognize any Unicode newline sequence\
   PCRE\_NEWLINE\_ANYCRLF   Recognize CR, LF, & CRLF as newline sequences\
   PCRE\_NEWLINE\_CR        Recognize CR as the only newline sequence\
   PCRE\_NEWLINE\_CRLF      Recognize CRLF as the only newline sequence\
   PCRE\_NEWLINE\_LF        Recognize LF as the only newline sequence\
   PCRE\_NOTBOL            Subject string is not the beginning of a line\
   PCRE\_NOTEOL            Subject string is not the end of a line\
   PCRE\_NOTEMPTY          An empty string is not a valid match\
   PCRE\_NOTEMPTY\_ATSTART  An empty string at the start of the subject\
                            is not a valid match\
   PCRE\_NO\_START\_OPTIMIZE Do not do "start-match" optimizations\
   PCRE\_NO\_UTF16\_CHECK    Do not check the subject for UTF-16\
                            validity (only relevant if PCRE\_UTF16\
                            was set at compile time)\
   PCRE\_NO\_UTF32\_CHECK    Do not check the subject for UTF-32\
                            validity (only relevant if PCRE\_UTF32\
                            was set at compile time)\
   PCRE\_NO\_UTF8\_CHECK     Do not check the subject for UTF-8\
                            validity (only relevant if PCRE\_UTF8\
                            was set at compile time)\
   PCRE\_PARTIAL           ) Return PCRE\_ERROR\_PARTIAL for a partial\
   PCRE\_PARTIAL\_SOFT      )   match if no full matches are found\
   PCRE\_PARTIAL\_HARD      Return PCRE\_ERROR\_PARTIAL for a partial match\
                            if that is found before a full match

For details of partial matching, see the **pcrepartial** page. A **pcre\_extra** structure contains the following fields:

  *flags*            Bits indicating which fields are set\
   *study\_data*       Opaque data from **pcre\[16\|32\]\_study()**\
   *match\_limit*      Limit on internal resource use\
   *match\_limit\_recursion*  Limit on internal recursion depth\
   *callout\_data*     Opaque data passed back to callouts\
   *tables*           Points to character tables or is NULL\
   *mark*             For passing back a \*MARK pointer\
   *executable\_jit*   Opaque data from JIT compilation

The flag bits are PCRE\_EXTRA\_STUDY\_DATA, PCRE\_EXTRA\_MATCH\_LIMIT, PCRE\_EXTRA\_MATCH\_LIMIT\_RECURSION, PCRE\_EXTRA\_CALLOUT\_DATA, PCRE\_EXTRA\_TABLES, PCRE\_EXTRA\_MARK and PCRE\_EXTRA\_EXECUTABLE\_JIT.

There is a complete description of the PCRE native API in the **pcreapi** page and a description of the POSIX API in the **pcreposix** page.