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