Elliott Hughes | 0c26e19 | 2019-08-07 12:24:46 -0700 | [diff] [blame] | 1 | .TH PCRE2_MATCH 3 "16 October 2018" "PCRE2 10.33" |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 2 | .SH NAME |
| 3 | PCRE2 - Perl-compatible regular expressions (revised API) |
| 4 | .SH SYNOPSIS |
| 5 | .rs |
| 6 | .sp |
| 7 | .B #include <pcre2.h> |
| 8 | .PP |
| 9 | .nf |
| 10 | .B int pcre2_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, |
| 11 | .B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," |
| 12 | .B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," |
| 13 | .B " pcre2_match_context *\fImcontext\fP);" |
| 14 | .fi |
| 15 | . |
| 16 | .SH DESCRIPTION |
| 17 | .rs |
| 18 | .sp |
| 19 | This function matches a compiled regular expression against a given subject |
| 20 | string, using a matching algorithm that is similar to Perl's. It returns |
Elliott Hughes | 9bc971b | 2018-07-27 13:23:14 -0700 | [diff] [blame] | 21 | offsets to what it has matched and to captured substrings via the |
| 22 | \fBmatch_data\fP block, which can be processed by functions with names that |
| 23 | start with \fBpcre2_get_ovector_...()\fP or \fBpcre2_substring_...()\fP. The |
| 24 | return from \fBpcre2_match()\fP is one more than the highest numbered capturing |
| 25 | pair that has been set (for example, 1 if there are no captures), zero if the |
| 26 | vector of offsets is too small, or a negative error code for no match and other |
| 27 | errors. The function arguments are: |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 28 | .sp |
| 29 | \fIcode\fP Points to the compiled pattern |
| 30 | \fIsubject\fP Points to the subject string |
| 31 | \fIlength\fP Length of the subject string |
| 32 | \fIstartoffset\fP Offset in the subject at which to start matching |
| 33 | \fIoptions\fP Option bits |
| 34 | \fImatch_data\fP Points to a match data block, for results |
| 35 | \fImcontext\fP Points to a match context, or is NULL |
| 36 | .sp |
| 37 | A match context is needed only if you want to: |
| 38 | .sp |
| 39 | Set up a callout function |
Elliott Hughes | 9bc971b | 2018-07-27 13:23:14 -0700 | [diff] [blame] | 40 | Set a matching offset limit |
| 41 | Change the heap memory limit |
| 42 | Change the backtracking match limit |
| 43 | Change the backtracking depth limit |
| 44 | Set custom memory management specifically for the match |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 45 | .sp |
Elliott Hughes | 0c26e19 | 2019-08-07 12:24:46 -0700 | [diff] [blame] | 46 | The \fIlength\fP and \fIstartoffset\fP values are code units, not characters. |
| 47 | The length may be given as PCRE2_ZERO_TERMINATED for a subject that is |
| 48 | terminated by a binary zero code unit. The options are: |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 49 | .sp |
| 50 | PCRE2_ANCHORED Match only at the first position |
Elliott Hughes | 0c26e19 | 2019-08-07 12:24:46 -0700 | [diff] [blame] | 51 | PCRE2_COPY_MATCHED_SUBJECT |
| 52 | On success, make a private subject copy |
Elliott Hughes | 9bc971b | 2018-07-27 13:23:14 -0700 | [diff] [blame] | 53 | PCRE2_ENDANCHORED Pattern can match only at end of subject |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 54 | PCRE2_NOTBOL Subject string is not the beginning of a line |
| 55 | PCRE2_NOTEOL Subject string is not the end of a line |
| 56 | PCRE2_NOTEMPTY An empty string is not a valid match |
Elliott Hughes | 9bc971b | 2018-07-27 13:23:14 -0700 | [diff] [blame] | 57 | .\" JOIN |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 58 | PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject |
| 59 | is not a valid match |
Elliott Hughes | 9bc971b | 2018-07-27 13:23:14 -0700 | [diff] [blame] | 60 | PCRE2_NO_JIT Do not use JIT matching |
| 61 | .\" JOIN |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 62 | PCRE2_NO_UTF_CHECK Do not check the subject for UTF |
| 63 | validity (only relevant if PCRE2_UTF |
| 64 | was set at compile time) |
Elliott Hughes | 9bc971b | 2018-07-27 13:23:14 -0700 | [diff] [blame] | 65 | .\" JOIN |
| 66 | PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial |
| 67 | match even if there is a full match |
| 68 | .\" JOIN |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 69 | PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial |
Elliott Hughes | 653c210 | 2019-01-09 15:41:36 -0800 | [diff] [blame] | 70 | match if no full matches are found |
Janis Danisevskis | 112c9cc | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 71 | .sp |
| 72 | For details of partial matching, see the |
| 73 | .\" HREF |
| 74 | \fBpcre2partial\fP |
| 75 | .\" |
| 76 | page. There is a complete description of the PCRE2 native API in the |
| 77 | .\" HREF |
| 78 | \fBpcre2api\fP |
| 79 | .\" |
| 80 | page and a description of the POSIX API in the |
| 81 | .\" HREF |
| 82 | \fBpcre2posix\fP |
| 83 | .\" |
| 84 | page. |