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

# pcre2\_substring\_copy\_bynumber(3)

Perl-compatible regular expressions (revised API)

## NAME

PCRE2 - Perl-compatible regular expressions (revised API)

## SYNOPSIS

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

```
int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
  uint32_t number, PCRE2_UCHAR *buffer,
  PCRE2_SIZE *bufflen);
```

## DESCRIPTION

This is a convenience function for extracting a captured substring into a given buffer. The arguments are:

  *match\_data*    The match data block for the match\
   *number*        Number of the required substring\
   *buffer*        Buffer to receive the string\
   *bufflen*       Length of buffer

The *bufflen* variable is updated with the length of the extracted string, excluding the terminating zero. The yield of the function is zero for success or one of the following error numbers:

  PCRE2\_ERROR\_NOSUBSTRING   there are no groups of that number\
   PCRE2\_ERROR\_UNAVAILBLE    the ovector was too small for that group\
   PCRE2\_ERROR\_UNSET         the group did not participate in the match\
   PCRE2\_ERROR\_NOMEMORY      the buffer is too small

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.