original/man3/regex.3

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