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 2021-03-22 "GNU" "Linux Programmer's Manual"
  31 .SH NAME
  32 regcomp, regexec, regerror, regfree \- POSIX regex functions
  33 .SH SYNOPSIS
  34 .nf
  35 .B #include <regex.h>
  36 .PP
  37 .BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex ,
  38 .BI "            int " cflags );
  39 .BI "int regexec(const regex_t *restrict " preg \
  40 ", const char *restrict " string ,
  41 .BI "            size_t " nmatch ", regmatch_t " pmatch "[restrict]\
  42 , int " eflags );
  43 .PP
  44 .BI "size_t regerror(int " errcode ", const regex_t *restrict " preg ,
  45 .BI "            char *restrict " errbuf ", size_t " errbuf_size );
  46 .BI "void regfree(regex_t *" preg );
  47 .fi
  48 .SH DESCRIPTION
  49 .SS POSIX regex compiling
  50 .BR regcomp ()
  51 is used to compile a regular expression into a form that is suitable
  52 for subsequent
  53 .BR regexec ()
  54 searches.
  55 .PP
  56 .BR regcomp ()
  57 is supplied with
  58 .IR preg ,
  59 a pointer to a pattern buffer storage area;
  60 .IR regex ,
  61 a pointer to the null-terminated string and
  62 .IR cflags ,
  63 flags used to determine the type of compilation.
  64 .PP
  65 All regular expression searching must be done via a compiled pattern
  66 buffer, thus
  67 .BR regexec ()
  68 must always be supplied with the address of a
  69 .BR regcomp ()-initialized
  70 pattern buffer.
  71 .PP
  72 .I cflags
  73 is the
  74 .RB bitwise- or
  75 of zero or more of the following:
  76 .TP
  77 .B REG_EXTENDED
  78 Use
  79 .B POSIX
  80 Extended Regular Expression syntax when interpreting
  81 .IR regex .
  82 If not set,
  83 .B POSIX
  84 Basic Regular Expression syntax is used.
  85 .TP
  86 .B REG_ICASE
  87 Do not differentiate case.
  88 Subsequent
  89 .BR regexec ()
  90 searches using this pattern buffer will be case insensitive.
  91 .TP
  92 .B REG_NOSUB
  93 Do not report position of matches.
  94 The
  95 .I nmatch
  96 and
  97 .I pmatch
  98 arguments to
  99 .BR regexec ()
 100 are ignored if the pattern buffer supplied was compiled with this flag set.
 101 .TP
 102 .B REG_NEWLINE
 103 Match-any-character operators don't match a newline.
 104 .IP
 105 A nonmatching list
 106 .RB ( [\(ha...] )
 107 not containing a newline does not match a newline.
 108 .IP
 109 Match-beginning-of-line operator
 110 .RB ( \(ha )
 111 matches the empty string immediately after a newline, regardless of
 112 whether
 113 .IR eflags ,
 114 the execution flags of
 115 .BR regexec (),
 116 contains
 117 .BR REG_NOTBOL .
 118 .IP
 119 Match-end-of-line operator
 120 .RB ( $ )
 121 matches the empty string immediately before a newline, regardless of
 122 whether
 123 .I eflags
 124 contains
 125 .BR REG_NOTEOL .
 126 .SS POSIX regex matching
 127 .BR regexec ()
 128 is used to match a null-terminated string
 129 against the precompiled pattern buffer,
 130 .IR preg .
 131 .I nmatch
 132 and
 133 .I pmatch
 134 are used to provide information regarding the location of any matches.
 135 .I eflags
 136 is the
 137 .RB bitwise- or
 138 of zero or more of the following flags:
 139 .TP
 140 .B REG_NOTBOL
 141 The match-beginning-of-line operator always fails to match (but see the
 142 compilation flag
 143 .B REG_NEWLINE
 144 above).
 145 This flag may be used when different portions of a string are passed to
 146 .BR regexec ()
 147 and the beginning of the string should not be interpreted as the
 148 beginning of the line.
 149 .TP
 150 .B REG_NOTEOL
 151 The match-end-of-line operator always fails to match (but see the
 152 compilation flag
 153 .B REG_NEWLINE
 154 above).
 155 .TP
 156 .B REG_STARTEND
 157 Use
 158 .I pmatch[0]
 159 on the input string, starting at byte
 160 .I pmatch[0].rm_so
 161 and ending before byte
 162 .IR pmatch[0].rm_eo .
 163 This allows matching embedded NUL bytes
 164 and avoids a
 165 .BR strlen (3)
 166 on large strings.
 167 It does not use
 168 .I nmatch
 169 on input, and does not change
 170 .B REG_NOTBOL
 171 or
 172 .B REG_NEWLINE
 173 processing.
 174 This flag is a BSD extension, not present in POSIX.
 175 .SS Byte offsets
 176 Unless
 177 .B REG_NOSUB
 178 was set for the compilation of the pattern buffer, it is possible to
 179 obtain match addressing information.
 180 .I pmatch
 181 must be dimensioned to have at least
 182 .I nmatch
 183 elements.
 184 These are filled in by
 185 .BR regexec ()
 186 with substring match addresses.
 187 The offsets of the subexpression starting at the
 188 .IR i th
 189 open parenthesis are stored in
 190 .IR pmatch[i] .
 191 The entire regular expression's match addresses are stored in
 192 .IR pmatch[0] .
 193 (Note that to return the offsets of
 194 .I N
 195 subexpression matches,
 196 .I nmatch
 197 must be at least
 198 .IR N+1 .)
 199 Any unused structure elements will contain the value \-1.
 200 .PP
 201 The
 202 .I regmatch_t
 203 structure which is the type of
 204 .I pmatch
 205 is defined in
 206 .IR <regex.h> .
 207 .PP
 208 .in +4n
 209 .EX
 210 typedef struct {
 211     regoff_t rm_so;
 212     regoff_t rm_eo;
 213 } regmatch_t;
 214 .EE
 215 .in
 216 .PP
 217 Each
 218 .I rm_so
 219 element that is not \-1 indicates the start offset of the next largest
 220 substring match within the string.
 221 The relative
 222 .I rm_eo
 223 element indicates the end offset of the match,
 224 which is the offset of the first character after the matching text.
 225 .SS POSIX error reporting
 226 .BR regerror ()
 227 is used to turn the error codes that can be returned by both
 228 .BR regcomp ()
 229 and
 230 .BR regexec ()
 231 into error message strings.
 232 .PP
 233 .BR regerror ()
 234 is passed the error code,
 235 .IR errcode ,
 236 the pattern buffer,
 237 .IR preg ,
 238 a pointer to a character string buffer,
 239 .IR errbuf ,
 240 and the size of the string buffer,
 241 .IR errbuf_size .
 242 It returns the size of the
 243 .I errbuf
 244 required to contain the null-terminated error message string.
 245 If both
 246 .I errbuf
 247 and
 248 .I errbuf_size
 249 are nonzero,
 250 .I errbuf
 251 is filled in with the first
 252 .I "errbuf_size \- 1"
 253 characters of the error message and a terminating null byte (\(aq\e0\(aq).
 254 .SS POSIX pattern buffer freeing
 255 Supplying
 256 .BR regfree ()
 257 with a precompiled pattern buffer,
 258 .I preg
 259 will free the memory allocated to the pattern buffer by the compiling
 260 process,
 261 .BR regcomp ().
 262 .SH RETURN VALUE
 263 .BR regcomp ()
 264 returns zero for a successful compilation or an error code for failure.
 265 .PP
 266 .BR regexec ()
 267 returns zero for a successful match or
 268 .B REG_NOMATCH
 269 for failure.
 270 .SH ERRORS
 271 The following errors can be returned by
 272 .BR regcomp ():
 273 .TP
 274 .B REG_BADBR
 275 Invalid use of back reference operator.
 276 .TP
 277 .B REG_BADPAT
 278 Invalid use of pattern operators such as group or list.
 279 .TP
 280 .B REG_BADRPT
 281 Invalid use of repetition operators such as using \(aq*\(aq
 282 as the first character.
 283 .TP
 284 .B REG_EBRACE
 285 Un-matched brace interval operators.
 286 .TP
 287 .B REG_EBRACK
 288 Un-matched bracket list operators.
 289 .TP
 290 .B REG_ECOLLATE
 291 Invalid collating element.
 292 .TP
 293 .B REG_ECTYPE
 294 Unknown character class name.
 295 .TP
 296 .B REG_EEND
 297 Nonspecific error.
 298 This is not defined by POSIX.2.
 299 .TP
 300 .B REG_EESCAPE
 301 Trailing backslash.
 302 .TP
 303 .B REG_EPAREN
 304 Un-matched parenthesis group operators.
 305 .TP
 306 .B REG_ERANGE
 307 Invalid use of the range operator; for example, the ending point of the range
 308 occurs prior to the starting point.
 309 .TP
 310 .B REG_ESIZE
 311 Compiled regular expression requires a pattern buffer larger than 64\ kB.
 312 This is not defined by POSIX.2.
 313 .TP
 314 .B REG_ESPACE
 315 The regex routines ran out of memory.
 316 .TP
 317 .B REG_ESUBREG
 318 Invalid back reference to a subexpression.
 319 .SH ATTRIBUTES
 320 For an explanation of the terms used in this section, see
 321 .BR attributes (7).
 322 .ad l
 323 .nh
 324 .TS
 325 allbox;
 326 lbx lb lb
 327 l l l.
 328 Interface       Attribute       Value
 329 T{
 330 .BR regcomp (),
 331 .BR regexec ()
 332 T}      Thread safety   MT-Safe locale
 333 T{
 334 .BR regerror ()
 335 T}      Thread safety   MT-Safe env
 336 T{
 337 .BR regfree ()
 338 T}      Thread safety   MT-Safe
 339 .TE
 340 .hy
 341 .ad
 342 .sp 1
 343 .SH CONFORMING TO
 344 POSIX.1-2001, POSIX.1-2008.
 345 .SH EXAMPLES
 346 .EX
 347 #include <stdint.h>
 348 #include <stdio.h>
 349 #include <stdlib.h>
 350 #include <regex.h>
 351
 352 #define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0]))
 353
 354 static const char *const str =
 355         "1) John Driverhacker;\en2) John Doe;\en3) John Foo;\en";
 356 static const char *const re = "John.*o";
 357
 358 int main(void)
 359 {
 360     static const char *s = str;
 361     regex_t     regex;
 362     regmatch_t  pmatch[1];
 363     regoff_t    off, len;
 364
 365     if (regcomp(&regex, re, REG_NEWLINE))
 366         exit(EXIT_FAILURE);
 367
 368     printf("String = \e"%s\e"\en", str);
 369     printf("Matches:\en");
 370
 371     for (int i = 0; ; i++) {
 372         if (regexec(&regex, s, ARRAY_SIZE(pmatch), pmatch, 0))
 373             break;
 374
 375         off = pmatch[0].rm_so + (s \- str);
 376         len = pmatch[0].rm_eo \- pmatch[0].rm_so;
 377         printf("#%d:\en", i);
 378         printf("offset = %jd; length = %jd\en", (intmax_t) off,
 379                 (intmax_t) len);
 380         printf("substring = \e"%.*s\e"\en", len, s + pmatch[0].rm_so);
 381
 382         s += pmatch[0].rm_eo;
 383     }
 384
 385     exit(EXIT_SUCCESS);
 386 }
 387 .EE
 388 .SH SEE ALSO
 389 .BR grep (1),
 390 .BR regex (7)
 391 .PP
 392 The glibc manual section,
 393 .I "Regular Expressions"