regcomp()

Compile a regular expression

Synopsis:

#include <regex.h>

int regcomp( regex_t * preg,
             const char * pattern,
             int cflags );

The regcomp() function prepares the regular expression, preg, for use by the function regexec(), from the specification pattern and cflags. The member re_nsub of preg is set to the number of subexpressions in pattern. The argument cflags is the bitwise inclusive OR of zero or more of the following flags:

REG_EXTENDED: Use Extended Regular Expressions.
REG_ICASE: Ignore differences in case.
REG_NEWLINE: Treat <newline> as a regular character.
REG_NOSUB: Report only success/failure in regexec().

The functions that deal with regular expressions (regcomp(), regerror(), regexec(), and regfree()) support two classes of regular expressions, the Basic and Extended Regular Expressions. These classes are rigorously defined in IEEE P1003.2, Regular Expression Notation.

Basic Regular Expressions

The Basic Regular Expressions are composed of these terms:

x$

x at end of line ($ must be the last term)

^x

x at beginning of line (^ must be first term)

x*

Zero or more occurrences of x

.

Any single character (except newline)

c

The character c

xc

x followed by the character c

cx

Character c followed by x

[cd]

The characters c or d

[c-d]

All characters between c and d, inclusive

[^c]

Any character but c

[[:classname:]]

Any of the following classes:

alnum
alpha
cntrl
digit
graph
lower
print
punct
space
upper
xdigit

[[=c=]]

All character in equivalence class with c

[[=.=]]

All collating elements

x{m,n}

m through n occurrences of x

\c

Character c even if c is an operator

$x$

A labeled subexpression x

\m

The mth subexpression encountered

xy

Expression x followed by y

Extended Regular Expressions

The Extended Regular Expressions also include:

x+: One or more occurrences of x
x?: Zero or one occurrences of x
(x): Subexpression x (for precedence handling)
x|y: Expression x OR y

Returns:

0: Success.
<>0: An error occurred (use regerror() to get an explanation).

Examples:

/*
    The following example prints out all lines
    from FILE "f" that match "pattern".
*/
#include <stdio.h>
#include <regex.h>
#include <limits.h>

#define BUFFER_SIZE   512

void grep( char* pattern, FILE* f )
  {
    int t;
    regex_t re;
    char    buffer[BUFFER_SIZE];

    if ((t=regcomp( &re, pattern, REG_NOSUB )) != 0) {
      regerror(t, &re, buffer, sizeof buffer);
      fprintf(stderr,"grep: %s (%s)\n",buffer,pattern);
      return;
    }
    while( fgets( buffer, BUFFER_SIZE, f ) != NULL ) {
      if( regexec( &re, buffer, 0, NULL, 0 ) == 0 ) {
        fputs( buffer, stdout );
      }
    }
    regfree( &re );
  }

Classification:

POSIX 1003.1a

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes

Author:

Henry Spencer. For copyright information, see Third-Party Copyright Notices in this reference.