Libc-594.1.4.tar.gz

[apple/libc.git] / regex / regex.3

diff --git a/regex/regex.3 b/regex/regex.3
index d87164177b8a34be359a978c0118eb6c2ba86950..9f6b11554bff3fea9ac8bf34347343fa7e38365c 100644 (file)
--- a/regex/regex.3
+++ b/regex/regex.3
@@ -34,36 +34,46 @@
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)regex.3     8.4 (Berkeley) 3/20/94
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)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.17 2004/07/12 11:03:42 tjr Exp $

 .\"
 .\"

-.Dd March 20, 1994
+.Dd July 12, 2004

 .Dt REGEX 3
 .Os
 .Sh NAME
 .Nm regcomp ,
 .Dt REGEX 3
 .Os
 .Sh NAME
 .Nm regcomp ,

-.Nm regexec ,

 .Nm regerror ,
 .Nm regerror ,

+.Nm regexec ,

 .Nm regfree
 .Nd regular-expression library
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .Nm regfree
 .Nd regular-expression library
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS

-.In sys/types.h

 .In regex.h
 .Ft int
 .In regex.h
 .Ft int

-.Fn regcomp "regex_t *preg" "const char *pattern" "int cflags"
-.Ft int
-.Fo regexec
-.Fa "const regex_t *preg" "const char *string"
-.Fa "size_t nmatch" "regmatch_t pmatch[]" "int eflags"
+.Fo regcomp
+.Fa "regex_t *restrict preg"
+.Fa "const char *restrict pattern"
+.Fa "int cflags"

 .Fc
 .Ft size_t
 .Fo regerror
 .Fc
 .Ft size_t
 .Fo regerror

-.Fa "int errcode" "const regex_t *preg"
-.Fa "char *errbuf" "size_t errbuf_size"
+.Fa "int errcode"
+.Fa "const regex_t *restrict preg"
+.Fa "char *restrict errbuf"
+.Fa "size_t errbuf_size"
+.Fc
+.Ft int
+.Fo regexec
+.Fa "const regex_t *restrict preg"
+.Fa "const char *restrict string"
+.Fa "size_t nmatch"
+.Fa "regmatch_t pmatch[restrict]"
+.Fa "int eflags"

 .Fc
 .Ft void
 .Fc
 .Ft void

-.Fn regfree "regex_t *preg"
+.Fo regfree
+.Fa "regex_t *preg"
+.Fc

 .Sh DESCRIPTION
 These routines implement
 .St -p1003.2
 .Sh DESCRIPTION
 These routines implement
 .St -p1003.2


@@ -71,19 +81,20 @@ regular expressions
 .Pq Do RE Dc Ns s ;
 see
 .Xr re_format 7 .
 .Pq Do RE Dc Ns s ;
 see
 .Xr re_format 7 .

-.Fn Regcomp
-compiles an RE written as a string into an internal form,
+The
+.Fn regcomp
+function
+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,
-and
+transforms error codes from either into human-readable messages.

 .Fn regfree
 frees any dynamically-allocated storage used by the internal form
 of an RE.
 .Pp
 The header
 .Fn regfree
 frees any dynamically-allocated storage used by the internal form
 of an RE.
 .Pp
 The header

-.Aq Pa regex.h
+.In regex.h

 declares two structure types,
 .Ft regex_t
 and
 declares two structure types,
 .Ft regex_t
 and


@@ -95,7 +106,9 @@ a type
 and a number of constants with names starting with
 .Dq Dv REG_ .
 .Pp
 and a number of constants with names starting with
 .Dq Dv REG_ .
 .Pp

-.Fn Regcomp
+The
+.Fn regcomp
+function

 compiles the regular expression contained in the
 .Fa pattern
 string,
 compiles the regular expression contained in the
 .Fa pattern
 string,


@@ -105,7 +118,9 @@ and places the results in the
 .Ft regex_t
 structure pointed to by
 .Fa preg .
 .Ft regex_t
 structure pointed to by
 .Fa preg .

-.Fa Cflags
+The
+.Fa cflags
+argument

 is the bitwise OR of zero or more of the following flags:
 .Bl -tag -width REG_EXTENDED
 .It Dv REG_EXTENDED
 is the bitwise OR of zero or more of the following flags:
 .Bl -tag -width REG_EXTENDED
 .It Dv REG_EXTENDED


@@ -203,7 +218,9 @@ fails, it returns a non-zero error code;
 see
 .Sx DIAGNOSTICS .
 .Pp
 see
 .Sx DIAGNOSTICS .
 .Pp

-.Fn Regexec
+The
+.Fn regexec
+function

 matches the compiled RE pointed to by
 .Fa preg
 against the
 matches the compiled RE pointed to by
 .Fa preg
 against the


