lib/libcompat/regexp/regexp.3

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)regexp.3    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libcompat/regexp/regexp.3,v 1.6.2.2 2001/12/17 10:08:29 ru Exp $
  34 .\"
  35 .Dd June 4, 1993
  36 .Dt REGEXP 3
  37 .Os
  38 .Sh NAME
  39 .Nm regcomp ,
  40 .Nm regexec ,
  41 .Nm regsub ,
  42 .Nm regerror
  43 .Nd regular expression handlers
  44 .Sh LIBRARY
  45 .Lb libcompat
  46 .Sh SYNOPSIS
  47 .In regexp.h
  48 .Ft regexp *
  49 .Fn regcomp "const char *exp"
  50 .Ft int
  51 .Fn regexec "const regexp *prog" "const char *string"
  52 .Ft void
  53 .Fn regsub "const regexp *prog" "const char *source" "char *dest"
  54 .Sh DESCRIPTION
  55 .Bf Sy
  56 This interface is made obsolete by
  57 .Xr regex 3 .
  58 .Ef
  59 .Pp
  60 The
  61 .Fn regcomp ,
  62 .Fn regexec ,
  63 .Fn regsub ,
  64 and
  65 .Fn regerror
  66 functions
  67 implement
  68 .Xr egrep 1 Ns -style
  69 regular expressions and supporting facilities.
  70 .Pp
  71 The
  72 .Fn regcomp
  73 function
  74 compiles a regular expression into a structure of type
  75 .Xr regexp ,
  76 and returns a pointer to it.
  77 The space has been allocated using
  78 .Xr malloc 3
  79 and may be released by
  80 .Xr free .
  81 .Pp
  82 The
  83 .Fn regexec
  84 function
  85 matches a
  86 .Dv NUL Ns -terminated
  87 .Fa string
  88 against the compiled regular expression
  89 in
  90 .Fa prog .
  91 It returns 1 for success and 0 for failure, and adjusts the contents of
  92 .Fa prog Ns 's
  93 .Em startp
  94 and
  95 .Em endp
  96 (see below) accordingly.
  97 .Pp
  98 The members of a
  99 .Xr regexp
 100 structure include at least the following (not necessarily in order):
 101 .Bd -literal -offset indent
 102 char *startp[NSUBEXP];
 103 char *endp[NSUBEXP];
 104 .Ed
 105 .Pp
 106 where
 107 .Dv NSUBEXP
 108 is defined (as 10) in the header file.
 109 Once a successful
 110 .Fn regexec
 111 has been done using the
 112 .Fn regexp ,
 113 each
 114 .Em startp Ns - Em endp
 115 pair describes one substring
 116 within the
 117 .Fa string ,
 118 with the
 119 .Em startp
 120 pointing to the first character of the substring and
 121 the
 122 .Em endp
 123 pointing to the first character following the substring.
 124 The 0th substring is the substring of
 125 .Fa string
 126 that matched the whole
 127 regular expression.
 128 The others are those substrings that matched parenthesized expressions
 129 within the regular expression, with parenthesized expressions numbered
 130 in left-to-right order of their opening parentheses.
 131 .Pp
 132 The
 133 .Fn regsub
 134 function
 135 copies
 136 .Fa source
 137 to
 138 .Fa dest ,
 139 making substitutions according to the
 140 most recent
 141 .Fn regexec
 142 performed using
 143 .Fa prog .
 144 Each instance of `&' in
 145 .Fa source
 146 is replaced by the substring
 147 indicated by
 148 .Em startp Ns Bq
 149 and
 150 .Em endp Ns Bq .
 151 Each instance of
 152 .Sq \e Ns Em n ,
 153 where
 154 .Em n
 155 is a digit, is replaced by
 156 the substring indicated by
 157 .Em startp Ns Bq Em n
 158 and
 159 .Em endp Ns Bq Em n .
 160 To get a literal `&' or
 161 .Sq \e Ns Em n
 162 into
 163 .Fa dest ,
 164 prefix it with `\e';
 165 to get a literal `\e' preceding `&' or
 166 .Sq \e Ns Em n ,
 167 prefix it with
 168 another `\e'.
 169 .Pp
 170 The
 171 .Fn regerror
 172 function
 173 is called whenever an error is detected in
 174 .Fn regcomp ,
 175 .Fn regexec ,
 176 or
 177 .Fn regsub .
 178 The default
 179 .Fn regerror
 180 writes the string
 181 .Fa msg ,
 182 with a suitable indicator of origin,
 183 on the standard
 184 error output
 185 and invokes
 186 .Xr exit 3 .
 187 The
 188 .Fn regerror
 189 function
 190 can be replaced by the user if other actions are desirable.
 191 .Sh REGULAR EXPRESSION SYNTAX
 192 A regular expression is zero or more
 193 .Em branches ,
 194 separated by `|'.
 195 It matches anything that matches one of the branches.
 196 .Pp
 197 A branch is zero or more
 198 .Em pieces ,
 199 concatenated.
 200 It matches a match for the first, followed by a match for the second, etc.
 201 .Pp
 202 A piece is an
 203 .Em atom
 204 possibly followed by `*', `+', or `?'.
 205 An atom followed by `*' matches a sequence of 0 or more matches of the atom.
 206 An atom followed by `+' matches a sequence of 1 or more matches of the atom.
 207 An atom followed by `?' matches a match of the atom, or the null string.
 208 .Pp
 209 An atom is a regular expression in parentheses (matching a match for the
 210 regular expression), a
 211 .Em range
 212 (see below), `.'
 213 (matching any single character), `^' (matching the null string at the
 214 beginning of the input string), `$' (matching the null string at the
 215 end of the input string), a `\e' followed by a single character (matching
 216 that character), or a single character with no other significance
 217 (matching that character).
 218 .Pp
 219 A
 220 .Em range
 221 is a sequence of characters enclosed in `[]'.
 222 It normally matches any single character from the sequence.
 223 If the sequence begins with `^',
 224 it matches any single character
 225 .Em not
 226 from the rest of the sequence.
 227 If two characters in the sequence are separated by `\-', this is shorthand
 228 for the full list of
 229 .Tn ASCII
 230 characters between them
 231 (e.g. `[0-9]' matches any decimal digit).
 232 To include a literal `]' in the sequence, make it the first character
 233 (following a possible `^').
 234 To include a literal `\-', make it the first or last character.
 235 .Sh AMBIGUITY
 236 If a regular expression could match two different parts of the input string,
 237 it will match the one which begins earliest.
 238 If both begin in the same place but match different lengths, or match
 239 the same length in different ways, life gets messier, as follows.
 240 .Pp
 241 In general, the possibilities in a list of branches are considered in
 242 left-to-right order, the possibilities for `*', `+', and `?' are
 243 considered longest-first, nested constructs are considered from the
 244 outermost in, and concatenated constructs are considered leftmost-first.
 245 The match that will be chosen is the one that uses the earliest
 246 possibility in the first choice that has to be made.
 247 If there is more than one choice, the next will be made in the same manner
 248 (earliest possibility) subject to the decision on the first choice.
 249 And so forth.
 250 .Pp
 251 For example,
 252 .Sq Li (ab|a)b*c
 253 could match
 254 `abc' in one of two ways.
 255 The first choice is between `ab' and `a'; since `ab' is earlier, and does
 256 lead to a successful overall match, it is chosen.
 257 Since the `b' is already spoken for,
 258 the `b*' must match its last possibility\(emthe empty string\(emsince
 259 it must respect the earlier choice.
 260 .Pp
 261 In the particular case where no `|'s are present and there is only one
 262 `*', `+', or `?', the net effect is that the longest possible
 263 match will be chosen.
 264 So
 265 .Sq Li ab* ,
 266 presented with `xabbbby', will match `abbbb'.
 267 Note that if
 268 .Sq Li ab* ,
 269 is tried against `xabyabbbz', it
 270 will match `ab' just after `x', due to the begins-earliest rule.
 271 (In effect, the decision on where to start the match is the first choice
 272 to be made, hence subsequent choices must respect it even if this leads them
 273 to less-preferred alternatives.)
 274 .Sh RETURN VALUES
 275 The
 276 .Fn regcomp
 277 function
 278 returns
 279 .Dv NULL
 280 for a failure
 281 .Pf ( Fn regerror
 282 permitting),
 283 where failures are syntax errors, exceeding implementation limits,
 284 or applying `+' or `*' to a possibly-null operand.
 285 .Sh SEE ALSO
 286 .Xr ed 1 ,
 287 .Xr egrep 1 ,
 288 .Xr ex 1 ,
 289 .Xr expr 1 ,
 290 .Xr fgrep 1 ,
 291 .Xr grep 1 ,
 292 .Xr regex 3
 293 .Sh HISTORY
 294 Both code and manual page for
 295 .Fn regcomp ,
 296 .Fn regexec ,
 297 .Fn regsub ,
 298 and
 299 .Fn regerror
 300 were written at the University of Toronto
 301 and appeared in
 302 .Bx 4.3 tahoe .
 303 They are intended to be compatible with the Bell V8
 304 .Xr regexp 3 ,
 305 but are not derived from Bell code.
 306 .Sh BUGS
 307 Empty branches and empty regular expressions are not portable to V8.
 308 .Pp
 309 The restriction against
 310 applying `*' or `+' to a possibly-null operand is an artifact of the
 311 simplistic implementation.
 312 .Pp
 313 Does not support
 314 .Xr egrep Ns 's
 315 newline-separated branches;
 316 neither does the V8
 317 .Xr regexp 3 ,
 318 though.
 319 .Pp
 320 Due to emphasis on
 321 compactness and simplicity,
 322 it's not strikingly fast.
 323 It does give special attention to handling simple cases quickly.