.\" Copyright (c) 1992, 1993, 1994 Henry Spencer.
|
.\" Copyright (c) 1992, 1993, 1994 Henry Spencer.
|
.\" Copyright (c) 1992, 1993, 1994
|
.\" Copyright (c) 1992, 1993, 1994
|
.\" The Regents of the University of California. All rights reserved.
|
.\" The Regents of the University of California. All rights reserved.
|
.\"
|
.\"
|
.\" This code is derived from software contributed to Berkeley by
|
.\" This code is derived from software contributed to Berkeley by
|
.\" Henry Spencer.
|
.\" Henry Spencer.
|
.\"
|
.\"
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
.\" are met:
|
.\" are met:
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" documentation and/or other materials provided with the distribution.
|
.\" documentation and/or other materials provided with the distribution.
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" must display the following acknowledgement:
|
.\" must display the following acknowledgement:
|
.\" This product includes software developed by the University of
|
.\" This product includes software developed by the University of
|
.\" California, Berkeley and its contributors.
|
.\" California, Berkeley and its contributors.
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" may be used to endorse or promote products derived from this software
|
.\" may be used to endorse or promote products derived from this software
|
.\" without specific prior written permission.
|
.\" without specific prior written permission.
|
.\"
|
.\"
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" SUCH DAMAGE.
|
.\" SUCH DAMAGE.
|
.\"
|
.\"
|
.\" @(#)regex.3 8.4 (Berkeley) 3/20/94
|
.\" @(#)regex.3 8.4 (Berkeley) 3/20/94
|
.\" $FreeBSD: src/lib/libc/regex/regex.3,v 1.9 2001/10/01 16:08:58 ru Exp $
|
.\" $FreeBSD: src/lib/libc/regex/regex.3,v 1.9 2001/10/01 16:08:58 ru Exp $
|
.\"
|
.\"
|
.Dd March 20, 1994
|
.Dd March 20, 1994
|
.Dt REGEX 3
|
.Dt REGEX 3
|
.Os
|
.Os
|
.Sh NAME
|
.Sh NAME
|
.Nm regcomp ,
|
.Nm regcomp ,
|
.Nm regexec ,
|
.Nm regexec ,
|
.Nm regerror ,
|
.Nm regerror ,
|
.Nm regfree
|
.Nm regfree
|
.Nd regular-expression library
|
.Nd regular-expression library
|
.Sh LIBRARY
|
.Sh LIBRARY
|
.Lb libc
|
.Lb libc
|
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
.In sys/types.h
|
.In sys/types.h
|
.In regex.h
|
.In regex.h
|
.Ft int
|
.Ft int
|
.Fn regcomp "regex_t *preg" "const char *pattern" "int cflags"
|
.Fn regcomp "regex_t *preg" "const char *pattern" "int cflags"
|
.Ft int
|
.Ft int
|
.Fo regexec
|
.Fo regexec
|
.Fa "const regex_t *preg" "const char *string"
|
.Fa "const regex_t *preg" "const char *string"
|
.Fa "size_t nmatch" "regmatch_t pmatch[]" "int eflags"
|
.Fa "size_t nmatch" "regmatch_t pmatch[]" "int eflags"
|
.Fc
|
.Fc
|
.Ft size_t
|
.Ft size_t
|
.Fo regerror
|
.Fo regerror
|
.Fa "int errcode" "const regex_t *preg"
|
.Fa "int errcode" "const regex_t *preg"
|
.Fa "char *errbuf" "size_t errbuf_size"
|
.Fa "char *errbuf" "size_t errbuf_size"
|
.Fc
|
.Fc
|
.Ft void
|
.Ft void
|
.Fn regfree "regex_t *preg"
|
.Fn regfree "regex_t *preg"
|
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
These routines implement
|
These routines implement
|
.St -p1003.2
|
.St -p1003.2
|
regular expressions
|
regular expressions
|
.Pq Do RE Dc Ns s ;
|
.Pq Do RE Dc Ns s ;
|
see
|
see
|
.Xr re_format 7 .
|
.Xr re_format 7 .
|
.Fn Regcomp
|
.Fn Regcomp
|
compiles an RE written as a string into an internal form,
|
compiles an RE written as a string into an internal form,
|
.Fn regexec
|
.Fn regexec
|
matches that internal form against a string and reports results,
|
matches that internal form against a string and reports results,
|
.Fn regerror
|
.Fn regerror
|
transforms error codes from either into human-readable messages,
|
transforms error codes from either into human-readable messages,
|
and
|
and
|
.Fn regfree
|
.Fn regfree
|
frees any dynamically-allocated storage used by the internal form
|
frees any dynamically-allocated storage used by the internal form
|
of an RE.
|
of an RE.
|
.Pp
|
.Pp
|
The header
|
The header
|
.Aq Pa regex.h
|
.Aq Pa regex.h
|
declares two structure types,
|
declares two structure types,
|
.Ft regex_t
|
.Ft regex_t
|
and
|
and
|
.Ft regmatch_t ,
|
.Ft regmatch_t ,
|
the former for compiled internal forms and the latter for match reporting.
|
the former for compiled internal forms and the latter for match reporting.
|
It also declares the four functions,
|
It also declares the four functions,
|
a type
|
a type
|
.Ft regoff_t ,
|
.Ft regoff_t ,
|
and a number of constants with names starting with
|
and a number of constants with names starting with
|
.Dq Dv REG_ .
|
.Dq Dv REG_ .
|
.Pp
|
.Pp
|
.Fn Regcomp
|
.Fn Regcomp
|
compiles the regular expression contained in the
|
compiles the regular expression contained in the
|
.Fa pattern
|
.Fa pattern
|
string,
|
string,
|
subject to the flags in
|
subject to the flags in
|
.Fa cflags ,
|
.Fa cflags ,
|
and places the results in the
|
and places the results in the
|
.Ft regex_t
|
.Ft regex_t
|
structure pointed to by
|
structure pointed to by
|
.Fa preg .
|
.Fa preg .
|
.Fa Cflags
|
.Fa Cflags
|
is the bitwise OR of zero or more of the following flags:
|
is the bitwise OR of zero or more of the following flags:
|
.Bl -tag -width REG_EXTENDED
|
.Bl -tag -width REG_EXTENDED
|
.It Dv REG_EXTENDED
|
.It Dv REG_EXTENDED
|
Compile modern
|
Compile modern
|
.Pq Dq extended
|
.Pq Dq extended
|
REs,
|
REs,
|
rather than the obsolete
|
rather than the obsolete
|
.Pq Dq basic
|
.Pq Dq basic
|
REs that
|
REs that
|
are the default.
|
are the default.
|
.It Dv REG_BASIC
|
.It Dv REG_BASIC
|
This is a synonym for 0,
|
This is a synonym for 0,
|
provided as a counterpart to
|
provided as a counterpart to
|
.Dv REG_EXTENDED
|
.Dv REG_EXTENDED
|
to improve readability.
|
to improve readability.
|
.It Dv REG_NOSPEC
|
.It Dv REG_NOSPEC
|
Compile with recognition of all special characters turned off.
|
Compile with recognition of all special characters turned off.
|
All characters are thus considered ordinary,
|
All characters are thus considered ordinary,
|
so the
|
so the
|
.Dq RE
|
.Dq RE
|
is a literal string.
|
is a literal string.
|
This is an extension,
|
This is an extension,
|
compatible with but not specified by
|
compatible with but not specified by
|
.St -p1003.2 ,
|
.St -p1003.2 ,
|
and should be used with
|
and should be used with
|
caution in software intended to be portable to other systems.
|
caution in software intended to be portable to other systems.
|
.Dv REG_EXTENDED
|
.Dv REG_EXTENDED
|
and
|
and
|
.Dv REG_NOSPEC
|
.Dv REG_NOSPEC
|
may not be used
|
may not be used
|
in the same call to
|
in the same call to
|
.Fn regcomp .
|
.Fn regcomp .
|
.It Dv REG_ICASE
|
.It Dv REG_ICASE
|
Compile for matching that ignores upper/lower case distinctions.
|
Compile for matching that ignores upper/lower case distinctions.
|
See
|
See
|
.Xr re_format 7 .
|
.Xr re_format 7 .
|
.It Dv REG_NOSUB
|
.It Dv REG_NOSUB
|
Compile for matching that need only report success or failure,
|
Compile for matching that need only report success or failure,
|
not what was matched.
|
not what was matched.
|
.It Dv REG_NEWLINE
|
.It Dv REG_NEWLINE
|
Compile for newline-sensitive matching.
|
Compile for newline-sensitive matching.
|
By default, newline is a completely ordinary character with no special
|
By default, newline is a completely ordinary character with no special
|
meaning in either REs or strings.
|
meaning in either REs or strings.
|
With this flag,
|
With this flag,
|
.Ql [^
|
.Ql [^
|
bracket expressions and
|
bracket expressions and
|
.Ql .\&
|
.Ql .\&
|
never match newline,
|
never match newline,
|
a
|
a
|
.Ql ^\&
|
.Ql ^\&
|
anchor matches the null string after any newline in the string
|
anchor matches the null string after any newline in the string
|
in addition to its normal function,
|
in addition to its normal function,
|
and the
|
and the
|
.Ql $\&
|
.Ql $\&
|
anchor matches the null string before any newline in the
|
anchor matches the null string before any newline in the
|
string in addition to its normal function.
|
string in addition to its normal function.
|
.It Dv REG_PEND
|
.It Dv REG_PEND
|
The regular expression ends,
|
The regular expression ends,
|
not at the first NUL,
|
not at the first NUL,
|
but just before the character pointed to by the
|
but just before the character pointed to by the
|
.Va re_endp
|
.Va re_endp
|
member of the structure pointed to by
|
member of the structure pointed to by
|
.Fa preg .
|
.Fa preg .
|
The
|
The
|
.Va re_endp
|
.Va re_endp
|
member is of type
|
member is of type
|
.Ft "const char *" .
|
.Ft "const char *" .
|
This flag permits inclusion of NULs in the RE;
|
This flag permits inclusion of NULs in the RE;
|
they are considered ordinary characters.
|
they are considered ordinary characters.
|
This is an extension,
|
This is an extension,
|
compatible with but not specified by
|
compatible with but not specified by
|
.St -p1003.2 ,
|
.St -p1003.2 ,
|
and should be used with
|
and should be used with
|
caution in software intended to be portable to other systems.
|
caution in software intended to be portable to other systems.
|
.El
|
.El
|
.Pp
|
.Pp
|
When successful,
|
When successful,
|
.Fn regcomp
|
.Fn regcomp
|
returns 0 and fills in the structure pointed to by
|
returns 0 and fills in the structure pointed to by
|
.Fa preg .
|
.Fa preg .
|
One member of that structure
|
One member of that structure
|
(other than
|
(other than
|
.Va re_endp )
|
.Va re_endp )
|
is publicized:
|
is publicized:
|
.Va re_nsub ,
|
.Va re_nsub ,
|
of type
|
of type
|
.Ft size_t ,
|
.Ft size_t ,
|
contains the number of parenthesized subexpressions within the RE
|
contains the number of parenthesized subexpressions within the RE
|
(except that the value of this member is undefined if the
|
(except that the value of this member is undefined if the
|
.Dv REG_NOSUB
|
.Dv REG_NOSUB
|
flag was used).
|
flag was used).
|
If
|
If
|
.Fn regcomp
|
.Fn regcomp
|
fails, it returns a non-zero error code;
|
fails, it returns a non-zero error code;
|
see
|
see
|
.Sx DIAGNOSTICS .
|
.Sx DIAGNOSTICS .
|
.Pp
|
.Pp
|
.Fn Regexec
|
.Fn Regexec
|
matches the compiled RE pointed to by
|
matches the compiled RE pointed to by
|
.Fa preg
|
.Fa preg
|
against the
|
against the
|
.Fa string ,
|
.Fa string ,
|
subject to the flags in
|
subject to the flags in
|
.Fa eflags ,
|
.Fa eflags ,
|
and reports results using
|
and reports results using
|
.Fa nmatch ,
|
.Fa nmatch ,
|
.Fa pmatch ,
|
.Fa pmatch ,
|
and the returned value.
|
and the returned value.
|
The RE must have been compiled by a previous invocation of
|
The RE must have been compiled by a previous invocation of
|
.Fn regcomp .
|
.Fn regcomp .
|
The compiled form is not altered during execution of
|
The compiled form is not altered during execution of
|
.Fn regexec ,
|
.Fn regexec ,
|
so a single compiled RE can be used simultaneously by multiple threads.
|
so a single compiled RE can be used simultaneously by multiple threads.
|
.Pp
|
.Pp
|
By default,
|
By default,
|
the NUL-terminated string pointed to by
|
the NUL-terminated string pointed to by
|
.Fa string
|
.Fa string
|
is considered to be the text of an entire line, minus any terminating
|
is considered to be the text of an entire line, minus any terminating
|
newline.
|
newline.
|
The
|
The
|
.Fa eflags
|
.Fa eflags
|
argument is the bitwise OR of zero or more of the following flags:
|
argument is the bitwise OR of zero or more of the following flags:
|
.Bl -tag -width REG_STARTEND
|
.Bl -tag -width REG_STARTEND
|
.It Dv REG_NOTBOL
|
.It Dv REG_NOTBOL
|
The first character of
|
The first character of
|
the string
|
the string
|
is not the beginning of a line, so the
|
is not the beginning of a line, so the
|
.Ql ^\&
|
.Ql ^\&
|
anchor should not match before it.
|
anchor should not match before it.
|
This does not affect the behavior of newlines under
|
This does not affect the behavior of newlines under
|
.Dv REG_NEWLINE .
|
.Dv REG_NEWLINE .
|
.It Dv REG_NOTEOL
|
.It Dv REG_NOTEOL
|
The NUL terminating
|
The NUL terminating
|
the string
|
the string
|
does not end a line, so the
|
does not end a line, so the
|
.Ql $\&
|
.Ql $\&
|
anchor should not match before it.
|
anchor should not match before it.
|
This does not affect the behavior of newlines under
|
This does not affect the behavior of newlines under
|
.Dv REG_NEWLINE .
|
.Dv REG_NEWLINE .
|
.It Dv REG_STARTEND
|
.It Dv REG_STARTEND
|
The string is considered to start at
|
The string is considered to start at
|
.Fa string
|
.Fa string
|
+
|
+
|
.Fa pmatch Ns [0]. Ns Va rm_so
|
.Fa pmatch Ns [0]. Ns Va rm_so
|
and to have a terminating NUL located at
|
and to have a terminating NUL located at
|
.Fa string
|
.Fa string
|
+
|
+
|
.Fa pmatch Ns [0]. Ns Va rm_eo
|
.Fa pmatch Ns [0]. Ns Va rm_eo
|
(there need not actually be a NUL at that location),
|
(there need not actually be a NUL at that location),
|
regardless of the value of
|
regardless of the value of
|
.Fa nmatch .
|
.Fa nmatch .
|
See below for the definition of
|
See below for the definition of
|
.Fa pmatch
|
.Fa pmatch
|
and
|
and
|
.Fa nmatch .
|
.Fa nmatch .
|
This is an extension,
|
This is an extension,
|
compatible with but not specified by
|
compatible with but not specified by
|
.St -p1003.2 ,
|
.St -p1003.2 ,
|
and should be used with
|
and should be used with
|
caution in software intended to be portable to other systems.
|
caution in software intended to be portable to other systems.
|
Note that a non-zero
|
Note that a non-zero
|
.Va rm_so
|
.Va rm_so
|
does not imply
|
does not imply
|
.Dv REG_NOTBOL ;
|
.Dv REG_NOTBOL ;
|
.Dv REG_STARTEND
|
.Dv REG_STARTEND
|
affects only the location of the string,
|
affects only the location of the string,
|
not how it is matched.
|
not how it is matched.
|
.El
|
.El
|
.Pp
|
.Pp
|
See
|
See
|
.Xr re_format 7
|
.Xr re_format 7
|
for a discussion of what is matched in situations where an RE or a
|
for a discussion of what is matched in situations where an RE or a
|
portion thereof could match any of several substrings of
|
portion thereof could match any of several substrings of
|
.Fa string .
|
.Fa string .
|
.Pp
|
.Pp
|
Normally,
|
Normally,
|
.Fn regexec
|
.Fn regexec
|
returns 0 for success and the non-zero code
|
returns 0 for success and the non-zero code
|
.Dv REG_NOMATCH
|
.Dv REG_NOMATCH
|
for failure.
|
for failure.
|
Other non-zero error codes may be returned in exceptional situations;
|
Other non-zero error codes may be returned in exceptional situations;
|
see
|
see
|
.Sx DIAGNOSTICS .
|
.Sx DIAGNOSTICS .
|
.Pp
|
.Pp
|
If
|
If
|
.Dv REG_NOSUB
|
.Dv REG_NOSUB
|
was specified in the compilation of the RE,
|
was specified in the compilation of the RE,
|
or if
|
or if
|
.Fa nmatch
|
.Fa nmatch
|
is 0,
|
is 0,
|
.Fn regexec
|
.Fn regexec
|
ignores the
|
ignores the
|
.Fa pmatch
|
.Fa pmatch
|
argument (but see below for the case where
|
argument (but see below for the case where
|
.Dv REG_STARTEND
|
.Dv REG_STARTEND
|
is specified).
|
is specified).
|
Otherwise,
|
Otherwise,
|
.Fa pmatch
|
.Fa pmatch
|
points to an array of
|
points to an array of
|
.Fa nmatch
|
.Fa nmatch
|
structures of type
|
structures of type
|
.Ft regmatch_t .
|
.Ft regmatch_t .
|
Such a structure has at least the members
|
Such a structure has at least the members
|
.Va rm_so
|
.Va rm_so
|
and
|
and
|
.Va rm_eo ,
|
.Va rm_eo ,
|
both of type
|
both of type
|
.Ft regoff_t
|
.Ft regoff_t
|
(a signed arithmetic type at least as large as an
|
(a signed arithmetic type at least as large as an
|
.Ft off_t
|
.Ft off_t
|
and a
|
and a
|
.Ft ssize_t ) ,
|
.Ft ssize_t ) ,
|
containing respectively the offset of the first character of a substring
|
containing respectively the offset of the first character of a substring
|
and the offset of the first character after the end of the substring.
|
and the offset of the first character after the end of the substring.
|
Offsets are measured from the beginning of the
|
Offsets are measured from the beginning of the
|
.Fa string
|
.Fa string
|
argument given to
|
argument given to
|
.Fn regexec .
|
.Fn regexec .
|
An empty substring is denoted by equal offsets,
|
An empty substring is denoted by equal offsets,
|
both indicating the character following the empty substring.
|
both indicating the character following the empty substring.
|
.Pp
|
.Pp
|
The 0th member of the
|
The 0th member of the
|
.Fa pmatch
|
.Fa pmatch
|
array is filled in to indicate what substring of
|
array is filled in to indicate what substring of
|
.Fa string
|
.Fa string
|
was matched by the entire RE.
|
was matched by the entire RE.
|
Remaining members report what substring was matched by parenthesized
|
Remaining members report what substring was matched by parenthesized
|
subexpressions within the RE;
|
subexpressions within the RE;
|
member
|
member
|
.Va i
|
.Va i
|
reports subexpression
|
reports subexpression
|
.Va i ,
|
.Va i ,
|
with subexpressions counted (starting at 1) by the order of their opening
|
with subexpressions counted (starting at 1) by the order of their opening
|
parentheses in the RE, left to right.
|
parentheses in the RE, left to right.
|
Unused entries in the array (corresponding either to subexpressions that
|
Unused entries in the array (corresponding either to subexpressions that
|
did not participate in the match at all, or to subexpressions that do not
|
did not participate in the match at all, or to subexpressions that do not
|
exist in the RE (that is,
|
exist in the RE (that is,
|
.Va i
|
.Va i
|
>
|
>
|
.Fa preg Ns -> Ns Va re_nsub ) )
|
.Fa preg Ns -> Ns Va re_nsub ) )
|
have both
|
have both
|
.Va rm_so
|
.Va rm_so
|
and
|
and
|
.Va rm_eo
|
.Va rm_eo
|
set to -1.
|
set to -1.
|
If a subexpression participated in the match several times,
|
If a subexpression participated in the match several times,
|
the reported substring is the last one it matched.
|
the reported substring is the last one it matched.
|
(Note, as an example in particular, that when the RE
|
(Note, as an example in particular, that when the RE
|
.Ql "(b*)+"
|
.Ql "(b*)+"
|
matches
|
matches
|
.Ql bbb ,
|
.Ql bbb ,
|
the parenthesized subexpression matches each of the three
|
the parenthesized subexpression matches each of the three
|
.So Li b Sc Ns s
|
.So Li b Sc Ns s
|
and then
|
and then
|
an infinite number of empty strings following the last
|
an infinite number of empty strings following the last
|
.Ql b ,
|
.Ql b ,
|
so the reported substring is one of the empties.)
|
so the reported substring is one of the empties.)
|
.Pp
|
.Pp
|
If
|
If
|
.Dv REG_STARTEND
|
.Dv REG_STARTEND
|
is specified,
|
is specified,
|
.Fa pmatch
|
.Fa pmatch
|
must point to at least one
|
must point to at least one
|
.Ft regmatch_t
|
.Ft regmatch_t
|
(even if
|
(even if
|
.Fa nmatch
|
.Fa nmatch
|
is 0 or
|
is 0 or
|
.Dv REG_NOSUB
|
.Dv REG_NOSUB
|
was specified),
|
was specified),
|
to hold the input offsets for
|
to hold the input offsets for
|
.Dv REG_STARTEND .
|
.Dv REG_STARTEND .
|
Use for output is still entirely controlled by
|
Use for output is still entirely controlled by
|
.Fa nmatch ;
|
.Fa nmatch ;
|
if
|
if
|
.Fa nmatch
|
.Fa nmatch
|
is 0 or
|
is 0 or
|
.Dv REG_NOSUB
|
.Dv REG_NOSUB
|
was specified,
|
was specified,
|
the value of
|
the value of
|
.Fa pmatch Ns [0]
|
.Fa pmatch Ns [0]
|
will not be changed by a successful
|
will not be changed by a successful
|
.Fn regexec .
|
.Fn regexec .
|
.Pp
|
.Pp
|
.Fn Regerror
|
.Fn Regerror
|
maps a non-zero
|
maps a non-zero
|
.Fa errcode
|
.Fa errcode
|
from either
|
from either
|
.Fn regcomp
|
.Fn regcomp
|
or
|
or
|
.Fn regexec
|
.Fn regexec
|
to a human-readable, printable message.
|
to a human-readable, printable message.
|
If
|
If
|
.Fa preg
|
.Fa preg
|
is
|
is
|
.No non\- Ns Dv NULL ,
|
.No non\- Ns Dv NULL ,
|
the error code should have arisen from use of
|
the error code should have arisen from use of
|
the
|
the
|
.Ft regex_t
|
.Ft regex_t
|
pointed to by
|
pointed to by
|
.Fa preg ,
|
.Fa preg ,
|
and if the error code came from
|
and if the error code came from
|
.Fn regcomp ,
|
.Fn regcomp ,
|
it should have been the result from the most recent
|
it should have been the result from the most recent
|
.Fn regcomp
|
.Fn regcomp
|
using that
|
using that
|
.Ft regex_t .
|
.Ft regex_t .
|
.No ( Fn Regerror
|
.No ( Fn Regerror
|
may be able to supply a more detailed message using information
|
may be able to supply a more detailed message using information
|
from the
|
from the
|
.Ft regex_t . )
|
.Ft regex_t . )
|
.Fn Regerror
|
.Fn Regerror
|
places the NUL-terminated message into the buffer pointed to by
|
places the NUL-terminated message into the buffer pointed to by
|
.Fa errbuf ,
|
.Fa errbuf ,
|
limiting the length (including the NUL) to at most
|
limiting the length (including the NUL) to at most
|
.Fa errbuf_size
|
.Fa errbuf_size
|
bytes.
|
bytes.
|
If the whole message won't fit,
|
If the whole message won't fit,
|
as much of it as will fit before the terminating NUL is supplied.
|
as much of it as will fit before the terminating NUL is supplied.
|
In any case,
|
In any case,
|
the returned value is the size of buffer needed to hold the whole
|
the returned value is the size of buffer needed to hold the whole
|
message (including terminating NUL).
|
message (including terminating NUL).
|
If
|
If
|
.Fa errbuf_size
|
.Fa errbuf_size
|
is 0,
|
is 0,
|
.Fa errbuf
|
.Fa errbuf
|
is ignored but the return value is still correct.
|
is ignored but the return value is still correct.
|
.Pp
|
.Pp
|
If the
|
If the
|
.Fa errcode
|
.Fa errcode
|
given to
|
given to
|
.Fn regerror
|
.Fn regerror
|
is first ORed with
|
is first ORed with
|
.Dv REG_ITOA ,
|
.Dv REG_ITOA ,
|
the
|
the
|
.Dq message
|
.Dq message
|
that results is the printable name of the error code,
|
that results is the printable name of the error code,
|
e.g.\&
|
e.g.\&
|
.Dq Dv REG_NOMATCH ,
|
.Dq Dv REG_NOMATCH ,
|
rather than an explanation thereof.
|
rather than an explanation thereof.
|
If
|
If
|
.Fa errcode
|
.Fa errcode
|
is
|
is
|
.Dv REG_ATOI ,
|
.Dv REG_ATOI ,
|
then
|
then
|
.Fa preg
|
.Fa preg
|
shall be
|
shall be
|
.No non\- Ns Dv NULL
|
.No non\- Ns Dv NULL
|
and the
|
and the
|
.Va re_endp
|
.Va re_endp
|
member of the structure it points to
|
member of the structure it points to
|
must point to the printable name of an error code;
|
must point to the printable name of an error code;
|
in this case, the result in
|
in this case, the result in
|
.Fa errbuf
|
.Fa errbuf
|
is the decimal digits of
|
is the decimal digits of
|
the numeric value of the error code
|
the numeric value of the error code
|
(0 if the name is not recognized).
|
(0 if the name is not recognized).
|
.Dv REG_ITOA
|
.Dv REG_ITOA
|
and
|
and
|
.Dv REG_ATOI
|
.Dv REG_ATOI
|
are intended primarily as debugging facilities;
|
are intended primarily as debugging facilities;
|
they are extensions,
|
they are extensions,
|
compatible with but not specified by
|
compatible with but not specified by
|
.St -p1003.2 ,
|
.St -p1003.2 ,
|
and should be used with
|
and should be used with
|
caution in software intended to be portable to other systems.
|
caution in software intended to be portable to other systems.
|
Be warned also that they are considered experimental and changes are possible.
|
Be warned also that they are considered experimental and changes are possible.
|
.Pp
|
.Pp
|
.Fn Regfree
|
.Fn Regfree
|
frees any dynamically-allocated storage associated with the compiled RE
|
frees any dynamically-allocated storage associated with the compiled RE
|
pointed to by
|
pointed to by
|
.Fa preg .
|
.Fa preg .
|
The remaining
|
The remaining
|
.Ft regex_t
|
.Ft regex_t
|
is no longer a valid compiled RE
|
is no longer a valid compiled RE
|
and the effect of supplying it to
|
and the effect of supplying it to
|
.Fn regexec
|
.Fn regexec
|
or
|
or
|
.Fn regerror
|
.Fn regerror
|
is undefined.
|
is undefined.
|
.Pp
|
.Pp
|
None of these functions references global variables except for tables
|
None of these functions references global variables except for tables
|
of constants;
|
of constants;
|
all are safe for use from multiple threads if the arguments are safe.
|
all are safe for use from multiple threads if the arguments are safe.
|
.Sh IMPLEMENTATION CHOICES
|
.Sh IMPLEMENTATION CHOICES
|
There are a number of decisions that
|
There are a number of decisions that
|
.St -p1003.2
|
.St -p1003.2
|
leaves up to the implementor,
|
leaves up to the implementor,
|
either by explicitly saying
|
either by explicitly saying
|
.Dq undefined
|
.Dq undefined
|
or by virtue of them being
|
or by virtue of them being
|
forbidden by the RE grammar.
|
forbidden by the RE grammar.
|
This implementation treats them as follows.
|
This implementation treats them as follows.
|
.Pp
|
.Pp
|
See
|
See
|
.Xr re_format 7
|
.Xr re_format 7
|
for a discussion of the definition of case-independent matching.
|
for a discussion of the definition of case-independent matching.
|
.Pp
|
.Pp
|
There is no particular limit on the length of REs,
|
There is no particular limit on the length of REs,
|
except insofar as memory is limited.
|
except insofar as memory is limited.
|
Memory usage is approximately linear in RE size, and largely insensitive
|
Memory usage is approximately linear in RE size, and largely insensitive
|
to RE complexity, except for bounded repetitions.
|
to RE complexity, except for bounded repetitions.
|
See
|
See
|
.Sx BUGS
|
.Sx BUGS
|
for one short RE using them
|
for one short RE using them
|
that will run almost any system out of memory.
|
that will run almost any system out of memory.
|
.Pp
|
.Pp
|
A backslashed character other than one specifically given a magic meaning
|
A backslashed character other than one specifically given a magic meaning
|
by
|
by
|
.St -p1003.2
|
.St -p1003.2
|
(such magic meanings occur only in obsolete
|
(such magic meanings occur only in obsolete
|
.Bq Dq basic
|
.Bq Dq basic
|
REs)
|
REs)
|
is taken as an ordinary character.
|
is taken as an ordinary character.
|
.Pp
|
.Pp
|
Any unmatched
|
Any unmatched
|
.Ql [\&
|
.Ql [\&
|
is a
|
is a
|
.Dv REG_EBRACK
|
.Dv REG_EBRACK
|
error.
|
error.
|
.Pp
|
.Pp
|
Equivalence classes cannot begin or end bracket-expression ranges.
|
Equivalence classes cannot begin or end bracket-expression ranges.
|
The endpoint of one range cannot begin another.
|
The endpoint of one range cannot begin another.
|
.Pp
|
.Pp
|
.Dv RE_DUP_MAX ,
|
.Dv RE_DUP_MAX ,
|
the limit on repetition counts in bounded repetitions, is 255.
|
the limit on repetition counts in bounded repetitions, is 255.
|
.Pp
|
.Pp
|
A repetition operator
|
A repetition operator
|
.Ql ( ?\& ,
|
.Ql ( ?\& ,
|
.Ql *\& ,
|
.Ql *\& ,
|
.Ql +\& ,
|
.Ql +\& ,
|
or bounds)
|
or bounds)
|
cannot follow another
|
cannot follow another
|
repetition operator.
|
repetition operator.
|
A repetition operator cannot begin an expression or subexpression
|
A repetition operator cannot begin an expression or subexpression
|
or follow
|
or follow
|
.Ql ^\&
|
.Ql ^\&
|
or
|
or
|
.Ql |\& .
|
.Ql |\& .
|
.Pp
|
.Pp
|
.Ql |\&
|
.Ql |\&
|
cannot appear first or last in a (sub)expression or after another
|
cannot appear first or last in a (sub)expression or after another
|
.Ql |\& ,
|
.Ql |\& ,
|
i.e. an operand of
|
i.e. an operand of
|
.Ql |\&
|
.Ql |\&
|
cannot be an empty subexpression.
|
cannot be an empty subexpression.
|
An empty parenthesized subexpression,
|
An empty parenthesized subexpression,
|
.Ql "()" ,
|
.Ql "()" ,
|
is legal and matches an
|
is legal and matches an
|
empty (sub)string.
|
empty (sub)string.
|
An empty string is not a legal RE.
|
An empty string is not a legal RE.
|
.Pp
|
.Pp
|
A
|
A
|
.Ql {\&
|
.Ql {\&
|
followed by a digit is considered the beginning of bounds for a
|
followed by a digit is considered the beginning of bounds for a
|
bounded repetition, which must then follow the syntax for bounds.
|
bounded repetition, which must then follow the syntax for bounds.
|
A
|
A
|
.Ql {\&
|
.Ql {\&
|
.Em not
|
.Em not
|
followed by a digit is considered an ordinary character.
|
followed by a digit is considered an ordinary character.
|
.Pp
|
.Pp
|
.Ql ^\&
|
.Ql ^\&
|
and
|
and
|
.Ql $\&
|
.Ql $\&
|
beginning and ending subexpressions in obsolete
|
beginning and ending subexpressions in obsolete
|
.Pq Dq basic
|
.Pq Dq basic
|
REs are anchors, not ordinary characters.
|
REs are anchors, not ordinary characters.
|
.Sh SEE ALSO
|
.Sh SEE ALSO
|
.Xr grep 1 ,
|
.Xr grep 1 ,
|
.Xr re_format 7
|
.Xr re_format 7
|
.Pp
|
.Pp
|
.St -p1003.2 ,
|
.St -p1003.2 ,
|
sections 2.8 (Regular Expression Notation)
|
sections 2.8 (Regular Expression Notation)
|
and
|
and
|
B.5 (C Binding for Regular Expression Matching).
|
B.5 (C Binding for Regular Expression Matching).
|
.Sh DIAGNOSTICS
|
.Sh DIAGNOSTICS
|
Non-zero error codes from
|
Non-zero error codes from
|
.Fn regcomp
|
.Fn regcomp
|
and
|
and
|
.Fn regexec
|
.Fn regexec
|
include the following:
|
include the following:
|
.Pp
|
.Pp
|
.Bl -tag -width REG_ECOLLATE -compact
|
.Bl -tag -width REG_ECOLLATE -compact
|
.It Dv REG_NOMATCH
|
.It Dv REG_NOMATCH
|
.Fn regexec
|
.Fn regexec
|
failed to match
|
failed to match
|
.It Dv REG_BADPAT
|
.It Dv REG_BADPAT
|
invalid regular expression
|
invalid regular expression
|
.It Dv REG_ECOLLATE
|
.It Dv REG_ECOLLATE
|
invalid collating element
|
invalid collating element
|
.It Dv REG_ECTYPE
|
.It Dv REG_ECTYPE
|
invalid character class
|
invalid character class
|
.It Dv REG_EESCAPE
|
.It Dv REG_EESCAPE
|
.Ql \e
|
.Ql \e
|
applied to unescapable character
|
applied to unescapable character
|
.It Dv REG_ESUBREG
|
.It Dv REG_ESUBREG
|
invalid backreference number
|
invalid backreference number
|
.It Dv REG_EBRACK
|
.It Dv REG_EBRACK
|
brackets
|
brackets
|
.Ql "[ ]"
|
.Ql "[ ]"
|
not balanced
|
not balanced
|
.It Dv REG_EPAREN
|
.It Dv REG_EPAREN
|
parentheses
|
parentheses
|
.Ql "( )"
|
.Ql "( )"
|
not balanced
|
not balanced
|
.It Dv REG_EBRACE
|
.It Dv REG_EBRACE
|
braces
|
braces
|
.Ql "{ }"
|
.Ql "{ }"
|
not balanced
|
not balanced
|
.It Dv REG_BADBR
|
.It Dv REG_BADBR
|
invalid repetition count(s) in
|
invalid repetition count(s) in
|
.Ql "{ }"
|
.Ql "{ }"
|
.It Dv REG_ERANGE
|
.It Dv REG_ERANGE
|
invalid character range in
|
invalid character range in
|
.Ql "[ ]"
|
.Ql "[ ]"
|
.It Dv REG_ESPACE
|
.It Dv REG_ESPACE
|
ran out of memory
|
ran out of memory
|
.It Dv REG_BADRPT
|
.It Dv REG_BADRPT
|
.Ql ?\& ,
|
.Ql ?\& ,
|
.Ql *\& ,
|
.Ql *\& ,
|
or
|
or
|
.Ql +\&
|
.Ql +\&
|
operand invalid
|
operand invalid
|
.It Dv REG_EMPTY
|
.It Dv REG_EMPTY
|
empty (sub)expression
|
empty (sub)expression
|
.It Dv REG_ASSERT
|
.It Dv REG_ASSERT
|
can't happen - you found a bug
|
can't happen - you found a bug
|
.It Dv REG_INVARG
|
.It Dv REG_INVARG
|
invalid argument, e.g. negative-length string
|
invalid argument, e.g. negative-length string
|
.El
|
.El
|
.Sh HISTORY
|
.Sh HISTORY
|
Originally written by
|
Originally written by
|
.An Henry Spencer .
|
.An Henry Spencer .
|
Altered for inclusion in the
|
Altered for inclusion in the
|
.Bx 4.4
|
.Bx 4.4
|
distribution.
|
distribution.
|
.Sh BUGS
|
.Sh BUGS
|
This is an alpha release with known defects.
|
This is an alpha release with known defects.
|
Please report problems.
|
Please report problems.
|
.Pp
|
.Pp
|
The back-reference code is subtle and doubts linger about its correctness
|
The back-reference code is subtle and doubts linger about its correctness
|
in complex cases.
|
in complex cases.
|
.Pp
|
.Pp
|
.Fn Regexec
|
.Fn Regexec
|
performance is poor.
|
performance is poor.
|
This will improve with later releases.
|
This will improve with later releases.
|
.Fa Nmatch
|
.Fa Nmatch
|
exceeding 0 is expensive;
|
exceeding 0 is expensive;
|
.Fa nmatch
|
.Fa nmatch
|
exceeding 1 is worse.
|
exceeding 1 is worse.
|
.Fn Regexec
|
.Fn Regexec
|
is largely insensitive to RE complexity
|
is largely insensitive to RE complexity
|
.Em except
|
.Em except
|
that back
|
that back
|
references are massively expensive.
|
references are massively expensive.
|
RE length does matter; in particular, there is a strong speed bonus
|
RE length does matter; in particular, there is a strong speed bonus
|
for keeping RE length under about 30 characters,
|
for keeping RE length under about 30 characters,
|
with most special characters counting roughly double.
|
with most special characters counting roughly double.
|
.Pp
|
.Pp
|
.Fn Regcomp
|
.Fn Regcomp
|
implements bounded repetitions by macro expansion,
|
implements bounded repetitions by macro expansion,
|
which is costly in time and space if counts are large
|
which is costly in time and space if counts are large
|
or bounded repetitions are nested.
|
or bounded repetitions are nested.
|
An RE like, say,
|
An RE like, say,
|
.Ql "((((a{1,100}){1,100}){1,100}){1,100}){1,100}"
|
.Ql "((((a{1,100}){1,100}){1,100}){1,100}){1,100}"
|
will (eventually) run almost any existing machine out of swap space.
|
will (eventually) run almost any existing machine out of swap space.
|
.Pp
|
.Pp
|
There are suspected problems with response to obscure error conditions.
|
There are suspected problems with response to obscure error conditions.
|
Notably,
|
Notably,
|
certain kinds of internal overflow,
|
certain kinds of internal overflow,
|
produced only by truly enormous REs or by multiply nested bounded repetitions,
|
produced only by truly enormous REs or by multiply nested bounded repetitions,
|
are probably not handled well.
|
are probably not handled well.
|
.Pp
|
.Pp
|
Due to a mistake in
|
Due to a mistake in
|
.St -p1003.2 ,
|
.St -p1003.2 ,
|
things like
|
things like
|
.Ql "a)b"
|
.Ql "a)b"
|
are legal REs because
|
are legal REs because
|
.Ql )\&
|
.Ql )\&
|
is
|
is
|
a special character only in the presence of a previous unmatched
|
a special character only in the presence of a previous unmatched
|
.Ql (\& .
|
.Ql (\& .
|
This can't be fixed until the spec is fixed.
|
This can't be fixed until the spec is fixed.
|
.Pp
|
.Pp
|
The standard's definition of back references is vague.
|
The standard's definition of back references is vague.
|
For example, does
|
For example, does
|
.Ql "a\e(\e(b\e)*\e2\e)*d"
|
.Ql "a\e(\e(b\e)*\e2\e)*d"
|
match
|
match
|
.Ql "abbbd" ?
|
.Ql "abbbd" ?
|
Until the standard is clarified,
|
Until the standard is clarified,
|
behavior in such cases should not be relied on.
|
behavior in such cases should not be relied on.
|
.Pp
|
.Pp
|
The implementation of word-boundary matching is a bit of a kludge,
|
The implementation of word-boundary matching is a bit of a kludge,
|
and bugs may lurk in combinations of word-boundary matching and anchoring.
|
and bugs may lurk in combinations of word-boundary matching and anchoring.
|
|
|