@@ -389,7 +406,9 @@ the value of
 will not be changed by a successful
 .Fn regexec .
 .Pp
 will not be changed by a successful
 .Fn regexec .
 .Pp

-.Fn Regerror
+The
+.Fn regerror
+function

 maps a non-zero
 .Fa errcode
 from either
 maps a non-zero
 .Fa errcode
 from either


@@ -412,11 +431,14 @@ it should have been the result from the most recent
 .Fn regcomp
 using that
 .Ft regex_t .
 .Fn regcomp
 using that
 .Ft regex_t .

-.No ( Fn Regerror
+The
+.Fn ( regerror

 may be able to supply a more detailed message using information
 from the
 .Ft regex_t . )
 may be able to supply a more detailed message using information
 from the
 .Ft regex_t . )

-.Fn Regerror
+The
+.Fn regerror
+function

 places the NUL-terminated message into the buffer pointed to by
 .Fa errbuf ,
 limiting the length (including the NUL) to at most
 places the NUL-terminated message into the buffer pointed to by
 .Fa errbuf ,
 limiting the length (including the NUL) to at most


@@ -473,7 +495,9 @@ and should be used with
 caution in software intended to be portable to other systems.
 Be warned also that they are considered experimental and changes are possible.
 .Pp
 caution in software intended to be portable to other systems.
 Be warned also that they are considered experimental and changes are possible.
 .Pp

-.Fn Regfree
+The
+.Fn regfree
+function

 frees any dynamically-allocated storage associated with the compiled RE
 pointed to by
 .Fa preg .
 frees any dynamically-allocated storage associated with the compiled RE
 pointed to by
 .Fa preg .


@@ -548,7 +572,7 @@ or
 .Ql |\&
 cannot appear first or last in a (sub)expression or after another
 .Ql |\& ,
 .Ql |\&
 cannot appear first or last in a (sub)expression or after another
 .Ql |\& ,

-i.e. an operand of
+i.e., an operand of

 .Ql |\&
 cannot be an empty subexpression.
 An empty parenthesized subexpression,
 .Ql |\&
 cannot be an empty subexpression.
 An empty parenthesized subexpression,


@@ -589,7 +613,9 @@ include the following:
 .Pp
 .Bl -tag -width REG_ECOLLATE -compact
 .It Dv REG_NOMATCH
 .Pp
 .Bl -tag -width REG_ECOLLATE -compact
 .It Dv REG_NOMATCH

+The

 .Fn regexec
 .Fn regexec

+function

 failed to match
 .It Dv REG_BADPAT
 invalid regular expression
 failed to match
 .It Dv REG_BADPAT
 invalid regular expression


@@ -633,7 +659,9 @@ empty (sub)expression
 .It Dv REG_ASSERT
 can't happen - you found a bug
 .It Dv REG_INVARG
 .It Dv REG_ASSERT
 can't happen - you found a bug
 .It Dv REG_INVARG

-invalid argument, e.g. negative-length string
+invalid argument, e.g.\& negative-length string
+.It Dv REG_ILLSEQ
+illegal byte sequence (bad multibyte character)

 .El
 .Sh HISTORY
 Originally written by
 .El
 .Sh HISTORY
 Originally written by


@@ -648,14 +676,20 @@ Please report problems.
 The back-reference code is subtle and doubts linger about its correctness
 in complex cases.
 .Pp
 The back-reference code is subtle and doubts linger about its correctness
 in complex cases.
 .Pp

-.Fn Regexec
+The
+.Fn regexec
+function

 performance is poor.
 This will improve with later releases.
 performance is poor.
 This will improve with later releases.

-.Fa Nmatch
+The
+.Fa nmatch
+argument

 exceeding 0 is expensive;
 .Fa nmatch
 exceeding 1 is worse.
 exceeding 0 is expensive;
 .Fa nmatch
 exceeding 1 is worse.

-.Fn Regexec
+The
+.Fn regexec
+function

 is largely insensitive to RE complexity
 .Em except
 that back
 is largely insensitive to RE complexity
 .Em except
 that back


@@ -664,7 +698,9 @@ RE length does matter; in particular, there is a strong speed bonus
 for keeping RE length under about 30 characters,
 with most special characters counting roughly double.
 .Pp
 for keeping RE length under about 30 characters,
 with most special characters counting roughly double.
 .Pp

-.Fn Regcomp
+The
+.Fn regcomp
+function

 implements bounded repetitions by macro expansion,
 which is costly in time and space if counts are large
 or bounded repetitions are nested.
 implements bounded repetitions by macro expansion,
 which is costly in time and space if counts are large
 or bounded repetitions are nested.