[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/regex/re_format.7

Version: -  FREEBSD  -  FREEBSD10  -  FREEBSD9  -  FREEBSD92  -  FREEBSD91  -  FREEBSD90  -  FREEBSD8  -  FREEBSD82  -  FREEBSD81  -  FREEBSD80  -  FREEBSD7  -  FREEBSD74  -  FREEBSD73  -  FREEBSD72  -  FREEBSD71  -  FREEBSD70  -  FREEBSD6  -  FREEBSD64  -  FREEBSD63  -  FREEBSD62  -  FREEBSD61  -  FREEBSD60  -  FREEBSD5  -  FREEBSD55  -  FREEBSD54  -  FREEBSD53  -  FREEBSD52  -  FREEBSD51  -  FREEBSD50  -  FREEBSD4  -  FREEBSD3  -  FREEBSD22  -  cheribsd  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1  -  FREEBSD-LIBC  -  FREEBSD8-LIBC  -  FREEBSD7-LIBC  -  FREEBSD6-LIBC  -  GLIBC27 
SearchContext: -  none  -  3  -  10 

    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
    9 .\" modification, are permitted provided that the following conditions
   10 .\" are met:
   11 .\" 1. Redistributions of source code must retain the above copyright
   12 .\"    notice, this list of conditions and the following disclaimer.
   13 .\" 2. Redistributions in binary form must reproduce the above copyright
   14 .\"    notice, this list of conditions and the following disclaimer in the
   15 .\"    documentation and/or other materials provided with the distribution.
   16 .\" 3. All advertising materials mentioning features or use of this software
   17 .\"    must display the following acknowledgement:
   18 .\"     This product includes software developed by the University of
   19 .\"     California, Berkeley and its contributors.
   20 .\" 4. Neither the name of the University nor the names of its contributors
   21 .\"    may be used to endorse or promote products derived from this software
   22 .\"    without specific prior written permission.
   23 .\"
   24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
   25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
   28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   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 .\"     @(#)re_format.7 8.3 (Berkeley) 3/20/94
   37 .\" $FreeBSD: head/lib/libc/regex/re_format.7 213573 2010-10-08 12:40:16Z uqs $
   38 .\"
   39 .Dd March 20, 1994
   40 .Dt RE_FORMAT 7
   41 .Os
   42 .Sh NAME
   43 .Nm re_format
   44 .Nd POSIX 1003.2 regular expressions
   45 .Sh DESCRIPTION
   46 Regular expressions
   47 .Pq Dq RE Ns s ,
   48 as defined in
   49 .St -p1003.2 ,
   50 come in two forms:
   51 modern REs (roughly those of
   52 .Xr egrep 1 ;
   53 1003.2 calls these
   54 .Dq extended
   55 REs)
   56 and obsolete REs (roughly those of
   57 .Xr ed 1 ;
   58 1003.2
   59 .Dq basic
   60 REs).
   61 Obsolete REs mostly exist for backward compatibility in some old programs;
   62 they will be discussed at the end.
   63 .St -p1003.2
   64 leaves some aspects of RE syntax and semantics open;
   65 `\(dd' marks decisions on these aspects that
   66 may not be fully portable to other
   67 .St -p1003.2
   68 implementations.
   69 .Pp
   70 A (modern) RE is one\(dd or more non-empty\(dd
   71 .Em branches ,
   72 separated by
   73 .Ql \&| .
   74 It matches anything that matches one of the branches.
   75 .Pp
   76 A branch is one\(dd or more
   77 .Em pieces ,
   78 concatenated.
   79 It matches a match for the first, followed by a match for the second, etc.
   80 .Pp
   81 A piece is an
   82 .Em atom
   83 possibly followed
   84 by a single\(dd
   85 .Ql \&* ,
   86 .Ql \&+ ,
   87 .Ql \&? ,
   88 or
   89 .Em bound .
   90 An atom followed by
   91 .Ql \&*
   92 matches a sequence of 0 or more matches of the atom.
   93 An atom followed by
   94 .Ql \&+
   95 matches a sequence of 1 or more matches of the atom.
   96 An atom followed by
   97 .Ql ?\&
   98 matches a sequence of 0 or 1 matches of the atom.
   99 .Pp
  100 A
  101 .Em bound
  102 is
  103 .Ql \&{
  104 followed by an unsigned decimal integer,
  105 possibly followed by
  106 .Ql \&,
  107 possibly followed by another unsigned decimal integer,
  108 always followed by
  109 .Ql \&} .
  110 The integers must lie between 0 and
  111 .Dv RE_DUP_MAX
  112 (255\(dd) inclusive,
  113 and if there are two of them, the first may not exceed the second.
  114 An atom followed by a bound containing one integer
  115 .Em i
  116 and no comma matches
  117 a sequence of exactly
  118 .Em i
  119 matches of the atom.
  120 An atom followed by a bound
  121 containing one integer
  122 .Em i
  123 and a comma matches
  124 a sequence of
  125 .Em i
  126 or more matches of the atom.
  127 An atom followed by a bound
  128 containing two integers
  129 .Em i
  130 and
  131 .Em j
  132 matches
  133 a sequence of
  134 .Em i
  135 through
  136 .Em j
  137 (inclusive) matches of the atom.
  138 .Pp
  139 An atom is a regular expression enclosed in
  140 .Ql ()
  141 (matching a match for the
  142 regular expression),
  143 an empty set of
  144 .Ql ()
  145 (matching the null string)\(dd,
  146 a
  147 .Em bracket expression
  148 (see below),
  149 .Ql .\&
  150 (matching any single character),
  151 .Ql \&^
  152 (matching the null string at the beginning of a line),
  153 .Ql \&$
  154 (matching the null string at the end of a line), a
  155 .Ql \e
  156 followed by one of the characters
  157 .Ql ^.[$()|*+?{\e
  158 (matching that character taken as an ordinary character),
  159 a
  160 .Ql \e
  161 followed by any other character\(dd
  162 (matching that character taken as an ordinary character,
  163 as if the
  164 .Ql \e
  165 had not been present\(dd),
  166 or a single character with no other significance (matching that character).
  167 A
  168 .Ql \&{
  169 followed by a character other than a digit is an ordinary
  170 character, not the beginning of a bound\(dd.
  171 It is illegal to end an RE with
  172 .Ql \e .
  173 .Pp
  174 A
  175 .Em bracket expression
  176 is a list of characters enclosed in
  177 .Ql [] .
  178 It normally matches any single character from the list (but see below).
  179 If the list begins with
  180 .Ql \&^ ,
  181 it matches any single character
  182 (but see below)
  183 .Em not
  184 from the rest of the list.
  185 If two characters in the list are separated by
  186 .Ql \&- ,
  187 this is shorthand
  188 for the full
  189 .Em range
  190 of characters between those two (inclusive) in the
  191 collating sequence,
  192 .No e.g. Ql [0-9]
  193 in ASCII matches any decimal digit.
  194 It is illegal\(dd for two ranges to share an
  195 endpoint,
  196 .No e.g. Ql a-c-e .
  197 Ranges are very collating-sequence-dependent,
  198 and portable programs should avoid relying on them.
  199 .Pp
  200 To include a literal
  201 .Ql \&]
  202 in the list, make it the first character
  203 (following a possible
  204 .Ql \&^ ) .
  205 To include a literal
  206 .Ql \&- ,
  207 make it the first or last character,
  208 or the second endpoint of a range.
  209 To use a literal
  210 .Ql \&-
  211 as the first endpoint of a range,
  212 enclose it in
  213 .Ql [.\&
  214 and
  215 .Ql .]\&
  216 to make it a collating element (see below).
  217 With the exception of these and some combinations using
  218 .Ql \&[
  219 (see next paragraphs), all other special characters, including
  220 .Ql \e ,
  221 lose their special significance within a bracket expression.
  222 .Pp
  223 Within a bracket expression, a collating element (a character,
  224 a multi-character sequence that collates as if it were a single character,
  225 or a collating-sequence name for either)
  226 enclosed in
  227 .Ql [.\&
  228 and
  229 .Ql .]\&
  230 stands for the
  231 sequence of characters of that collating element.
  232 The sequence is a single element of the bracket expression's list.
  233 A bracket expression containing a multi-character collating element
  234 can thus match more than one character,
  235 e.g.\& if the collating sequence includes a
  236 .Ql ch
  237 collating element,
  238 then the RE
  239 .Ql [[.ch.]]*c
  240 matches the first five characters
  241 of
  242 .Ql chchcc .
  243 .Pp
  244 Within a bracket expression, a collating element enclosed in
  245 .Ql [=
  246 and
  247 .Ql =]
  248 is an equivalence class, standing for the sequences of characters
  249 of all collating elements equivalent to that one, including itself.
  250 (If there are no other equivalent collating elements,
  251 the treatment is as if the enclosing delimiters were
  252 .Ql [.\&
  253 and
  254 .Ql .] . )
  255 For example, if
  256 .Ql x
  257 and
  258 .Ql y
  259 are the members of an equivalence class,
  260 then
  261 .Ql [[=x=]] ,
  262 .Ql [[=y=]] ,
  263 and
  264 .Ql [xy]
  265 are all synonymous.
  266 An equivalence class may not\(dd be an endpoint
  267 of a range.
  268 .Pp
  269 Within a bracket expression, the name of a
  270 .Em character class
  271 enclosed in
  272 .Ql [:
  273 and
  274 .Ql :]
  275 stands for the list of all characters belonging to that
  276 class.
  277 Standard character class names are:
  278 .Bl -column "alnum" "digit" "xdigit" -offset indent
  279 .It Em "alnum   digit   punct"
  280 .It Em "alpha   graph   space"
  281 .It Em "blank   lower   upper"
  282 .It Em "cntrl   print   xdigit"
  283 .El
  284 .Pp
  285 These stand for the character classes defined in
  286 .Xr ctype 3 .
  287 A locale may provide others.
  288 A character class may not be used as an endpoint of a range.
  289 .Pp
  290 A bracketed expression like
  291 .Ql [[:class:]]
  292 can be used to match a single character that belongs to a character
  293 class.
  294 The reverse, matching any character that does not belong to a specific
  295 class, the negation operator of bracket expressions may be used:
  296 .Ql [^[:class:]] .
  297 .Pp
  298 There are two special cases\(dd of bracket expressions:
  299 the bracket expressions
  300 .Ql [[:<:]]
  301 and
  302 .Ql [[:>:]]
  303 match the null string at the beginning and end of a word respectively.
  304 A word is defined as a sequence of word characters
  305 which is neither preceded nor followed by
  306 word characters.
  307 A word character is an
  308 .Em alnum
  309 character (as defined by
  310 .Xr ctype 3 )
  311 or an underscore.
  312 This is an extension,
  313 compatible with but not specified by
  314 .St -p1003.2 ,
  315 and should be used with
  316 caution in software intended to be portable to other systems.
  317 .Pp
  318 In the event that an RE could match more than one substring of a given
  319 string,
  320 the RE matches the one starting earliest in the string.
  321 If the RE could match more than one substring starting at that point,
  322 it matches the longest.
  323 Subexpressions also match the longest possible substrings, subject to
  324 the constraint that the whole match be as long as possible,
  325 with subexpressions starting earlier in the RE taking priority over
  326 ones starting later.
  327 Note that higher-level subexpressions thus take priority over
  328 their lower-level component subexpressions.
  329 .Pp
  330 Match lengths are measured in characters, not collating elements.
  331 A null string is considered longer than no match at all.
  332 For example,
  333 .Ql bb*
  334 matches the three middle characters of
  335 .Ql abbbc ,
  336 .Ql (wee|week)(knights|nights)
  337 matches all ten characters of
  338 .Ql weeknights ,
  339 when
  340 .Ql (.*).*\&
  341 is matched against
  342 .Ql abc
  343 the parenthesized subexpression
  344 matches all three characters, and
  345 when
  346 .Ql (a*)*
  347 is matched against
  348 .Ql bc
  349 both the whole RE and the parenthesized
  350 subexpression match the null string.
  351 .Pp
  352 If case-independent matching is specified,
  353 the effect is much as if all case distinctions had vanished from the
  354 alphabet.
  355 When an alphabetic that exists in multiple cases appears as an
  356 ordinary character outside a bracket expression, it is effectively
  357 transformed into a bracket expression containing both cases,
  358 .No e.g. Ql x
  359 becomes
  360 .Ql [xX] .
  361 When it appears inside a bracket expression, all case counterparts
  362 of it are added to the bracket expression, so that (e.g.)
  363 .Ql [x]
  364 becomes
  365 .Ql [xX]
  366 and
  367 .Ql [^x]
  368 becomes
  369 .Ql [^xX] .
  370 .Pp
  371 No particular limit is imposed on the length of REs\(dd.
  372 Programs intended to be portable should not employ REs longer
  373 than 256 bytes,
  374 as an implementation can refuse to accept such REs and remain
  375 POSIX-compliant.
  376 .Pp
  377 Obsolete
  378 .Pq Dq basic
  379 regular expressions differ in several respects.
  380 .Ql \&|
  381 is an ordinary character and there is no equivalent
  382 for its functionality.
  383 .Ql \&+
  384 and
  385 .Ql ?\&
  386 are ordinary characters, and their functionality
  387 can be expressed using bounds
  388 .No ( Ql {1,}
  389 or
  390 .Ql {0,1}
  391 respectively).
  392 Also note that
  393 .Ql x+
  394 in modern REs is equivalent to
  395 .Ql xx* .
  396 The delimiters for bounds are
  397 .Ql \e{
  398 and
  399 .Ql \e} ,
  400 with
  401 .Ql \&{
  402 and
  403 .Ql \&}
  404 by themselves ordinary characters.
  405 The parentheses for nested subexpressions are
  406 .Ql \e(
  407 and
  408 .Ql \e) ,
  409 with
  410 .Ql \&(
  411 and
  412 .Ql \&)
  413 by themselves ordinary characters.
  414 .Ql \&^
  415 is an ordinary character except at the beginning of the
  416 RE or\(dd the beginning of a parenthesized subexpression,
  417 .Ql \&$
  418 is an ordinary character except at the end of the
  419 RE or\(dd the end of a parenthesized subexpression,
  420 and
  421 .Ql \&*
  422 is an ordinary character if it appears at the beginning of the
  423 RE or the beginning of a parenthesized subexpression
  424 (after a possible leading
  425 .Ql \&^ ) .
  426 Finally, there is one new type of atom, a
  427 .Em back reference :
  428 .Ql \e
  429 followed by a non-zero decimal digit
  430 .Em d
  431 matches the same sequence of characters
  432 matched by the
  433 .Em d Ns th
  434 parenthesized subexpression
  435 (numbering subexpressions by the positions of their opening parentheses,
  436 left to right),
  437 so that (e.g.)
  438 .Ql \e([bc]\e)\e1
  439 matches
  440 .Ql bb
  441 or
  442 .Ql cc
  443 but not
  444 .Ql bc .
  445 .Sh SEE ALSO
  446 .Xr regex 3
  447 .Rs
  448 .%T Regular Expression Notation
  449 .%R IEEE Std
  450 .%N 1003.2
  451 .%P section 2.8
  452 .Re
  453 .Sh BUGS
  454 Having two kinds of REs is a botch.
  455 .Pp
  456 The current
  457 .St -p1003.2
  458 spec says that
  459 .Ql \&)
  460 is an ordinary character in
  461 the absence of an unmatched
  462 .Ql \&( ;
  463 this was an unintentional result of a wording error,
  464 and change is likely.
  465 Avoid relying on it.
  466 .Pp
  467 Back references are a dreadful botch,
  468 posing major problems for efficient implementations.
  469 They are also somewhat vaguely defined
  470 (does
  471 .Ql a\e(\e(b\e)*\e2\e)*d
  472 match
  473 .Ql abbbd ? ) .
  474 Avoid using them.
  475 .Pp
  476 .St -p1003.2
  477 specification of case-independent matching is vague.
  478 The
  479 .Dq one case implies all cases
  480 definition given above
  481 is current consensus among implementors as to the right interpretation.
  482 .Pp
  483 The syntax for word boundaries is incredibly ugly.

Cache object: 1bd2eadc74466919f26492f3971cf292


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.