Elliott Hughes | 4e19c8e | 2022-04-15 15:11:02 -0700 | [diff] [blame] | 1 | .TH PCRE2JIT 3 "30 November 2021" "PCRE2 10.40" |
Elliott Hughes | 5b80804 | 2021-10-01 10:56:10 -0700 | [diff] [blame] | 2 | .SH NAME |
| 3 | PCRE2 - Perl-compatible regular expressions (revised API) |
| 4 | .SH "PCRE2 JUST-IN-TIME COMPILER SUPPORT" |
| 5 | .rs |
| 6 | .sp |
| 7 | Just-in-time compiling is a heavyweight optimization that can greatly speed up |
| 8 | pattern matching. However, it comes at the cost of extra processing before the |
| 9 | match is performed, so it is of most benefit when the same pattern is going to |
| 10 | be matched many times. This does not necessarily mean many calls of a matching |
| 11 | function; if the pattern is not anchored, matching attempts may take place many |
| 12 | times at various positions in the subject, even for a single call. Therefore, |
| 13 | if the subject string is very long, it may still pay to use JIT even for |
| 14 | one-off matches. JIT support is available for all of the 8-bit, 16-bit and |
| 15 | 32-bit PCRE2 libraries. |
| 16 | .P |
| 17 | JIT support applies only to the traditional Perl-compatible matching function. |
| 18 | It does not apply when the DFA matching function is being used. The code for |
| 19 | this support was written by Zoltan Herczeg. |
| 20 | . |
| 21 | . |
| 22 | .SH "AVAILABILITY OF JIT SUPPORT" |
| 23 | .rs |
| 24 | .sp |
| 25 | JIT support is an optional feature of PCRE2. The "configure" option |
| 26 | --enable-jit (or equivalent CMake option) must be set when PCRE2 is built if |
| 27 | you want to use JIT. The support is limited to the following hardware |
| 28 | platforms: |
| 29 | .sp |
| 30 | ARM 32-bit (v5, v7, and Thumb2) |
| 31 | ARM 64-bit |
| 32 | IBM s390x 64 bit |
| 33 | Intel x86 32-bit and 64-bit |
| 34 | MIPS 32-bit and 64-bit |
| 35 | Power PC 32-bit and 64-bit |
| 36 | SPARC 32-bit |
| 37 | .sp |
| 38 | If --enable-jit is set on an unsupported platform, compilation fails. |
| 39 | .P |
| 40 | A program can tell if JIT support is available by calling \fBpcre2_config()\fP |
| 41 | with the PCRE2_CONFIG_JIT option. The result is 1 when JIT is available, and 0 |
| 42 | otherwise. However, a simple program does not need to check this in order to |
| 43 | use JIT. The API is implemented in a way that falls back to the interpretive |
| 44 | code if JIT is not available. For programs that need the best possible |
| 45 | performance, there is also a "fast path" API that is JIT-specific. |
| 46 | . |
| 47 | . |
| 48 | .SH "SIMPLE USE OF JIT" |
| 49 | .rs |
| 50 | .sp |
| 51 | To make use of the JIT support in the simplest way, all you have to do is to |
| 52 | call \fBpcre2_jit_compile()\fP after successfully compiling a pattern with |
| 53 | \fBpcre2_compile()\fP. This function has two arguments: the first is the |
| 54 | compiled pattern pointer that was returned by \fBpcre2_compile()\fP, and the |
| 55 | second is zero or more of the following option bits: PCRE2_JIT_COMPLETE, |
| 56 | PCRE2_JIT_PARTIAL_HARD, or PCRE2_JIT_PARTIAL_SOFT. |
| 57 | .P |
| 58 | If JIT support is not available, a call to \fBpcre2_jit_compile()\fP does |
| 59 | nothing and returns PCRE2_ERROR_JIT_BADOPTION. Otherwise, the compiled pattern |
| 60 | is passed to the JIT compiler, which turns it into machine code that executes |
| 61 | much faster than the normal interpretive code, but yields exactly the same |
| 62 | results. The returned value from \fBpcre2_jit_compile()\fP is zero on success, |
| 63 | or a negative error code. |
| 64 | .P |
| 65 | There is a limit to the size of pattern that JIT supports, imposed by the size |
| 66 | of machine stack that it uses. The exact rules are not documented because they |
| 67 | may change at any time, in particular, when new optimizations are introduced. |
| 68 | If a pattern is too big, a call to \fBpcre2_jit_compile()\fP returns |
| 69 | PCRE2_ERROR_NOMEMORY. |
| 70 | .P |
| 71 | PCRE2_JIT_COMPLETE requests the JIT compiler to generate code for complete |
| 72 | matches. If you want to run partial matches using the PCRE2_PARTIAL_HARD or |
| 73 | PCRE2_PARTIAL_SOFT options of \fBpcre2_match()\fP, you should set one or both |
| 74 | of the other options as well as, or instead of PCRE2_JIT_COMPLETE. The JIT |
| 75 | compiler generates different optimized code for each of the three modes |
| 76 | (normal, soft partial, hard partial). When \fBpcre2_match()\fP is called, the |
| 77 | appropriate code is run if it is available. Otherwise, the pattern is matched |
| 78 | using interpretive code. |
| 79 | .P |
| 80 | You can call \fBpcre2_jit_compile()\fP multiple times for the same compiled |
| 81 | pattern. It does nothing if it has previously compiled code for any of the |
| 82 | option bits. For example, you can call it once with PCRE2_JIT_COMPLETE and |
| 83 | (perhaps later, when you find you need partial matching) again with |
| 84 | PCRE2_JIT_COMPLETE and PCRE2_JIT_PARTIAL_HARD. This time it will ignore |
| 85 | PCRE2_JIT_COMPLETE and just compile code for partial matching. If |
| 86 | \fBpcre2_jit_compile()\fP is called with no option bits set, it immediately |
| 87 | returns zero. This is an alternative way of testing whether JIT is available. |
| 88 | .P |
| 89 | At present, it is not possible to free JIT compiled code except when the entire |
| 90 | compiled pattern is freed by calling \fBpcre2_code_free()\fP. |
| 91 | .P |
| 92 | In some circumstances you may need to call additional functions. These are |
| 93 | described in the section entitled |
| 94 | .\" HTML <a href="#stackcontrol"> |
| 95 | .\" </a> |
| 96 | "Controlling the JIT stack" |
| 97 | .\" |
| 98 | below. |
| 99 | .P |
| 100 | There are some \fBpcre2_match()\fP options that are not supported by JIT, and |
| 101 | there are also some pattern items that JIT cannot handle. Details are given |
| 102 | below. In both cases, matching automatically falls back to the interpretive |
| 103 | code. If you want to know whether JIT was actually used for a particular match, |
| 104 | you should arrange for a JIT callback function to be set up as described in the |
| 105 | section entitled |
| 106 | .\" HTML <a href="#stackcontrol"> |
| 107 | .\" </a> |
| 108 | "Controlling the JIT stack" |
| 109 | .\" |
| 110 | below, even if you do not need to supply a non-default JIT stack. Such a |
| 111 | callback function is called whenever JIT code is about to be obeyed. If the |
| 112 | match-time options are not right for JIT execution, the callback function is |
| 113 | not obeyed. |
| 114 | .P |
| 115 | If the JIT compiler finds an unsupported item, no JIT data is generated. You |
| 116 | can find out if JIT matching is available after compiling a pattern by calling |
| 117 | \fBpcre2_pattern_info()\fP with the PCRE2_INFO_JITSIZE option. A non-zero |
| 118 | result means that JIT compilation was successful. A result of 0 means that JIT |
| 119 | support is not available, or the pattern was not processed by |
| 120 | \fBpcre2_jit_compile()\fP, or the JIT compiler was not able to handle the |
| 121 | pattern. |
| 122 | . |
| 123 | . |
| 124 | .SH "MATCHING SUBJECTS CONTAINING INVALID UTF" |
| 125 | .rs |
| 126 | .sp |
| 127 | When a pattern is compiled with the PCRE2_UTF option, subject strings are |
| 128 | normally expected to be a valid sequence of UTF code units. By default, this is |
| 129 | checked at the start of matching and an error is generated if invalid UTF is |
| 130 | detected. The PCRE2_NO_UTF_CHECK option can be passed to \fBpcre2_match()\fP to |
| 131 | skip the check (for improved performance) if you are sure that a subject string |
| 132 | is valid. If this option is used with an invalid string, the result is |
| 133 | undefined. |
| 134 | .P |
| 135 | However, a way of running matches on strings that may contain invalid UTF |
| 136 | sequences is available. Calling \fBpcre2_compile()\fP with the |
| 137 | PCRE2_MATCH_INVALID_UTF option has two effects: it tells the interpreter in |
| 138 | \fBpcre2_match()\fP to support invalid UTF, and, if \fBpcre2_jit_compile()\fP |
| 139 | is called, the compiled JIT code also supports invalid UTF. Details of how this |
| 140 | support works, in both the JIT and the interpretive cases, is given in the |
| 141 | .\" HREF |
| 142 | \fBpcre2unicode\fP |
| 143 | .\" |
| 144 | documentation. |
| 145 | .P |
| 146 | There is also an obsolete option for \fBpcre2_jit_compile()\fP called |
| 147 | PCRE2_JIT_INVALID_UTF, which currently exists only for backward compatibility. |
| 148 | It is superseded by the \fBpcre2_compile()\fP option PCRE2_MATCH_INVALID_UTF |
| 149 | and should no longer be used. It may be removed in future. |
| 150 | . |
| 151 | . |
| 152 | .SH "UNSUPPORTED OPTIONS AND PATTERN ITEMS" |
| 153 | .rs |
| 154 | .sp |
| 155 | The \fBpcre2_match()\fP options that are supported for JIT matching are |
| 156 | PCRE2_COPY_MATCHED_SUBJECT, PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, |
| 157 | PCRE2_NOTEMPTY_ATSTART, PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, and |
| 158 | PCRE2_PARTIAL_SOFT. The PCRE2_ANCHORED and PCRE2_ENDANCHORED options are not |
| 159 | supported at match time. |
| 160 | .P |
| 161 | If the PCRE2_NO_JIT option is passed to \fBpcre2_match()\fP it disables the |
| 162 | use of JIT, forcing matching by the interpreter code. |
| 163 | .P |
| 164 | The only unsupported pattern items are \eC (match a single data unit) when |
| 165 | running in a UTF mode, and a callout immediately before an assertion condition |
| 166 | in a conditional group. |
| 167 | . |
| 168 | . |
| 169 | .SH "RETURN VALUES FROM JIT MATCHING" |
| 170 | .rs |
| 171 | .sp |
| 172 | When a pattern is matched using JIT matching, the return values are the same |
| 173 | as those given by the interpretive \fBpcre2_match()\fP code, with the addition |
| 174 | of one new error code: PCRE2_ERROR_JIT_STACKLIMIT. This means that the memory |
| 175 | used for the JIT stack was insufficient. See |
| 176 | .\" HTML <a href="#stackcontrol"> |
| 177 | .\" </a> |
| 178 | "Controlling the JIT stack" |
| 179 | .\" |
| 180 | below for a discussion of JIT stack usage. |
| 181 | .P |
| 182 | The error code PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if searching |
| 183 | a very large pattern tree goes on for too long, as it is in the same |
| 184 | circumstance when JIT is not used, but the details of exactly what is counted |
| 185 | are not the same. The PCRE2_ERROR_DEPTHLIMIT error code is never returned |
| 186 | when JIT matching is used. |
| 187 | . |
| 188 | . |
| 189 | .\" HTML <a name="stackcontrol"></a> |
| 190 | .SH "CONTROLLING THE JIT STACK" |
| 191 | .rs |
| 192 | .sp |
| 193 | When the compiled JIT code runs, it needs a block of memory to use as a stack. |
| 194 | By default, it uses 32KiB on the machine stack. However, some large or |
| 195 | complicated patterns need more than this. The error PCRE2_ERROR_JIT_STACKLIMIT |
| 196 | is given when there is not enough stack. Three functions are provided for |
| 197 | managing blocks of memory for use as JIT stacks. There is further discussion |
| 198 | about the use of JIT stacks in the section entitled |
| 199 | .\" HTML <a href="#stackfaq"> |
| 200 | .\" </a> |
| 201 | "JIT stack FAQ" |
| 202 | .\" |
| 203 | below. |
| 204 | .P |
| 205 | The \fBpcre2_jit_stack_create()\fP function creates a JIT stack. Its arguments |
| 206 | are a starting size, a maximum size, and a general context (for memory |
| 207 | allocation functions, or NULL for standard memory allocation). It returns a |
| 208 | pointer to an opaque structure of type \fBpcre2_jit_stack\fP, or NULL if there |
| 209 | is an error. The \fBpcre2_jit_stack_free()\fP function is used to free a stack |
| 210 | that is no longer needed. If its argument is NULL, this function returns |
| 211 | immediately, without doing anything. (For the technically minded: the address |
| 212 | space is allocated by mmap or VirtualAlloc.) A maximum stack size of 512KiB to |
| 213 | 1MiB should be more than enough for any pattern. |
| 214 | .P |
| 215 | The \fBpcre2_jit_stack_assign()\fP function specifies which stack JIT code |
| 216 | should use. Its arguments are as follows: |
| 217 | .sp |
| 218 | pcre2_match_context *mcontext |
| 219 | pcre2_jit_callback callback |
| 220 | void *data |
| 221 | .sp |
| 222 | The first argument is a pointer to a match context. When this is subsequently |
| 223 | passed to a matching function, its information determines which JIT stack is |
| 224 | used. If this argument is NULL, the function returns immediately, without doing |
| 225 | anything. There are three cases for the values of the other two options: |
| 226 | .sp |
| 227 | (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32KiB block |
| 228 | on the machine stack is used. This is the default when a match |
| 229 | context is created. |
| 230 | .sp |
| 231 | (2) If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must be |
| 232 | a pointer to a valid JIT stack, the result of calling |
| 233 | \fBpcre2_jit_stack_create()\fP. |
| 234 | .sp |
| 235 | (3) If \fIcallback\fP is not NULL, it must point to a function that is |
| 236 | called with \fIdata\fP as an argument at the start of matching, in |
| 237 | order to set up a JIT stack. If the return from the callback |
| 238 | function is NULL, the internal 32KiB stack is used; otherwise the |
| 239 | return value must be a valid JIT stack, the result of calling |
| 240 | \fBpcre2_jit_stack_create()\fP. |
| 241 | .sp |
| 242 | A callback function is obeyed whenever JIT code is about to be run; it is not |
| 243 | obeyed when \fBpcre2_match()\fP is called with options that are incompatible |
| 244 | for JIT matching. A callback function can therefore be used to determine |
| 245 | whether a match operation was executed by JIT or by the interpreter. |
| 246 | .P |
| 247 | You may safely use the same JIT stack for more than one pattern (either by |
| 248 | assigning directly or by callback), as long as the patterns are matched |
| 249 | sequentially in the same thread. Currently, the only way to set up |
| 250 | non-sequential matches in one thread is to use callouts: if a callout function |
| 251 | starts another match, that match must use a different JIT stack to the one used |
| 252 | for currently suspended match(es). |
| 253 | .P |
Elliott Hughes | 4e19c8e | 2022-04-15 15:11:02 -0700 | [diff] [blame] | 254 | In a multithread application, if you do not specify a JIT stack, or if you |
| 255 | assign or pass back NULL from a callback, that is thread-safe, because each |
| 256 | thread has its own machine stack. However, if you assign or pass back a |
| 257 | non-NULL JIT stack, this must be a different stack for each thread so that the |
| 258 | application is thread-safe. |
Elliott Hughes | 5b80804 | 2021-10-01 10:56:10 -0700 | [diff] [blame] | 259 | .P |
| 260 | Strictly speaking, even more is allowed. You can assign the same non-NULL stack |
| 261 | to a match context that is used by any number of patterns, as long as they are |
| 262 | not used for matching by multiple threads at the same time. For example, you |
| 263 | could use the same stack in all compiled patterns, with a global mutex in the |
| 264 | callback to wait until the stack is available for use. However, this is an |
| 265 | inefficient solution, and not recommended. |
| 266 | .P |
| 267 | This is a suggestion for how a multithreaded program that needs to set up |
| 268 | non-default JIT stacks might operate: |
| 269 | .sp |
| 270 | During thread initialization |
| 271 | thread_local_var = pcre2_jit_stack_create(...) |
| 272 | .sp |
| 273 | During thread exit |
| 274 | pcre2_jit_stack_free(thread_local_var) |
| 275 | .sp |
| 276 | Use a one-line callback function |
| 277 | return thread_local_var |
| 278 | .sp |
| 279 | All the functions described in this section do nothing if JIT is not available. |
| 280 | . |
| 281 | . |
| 282 | .\" HTML <a name="stackfaq"></a> |
| 283 | .SH "JIT STACK FAQ" |
| 284 | .rs |
| 285 | .sp |
| 286 | (1) Why do we need JIT stacks? |
| 287 | .sp |
| 288 | PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack where |
| 289 | the local data of the current node is pushed before checking its child nodes. |
| 290 | Allocating real machine stack on some platforms is difficult. For example, the |
| 291 | stack chain needs to be updated every time if we extend the stack on PowerPC. |
| 292 | Although it is possible, its updating time overhead decreases performance. So |
| 293 | we do the recursion in memory. |
| 294 | .P |
| 295 | (2) Why don't we simply allocate blocks of memory with \fBmalloc()\fP? |
| 296 | .sp |
| 297 | Modern operating systems have a nice feature: they can reserve an address space |
| 298 | instead of allocating memory. We can safely allocate memory pages inside this |
| 299 | address space, so the stack could grow without moving memory data (this is |
| 300 | important because of pointers). Thus we can allocate 1MiB address space, and |
| 301 | use only a single memory page (usually 4KiB) if that is enough. However, we can |
| 302 | still grow up to 1MiB anytime if needed. |
| 303 | .P |
| 304 | (3) Who "owns" a JIT stack? |
| 305 | .sp |
| 306 | The owner of the stack is the user program, not the JIT studied pattern or |
| 307 | anything else. The user program must ensure that if a stack is being used by |
| 308 | \fBpcre2_match()\fP, (that is, it is assigned to a match context that is passed |
| 309 | to the pattern currently running), that stack must not be used by any other |
| 310 | threads (to avoid overwriting the same memory area). The best practice for |
| 311 | multithreaded programs is to allocate a stack for each thread, and return this |
| 312 | stack through the JIT callback function. |
| 313 | .P |
| 314 | (4) When should a JIT stack be freed? |
| 315 | .sp |
| 316 | You can free a JIT stack at any time, as long as it will not be used by |
| 317 | \fBpcre2_match()\fP again. When you assign the stack to a match context, only a |
| 318 | pointer is set. There is no reference counting or any other magic. You can free |
| 319 | compiled patterns, contexts, and stacks in any order, anytime. |
| 320 | Just \fIdo not\fP call \fBpcre2_match()\fP with a match context pointing to an |
| 321 | already freed stack, as that will cause SEGFAULT. (Also, do not free a stack |
| 322 | currently used by \fBpcre2_match()\fP in another thread). You can also replace |
| 323 | the stack in a context at any time when it is not in use. You should free the |
| 324 | previous stack before assigning a replacement. |
| 325 | .P |
| 326 | (5) Should I allocate/free a stack every time before/after calling |
| 327 | \fBpcre2_match()\fP? |
| 328 | .sp |
| 329 | No, because this is too costly in terms of resources. However, you could |
| 330 | implement some clever idea which release the stack if it is not used in let's |
| 331 | say two minutes. The JIT callback can help to achieve this without keeping a |
| 332 | list of patterns. |
| 333 | .P |
| 334 | (6) OK, the stack is for long term memory allocation. But what happens if a |
| 335 | pattern causes stack overflow with a stack of 1MiB? Is that 1MiB kept until the |
| 336 | stack is freed? |
| 337 | .sp |
| 338 | Especially on embedded sytems, it might be a good idea to release memory |
| 339 | sometimes without freeing the stack. There is no API for this at the moment. |
| 340 | Probably a function call which returns with the currently allocated memory for |
| 341 | any stack and another which allows releasing memory (shrinking the stack) would |
| 342 | be a good idea if someone needs this. |
| 343 | .P |
| 344 | (7) This is too much of a headache. Isn't there any better solution for JIT |
| 345 | stack handling? |
| 346 | .sp |
| 347 | No, thanks to Windows. If POSIX threads were used everywhere, we could throw |
| 348 | out this complicated API. |
| 349 | . |
| 350 | . |
| 351 | .SH "FREEING JIT SPECULATIVE MEMORY" |
| 352 | .rs |
| 353 | .sp |
| 354 | .nf |
| 355 | .B void pcre2_jit_free_unused_memory(pcre2_general_context *\fIgcontext\fP); |
| 356 | .fi |
| 357 | .P |
Elliott Hughes | 4e19c8e | 2022-04-15 15:11:02 -0700 | [diff] [blame] | 358 | The JIT executable allocator does not free all memory when it is possible. It |
| 359 | expects new allocations, and keeps some free memory around to improve |
Elliott Hughes | 5b80804 | 2021-10-01 10:56:10 -0700 | [diff] [blame] | 360 | allocation speed. However, in low memory conditions, it might be better to free |
| 361 | all possible memory. You can cause this to happen by calling |
| 362 | pcre2_jit_free_unused_memory(). Its argument is a general context, for custom |
| 363 | memory management, or NULL for standard memory management. |
| 364 | . |
| 365 | . |
| 366 | .SH "EXAMPLE CODE" |
| 367 | .rs |
| 368 | .sp |
| 369 | This is a single-threaded example that specifies a JIT stack without using a |
| 370 | callback. A real program should include error checking after all the function |
| 371 | calls. |
| 372 | .sp |
| 373 | int rc; |
| 374 | pcre2_code *re; |
| 375 | pcre2_match_data *match_data; |
| 376 | pcre2_match_context *mcontext; |
| 377 | pcre2_jit_stack *jit_stack; |
| 378 | .sp |
| 379 | re = pcre2_compile(pattern, PCRE2_ZERO_TERMINATED, 0, |
| 380 | &errornumber, &erroffset, NULL); |
| 381 | rc = pcre2_jit_compile(re, PCRE2_JIT_COMPLETE); |
| 382 | mcontext = pcre2_match_context_create(NULL); |
| 383 | jit_stack = pcre2_jit_stack_create(32*1024, 512*1024, NULL); |
| 384 | pcre2_jit_stack_assign(mcontext, NULL, jit_stack); |
| 385 | match_data = pcre2_match_data_create(re, 10); |
| 386 | rc = pcre2_match(re, subject, length, 0, 0, match_data, mcontext); |
| 387 | /* Process result */ |
| 388 | .sp |
| 389 | pcre2_code_free(re); |
| 390 | pcre2_match_data_free(match_data); |
| 391 | pcre2_match_context_free(mcontext); |
| 392 | pcre2_jit_stack_free(jit_stack); |
| 393 | .sp |
| 394 | . |
| 395 | . |
| 396 | .SH "JIT FAST PATH API" |
| 397 | .rs |
| 398 | .sp |
| 399 | Because the API described above falls back to interpreted matching when JIT is |
| 400 | not available, it is convenient for programs that are written for general use |
| 401 | in many environments. However, calling JIT via \fBpcre2_match()\fP does have a |
| 402 | performance impact. Programs that are written for use where JIT is known to be |
| 403 | available, and which need the best possible performance, can instead use a |
| 404 | "fast path" API to call JIT matching directly instead of calling |
| 405 | \fBpcre2_match()\fP (obviously only for patterns that have been successfully |
| 406 | processed by \fBpcre2_jit_compile()\fP). |
| 407 | .P |
| 408 | The fast path function is called \fBpcre2_jit_match()\fP, and it takes exactly |
| 409 | the same arguments as \fBpcre2_match()\fP. However, the subject string must be |
| 410 | specified with a length; PCRE2_ZERO_TERMINATED is not supported. Unsupported |
| 411 | option bits (for example, PCRE2_ANCHORED, PCRE2_ENDANCHORED and |
| 412 | PCRE2_COPY_MATCHED_SUBJECT) are ignored, as is the PCRE2_NO_JIT option. The |
| 413 | return values are also the same as for \fBpcre2_match()\fP, plus |
| 414 | PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is requested |
| 415 | that was not compiled. |
| 416 | .P |
| 417 | When you call \fBpcre2_match()\fP, as well as testing for invalid options, a |
| 418 | number of other sanity checks are performed on the arguments. For example, if |
Elliott Hughes | 4e19c8e | 2022-04-15 15:11:02 -0700 | [diff] [blame] | 419 | the subject pointer is NULL but the length is non-zero, an immediate error is |
| 420 | given. Also, unless PCRE2_NO_UTF_CHECK is set, a UTF subject string is tested |
| 421 | for validity. In the interests of speed, these checks do not happen on the JIT |
| 422 | fast path, and if invalid data is passed, the result is undefined. |
Elliott Hughes | 5b80804 | 2021-10-01 10:56:10 -0700 | [diff] [blame] | 423 | .P |
| 424 | Bypassing the sanity checks and the \fBpcre2_match()\fP wrapping can give |
| 425 | speedups of more than 10%. |
| 426 | . |
| 427 | . |
| 428 | .SH "SEE ALSO" |
| 429 | .rs |
| 430 | .sp |
| 431 | \fBpcre2api\fP(3) |
| 432 | . |
| 433 | . |
| 434 | .SH AUTHOR |
| 435 | .rs |
| 436 | .sp |
| 437 | .nf |
| 438 | Philip Hazel (FAQ by Zoltan Herczeg) |
| 439 | University Computing Service |
| 440 | Cambridge, England. |
| 441 | .fi |
| 442 | . |
| 443 | . |
| 444 | .SH REVISION |
| 445 | .rs |
| 446 | .sp |
| 447 | .nf |
Elliott Hughes | 4e19c8e | 2022-04-15 15:11:02 -0700 | [diff] [blame] | 448 | Last updated: 30 November 2021 |
| 449 | Copyright (c) 1997-2021 University of Cambridge. |
Elliott Hughes | 5b80804 | 2021-10-01 10:56:10 -0700 | [diff] [blame] | 450 | .fi |