regcomp()

Compile a regular expression

Synopsis:

#include <regex.h>

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

Arguments:

preg

A pointer to a regex_t object where the function can store the compiled regular expression.

pattern

The regular expression that you want to compile; see below.

cflags

A 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().

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Note: This function is in libc.a, but not in libc.so (in order to save space).

Description:

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 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.

Note: Strings used with this interface may only include the ASCII characters 0x0 to 0x7F.

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 the 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 the 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.1

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

Contributing author:

Henry Spencer. For license information, see “Licensing information” in Typographical Conventions, Support, and Licensing.