original/man3/regex.3

   1 .\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk)
  26 .\" Tiny change in formatting - aeb, 950812
  27 .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  28 .\"
  29 .\" show the synopsis section nicely
  30 .TH REGEX 3 2013-02-11 "GNU" "Linux Programmer's Manual"
  31 .SH NAME
  32 regcomp, regexec, regerror, regfree \- POSIX regex functions
  33 .SH SYNOPSIS
  34 .nf
  35 .B #include <sys/types.h>
  36 .B #include <regex.h>
  37
  38 .BI "int regcomp(regex_t *" preg ", const char *" regex ", int " cflags );
  39
  40 .BI "int regexec(const regex_t *" preg ", const char *" string \
  41 ", size_t " nmatch ,
  42 .BI "            regmatch_t " pmatch[] ", int " eflags );
  43
  44 .BI "size_t regerror(int " errcode ", const regex_t *" preg ", char *" errbuf ,
  45 .BI "                size_t " errbuf_size );
  46
  47 .BI "void regfree(regex_t *" preg );
  48 .fi
  49 .SH DESCRIPTION
  50 .SS POSIX regex compiling
  51 .BR regcomp ()
  52 is used to compile a regular expression into a form that is suitable
  53 for subsequent
  54 .BR regexec ()
  55 searches.
  56
  57 .BR regcomp ()
  58 is supplied with
  59 .IR preg ,
  60 a pointer to a pattern buffer storage area;
  61 .IR regex ,
  62 a pointer to the null-terminated string and
  63 .IR cflags ,
  64 flags used to determine the type of compilation.
  65
  66 All regular expression searching must be done via a compiled pattern
  67 buffer, thus
  68 .BR regexec ()
  69 must always be supplied with the address of a
  70 .BR regcomp ()
  71 initialized pattern buffer.
  72
  73 .I cflags
  74 may be the
  75 .RB bitwise- or
  76 of one or more of the following:
  77 .TP
  78 .B REG_EXTENDED
  79 Use
  80 .B POSIX
  81 Extended Regular Expression syntax when interpreting
  82 .IR regex .
  83 If not set,
  84 .B POSIX
  85 Basic Regular Expression syntax is used.
  86 .TP
  87 .B REG_ICASE
  88 Do not differentiate case.
  89 Subsequent
  90 .BR regexec ()
  91 searches using this pattern buffer will be case insensitive.
  92 .TP
  93 .B REG_NOSUB
  94 Do not report position of matches.
  95 The
  96 .I nmatch
  97 and
  98 .I pmatch
  99 arguments to
 100 .BR regexec ()
 101 are ignored if the pattern buffer supplied was compiled with this flag set.
 102 .TP
 103 .B REG_NEWLINE
 104 Match-any-character operators don't match a newline.
 105
 106 A nonmatching list
 107 .RB ( [^...] )
 108 not containing a newline does not match a newline.
 109
 110 Match-beginning-of-line operator
 111 .RB ( ^ )
 112 matches the empty string immediately after a newline, regardless of
 113 whether
 114 .IR eflags ,
 115 the execution flags of
 116 .BR regexec (),
 117 contains
 118 .BR REG_NOTBOL .
 119
 120 Match-end-of-line operator
 121 .RB ( $ )
 122 matches the empty string immediately before a newline, regardless of
 123 whether
 124 .I eflags
 125 contains
 126 .BR REG_NOTEOL .
 127 .SS POSIX regex matching
 128 .BR regexec ()
 129 is used to match a null-terminated string
 130 against the precompiled pattern buffer,
 131 .IR preg .
 132 .I nmatch
 133 and
 134 .I pmatch
 135 are used to provide information regarding the location of any matches.
 136 .I eflags
 137 may be the
 138 .RB bitwise- or
 139 of one or both of
 140 .B REG_NOTBOL
 141 and
 142 .B REG_NOTEOL
 143 which cause changes in matching behavior described below.
 144 .TP
 145 .B REG_NOTBOL
 146 The match-beginning-of-line operator always fails to match (but see the
 147 compilation flag
 148 .B REG_NEWLINE
 149 above).
 150 This flag may be used when different portions of a string are passed to
 151 .BR regexec ()
 152 and the beginning of the string should not be interpreted as the
 153 beginning of the line.
 154 .TP
 155 .B REG_NOTEOL
 156 The match-end-of-line operator always fails to match (but see the
 157 compilation flag
 158 .B REG_NEWLINE
 159 above).
 160 .SS Byte offsets
 161 Unless
 162 .B REG_NOSUB
 163 was set for the compilation of the pattern buffer, it is possible to
 164 obtain match addressing information.
 165 .I pmatch
 166 must be dimensioned to have at least
 167 .I nmatch
 168 elements.
 169 These are filled in by
 170 .BR regexec ()
 171 with substring match addresses.
 172 The offsets of the subexpression starting at the
 173 .IR i th
 174 open parenthesis are stored in
 175 .IR pmatch[i] .
 176 The entire regular expression's match addresses are stored in
 177 .IR pmatch[0] .
 178 (Note that to return the offsets of
 179 .I N
 180 subexpression matches,
 181 .I nmatch
 182 must be at least
 183 .IR N+1 .)
 184 Any unused structure elements will contain the value \-1.
 185
 186 The
 187 .I regmatch_t
 188 structure which is the type of
 189 .I pmatch
 190 is defined in
 191 .IR <regex.h> .
 192
 193 .in +4n
 194 .nf
 195 typedef struct {
 196     regoff_t rm_so;
 197     regoff_t rm_eo;
 198 } regmatch_t;
 199 .fi
 200 .in
 201
 202 Each
 203 .I rm_so
 204 element that is not \-1 indicates the start offset of the next largest
 205 substring match within the string.
 206 The relative
 207 .I rm_eo
 208 element indicates the end offset of the match,
 209 which is the offset of the first character after the matching text.
 210 .SS POSIX error reporting
 211 .BR regerror ()
 212 is used to turn the error codes that can be returned by both
 213 .BR regcomp ()
 214 and
 215 .BR regexec ()
 216 into error message strings.
 217
 218 .BR regerror ()
 219 is passed the error code,
 220 .IR errcode ,
 221 the pattern buffer,
 222 .IR preg ,
 223 a pointer to a character string buffer,
 224 .IR errbuf ,
 225 and the size of the string buffer,
 226 .IR errbuf_size .
 227 It returns the size of the
 228 .I errbuf
 229 required to contain the null-terminated error message string.
 230 If both
 231 .I errbuf
 232 and
 233 .I errbuf_size
 234 are nonzero,
 235 .I errbuf
 236 is filled in with the first
 237 .I "errbuf_size \- 1"
 238 characters of the error message and a terminating null byte (\(aq\\0\(aq).
 239 .SS POSIX pattern buffer freeing
 240 Supplying
 241 .BR regfree ()
 242 with a precompiled pattern buffer,
 243 .I preg
 244 will free the memory allocated to the pattern buffer by the compiling
 245 process,
 246 .BR regcomp ().
 247 .SH RETURN VALUE
 248 .BR regcomp ()
 249 returns zero for a successful compilation or an error code for failure.
 250
 251 .BR regexec ()
 252 returns zero for a successful match or
 253 .B REG_NOMATCH
 254 for failure.
 255 .SH ERRORS
 256 The following errors can be returned by
 257 .BR regcomp ():
 258 .TP
 259 .B REG_BADBR
 260 Invalid use of back reference operator.
 261 .TP
 262 .B REG_BADPAT
 263 Invalid use of pattern operators such as group or list.
 264 .TP
 265 .B REG_BADRPT
 266 Invalid use of repetition operators such as using \(aq*\(aq
 267 as the first character.
 268 .TP
 269 .B REG_EBRACE
 270 Un-matched brace interval operators.
 271 .TP
 272 .B REG_EBRACK
 273 Un-matched bracket list operators.
 274 .TP
 275 .B REG_ECOLLATE
 276 Invalid collating element.
 277 .TP
 278 .B REG_ECTYPE
 279 Unknown character class name.
 280 .TP
 281 .B REG_EEND
 282 Nonspecific error.
 283 This is not defined by POSIX.2.
 284 .TP
 285 .B REG_EESCAPE
 286 Trailing backslash.
 287 .TP
 288 .B REG_EPAREN
 289 Un-matched parenthesis group operators.
 290 .TP
 291 .B REG_ERANGE
 292 Invalid use of the range operator; for example, the ending point of the range
 293 occurs prior to the starting point.
 294 .TP
 295 .B REG_ESIZE
 296 Compiled regular expression requires a pattern buffer larger than 64Kb.
 297 This is not defined by POSIX.2.
 298 .TP
 299 .B REG_ESPACE
 300 The regex routines ran out of memory.
 301 .TP
 302 .B REG_ESUBREG
 303 Invalid back reference to a subexpression.
 304 .SH CONFORMING TO
 305 POSIX.1-2001.
 306 .SH SEE ALSO
 307 .BR grep (1),
 308 .BR regex (7)
 309 .br
 310 The glibc manual section,
 311 .I "Regular Expression Matching"
 312 .SH COLOPHON
 313 This page is part of release 3.68 of the Linux
 314 .I man-pages
 315 project.
 316 A description of the project,
 317 information about reporting bugs,
 318 and the latest version of this page,
 319 can be found at
 320 \%http://www.kernel.org/doc/man\-pages/.