| regex.3 (104358) | regex.3 (108037) |
|---|---|
| 1.\" Copyright (c) 1992, 1993, 1994 Henry Spencer. 2.\" Copyright (c) 1992, 1993, 1994 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" Henry Spencer. 7.\" 8.\" Redistribution and use in source and binary forms, with or without --- 20 unchanged lines hidden (view full) --- 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" @(#)regex.3 8.4 (Berkeley) 3/20/94 | 1.\" Copyright (c) 1992, 1993, 1994 Henry Spencer. 2.\" Copyright (c) 1992, 1993, 1994 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" Henry Spencer. 7.\" 8.\" Redistribution and use in source and binary forms, with or without --- 20 unchanged lines hidden (view full) --- 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" @(#)regex.3 8.4 (Berkeley) 3/20/94 |
| 37.\" $FreeBSD: head/lib/libc/regex/regex.3 104358 2002-10-02 07:49:35Z mike $ | 37.\" $FreeBSD: head/lib/libc/regex/regex.3 108037 2002-12-18 12:45:11Z ru $ |
| 38.\" 39.Dd October 2, 2002 40.Dt REGEX 3 41.Os 42.Sh NAME 43.Nm regcomp , 44.Nm regexec , 45.Nm regerror , --- 21 unchanged lines hidden (view full) --- 67.Fn regfree "regex_t *preg" 68.Sh DESCRIPTION 69These routines implement 70.St -p1003.2 71regular expressions 72.Pq Do RE Dc Ns s ; 73see 74.Xr re_format 7 . | 38.\" 39.Dd October 2, 2002 40.Dt REGEX 3 41.Os 42.Sh NAME 43.Nm regcomp , 44.Nm regexec , 45.Nm regerror , --- 21 unchanged lines hidden (view full) --- 67.Fn regfree "regex_t *preg" 68.Sh DESCRIPTION 69These routines implement 70.St -p1003.2 71regular expressions 72.Pq Do RE Dc Ns s ; 73see 74.Xr re_format 7 . |
| 75.Fn Regcomp | 75The 76.Fn regcomp 77function |
| 76compiles an RE written as a string into an internal form, 77.Fn regexec 78matches that internal form against a string and reports results, 79.Fn regerror 80transforms error codes from either into human-readable messages, 81and 82.Fn regfree 83frees any dynamically-allocated storage used by the internal form --- 7 unchanged lines hidden (view full) --- 91.Ft regmatch_t , 92the former for compiled internal forms and the latter for match reporting. 93It also declares the four functions, 94a type 95.Ft regoff_t , 96and a number of constants with names starting with 97.Dq Dv REG_ . 98.Pp | 78compiles an RE written as a string into an internal form, 79.Fn regexec 80matches that internal form against a string and reports results, 81.Fn regerror 82transforms error codes from either into human-readable messages, 83and 84.Fn regfree 85frees any dynamically-allocated storage used by the internal form --- 7 unchanged lines hidden (view full) --- 93.Ft regmatch_t , 94the former for compiled internal forms and the latter for match reporting. 95It also declares the four functions, 96a type 97.Ft regoff_t , 98and a number of constants with names starting with 99.Dq Dv REG_ . 100.Pp |
| 99.Fn Regcomp | 101The 102.Fn regcomp 103function |
| 100compiles the regular expression contained in the 101.Fa pattern 102string, 103subject to the flags in 104.Fa cflags , 105and places the results in the 106.Ft regex_t 107structure pointed to by --- 91 unchanged lines hidden (view full) --- 199.Dv REG_NOSUB 200flag was used). 201If 202.Fn regcomp 203fails, it returns a non-zero error code; 204see 205.Sx DIAGNOSTICS . 206.Pp | 104compiles the regular expression contained in the 105.Fa pattern 106string, 107subject to the flags in 108.Fa cflags , 109and places the results in the 110.Ft regex_t 111structure pointed to by --- 91 unchanged lines hidden (view full) --- 203.Dv REG_NOSUB 204flag was used). 205If 206.Fn regcomp 207fails, it returns a non-zero error code; 208see 209.Sx DIAGNOSTICS . 210.Pp |
| 207.Fn Regexec | 211The 212.Fn regexec 213function |
| 208matches the compiled RE pointed to by 209.Fa preg 210against the 211.Fa string , 212subject to the flags in 213.Fa eflags , 214and reports results using 215.Fa nmatch , --- 169 unchanged lines hidden (view full) --- 385is 0 or 386.Dv REG_NOSUB 387was specified, 388the value of 389.Fa pmatch Ns [0] 390will not be changed by a successful 391.Fn regexec . 392.Pp | 214matches the compiled RE pointed to by 215.Fa preg 216against the 217.Fa string , 218subject to the flags in 219.Fa eflags , 220and reports results using 221.Fa nmatch , --- 169 unchanged lines hidden (view full) --- 391is 0 or 392.Dv REG_NOSUB 393was specified, 394the value of 395.Fa pmatch Ns [0] 396will not be changed by a successful 397.Fn regexec . 398.Pp |
| 393.Fn Regerror | 399The 400.Fn regerror 401function |
| 394maps a non-zero 395.Fa errcode 396from either 397.Fn regcomp 398or 399.Fn regexec 400to a human-readable, printable message. 401If --- 6 unchanged lines hidden (view full) --- 408pointed to by 409.Fa preg , 410and if the error code came from 411.Fn regcomp , 412it should have been the result from the most recent 413.Fn regcomp 414using that 415.Ft regex_t . | 402maps a non-zero 403.Fa errcode 404from either 405.Fn regcomp 406or 407.Fn regexec 408to a human-readable, printable message. 409If --- 6 unchanged lines hidden (view full) --- 416pointed to by 417.Fa preg , 418and if the error code came from 419.Fn regcomp , 420it should have been the result from the most recent 421.Fn regcomp 422using that 423.Ft regex_t . |
| 416.No ( Fn Regerror | 424The 425.Fn ( regerror |
| 417may be able to supply a more detailed message using information 418from the 419.Ft regex_t . ) | 426may be able to supply a more detailed message using information 427from the 428.Ft regex_t . ) |
| 420.Fn Regerror | 429The 430.Fn regerror 431function |
| 421places the NUL-terminated message into the buffer pointed to by 422.Fa errbuf , 423limiting the length (including the NUL) to at most 424.Fa errbuf_size 425bytes. 426If the whole message won't fit, 427as much of it as will fit before the terminating NUL is supplied. 428In any case, --- 40 unchanged lines hidden (view full) --- 469are intended primarily as debugging facilities; 470they are extensions, 471compatible with but not specified by 472.St -p1003.2 , 473and should be used with 474caution in software intended to be portable to other systems. 475Be warned also that they are considered experimental and changes are possible. 476.Pp | 432places the NUL-terminated message into the buffer pointed to by 433.Fa errbuf , 434limiting the length (including the NUL) to at most 435.Fa errbuf_size 436bytes. 437If the whole message won't fit, 438as much of it as will fit before the terminating NUL is supplied. 439In any case, --- 40 unchanged lines hidden (view full) --- 480are intended primarily as debugging facilities; 481they are extensions, 482compatible with but not specified by 483.St -p1003.2 , 484and should be used with 485caution in software intended to be portable to other systems. 486Be warned also that they are considered experimental and changes are possible. 487.Pp |
| 477.Fn Regfree | 488The 489.Fn regfree 490function |
| 478frees any dynamically-allocated storage associated with the compiled RE 479pointed to by 480.Fa preg . 481The remaining 482.Ft regex_t 483is no longer a valid compiled RE 484and the effect of supplying it to 485.Fn regexec --- 99 unchanged lines hidden (view full) --- 585Non-zero error codes from 586.Fn regcomp 587and 588.Fn regexec 589include the following: 590.Pp 591.Bl -tag -width REG_ECOLLATE -compact 592.It Dv REG_NOMATCH | 491frees any dynamically-allocated storage associated with the compiled RE 492pointed to by 493.Fa preg . 494The remaining 495.Ft regex_t 496is no longer a valid compiled RE 497and the effect of supplying it to 498.Fn regexec --- 99 unchanged lines hidden (view full) --- 598Non-zero error codes from 599.Fn regcomp 600and 601.Fn regexec 602include the following: 603.Pp 604.Bl -tag -width REG_ECOLLATE -compact 605.It Dv REG_NOMATCH |
| 606The |
|
| 593.Fn regexec | 607.Fn regexec |
| 608function |
|
| 594failed to match 595.It Dv REG_BADPAT 596invalid regular expression 597.It Dv REG_ECOLLATE 598invalid collating element 599.It Dv REG_ECTYPE 600invalid character class 601.It Dv REG_EESCAPE --- 42 unchanged lines hidden (view full) --- 644distribution. 645.Sh BUGS 646This is an alpha release with known defects. 647Please report problems. 648.Pp 649The back-reference code is subtle and doubts linger about its correctness 650in complex cases. 651.Pp | 609failed to match 610.It Dv REG_BADPAT 611invalid regular expression 612.It Dv REG_ECOLLATE 613invalid collating element 614.It Dv REG_ECTYPE 615invalid character class 616.It Dv REG_EESCAPE --- 42 unchanged lines hidden (view full) --- 659distribution. 660.Sh BUGS 661This is an alpha release with known defects. 662Please report problems. 663.Pp 664The back-reference code is subtle and doubts linger about its correctness 665in complex cases. 666.Pp |
| 652.Fn Regexec | 667The 668.Fn regexec 669function |
| 653performance is poor. 654This will improve with later releases. 655.Fa Nmatch 656exceeding 0 is expensive; 657.Fa nmatch 658exceeding 1 is worse. | 670performance is poor. 671This will improve with later releases. 672.Fa Nmatch 673exceeding 0 is expensive; 674.Fa nmatch 675exceeding 1 is worse. |
| 659.Fn Regexec | 676The 677.Fn regexec 678function |
| 660is largely insensitive to RE complexity 661.Em except 662that back 663references are massively expensive. 664RE length does matter; in particular, there is a strong speed bonus 665for keeping RE length under about 30 characters, 666with most special characters counting roughly double. 667.Pp | 679is largely insensitive to RE complexity 680.Em except 681that back 682references are massively expensive. 683RE length does matter; in particular, there is a strong speed bonus 684for keeping RE length under about 30 characters, 685with most special characters counting roughly double. 686.Pp |
| 668.Fn Regcomp | 687The 688.Fn regcomp 689function |
| 669implements bounded repetitions by macro expansion, 670which is costly in time and space if counts are large 671or bounded repetitions are nested. 672An RE like, say, 673.Ql "((((a{1,100}){1,100}){1,100}){1,100}){1,100}" 674will (eventually) run almost any existing machine out of swap space. 675.Pp 676There are suspected problems with response to obscure error conditions. --- 26 unchanged lines hidden --- | 690implements bounded repetitions by macro expansion, 691which is costly in time and space if counts are large 692or bounded repetitions are nested. 693An RE like, say, 694.Ql "((((a{1,100}){1,100}){1,100}){1,100}){1,100}" 695will (eventually) run almost any existing machine out of swap space. 696.Pp 697There are suspected problems with response to obscure error conditions. --- 26 unchanged lines hidden --- |