regcmp(3C)


regcmp, regex -- regular expression handler

Synopsis

   char *regcmp (const char *string1, [char *string2...,] (char *)0);
   

char *regex (const char *re, const char *subject, ...); extern char *__loc1;

Description

The regcmp function compiles a regular expression consisting of the concatenated arguments and returns a pointer to the compiled form. The end of arguments is indicated by a null pointer. The malloc function is used to create space for the compiled form. It is the process' responsibility to free unneeded space so allocated. A NULL pointer returned from regcmp indicates an invalid argument.

The regex function executes a compiled pattern against the subject string. Additional arguments of type char * must be passed to receive matched subexpressions back.

A global character pointer __loc1 points to the first matched character in the subject string.

Both regcmp and regex were largely borrowed from the editor ed(1), but the syntax and semantics have been changed slightly. The following are the valid symbols and their associated meanings:


[]*.^
These symbols retain their meaning in ed(1).

$
Matches the end of the string; \n matches a newline.

-
Within brackets the minus means through. For example, [a-z] is equivalent to [abcd...xyz]. The - can appear as itself only if used as the first or last character. For example, the character class expression []-] matches the characters ] and -.

+
A regular expression followed by + means one or more times. For example, [0-9]+ is equivalent to [0-9][0-9]*.

{m} {m,} {m,u}
Integer values enclosed in {} indicate the number of times the preceding regular expression is to be applied. The value m is the minimum number and u is a number, less than 256, which is the maximum. If only m is present (that is, {m}), it indicates the exact number of times the regular expression is to be applied. The value {m,} is analogous to {m,infinity}. The plus (+) and star (*) operations are equivalent to {1,} and {0,} respectively.

( ... )$n
The value of the enclosed regular expression is to be returned. The value will be stored in the (n+1)th argument following the subject argument. At most, ten enclosed regular expressions are allowed. regex makes its assignments unconditionally.

( ... )
Parentheses are used for grouping. An operator, for example, *, +, {}, can work on a single character or a regular expression enclosed in parentheses. For example, (a*(cb+)*)$0.

By necessity, all the above defined symbols are special. They must, therefore, be escaped with a \ (backslash) to be used as themselves.

Examples

The following example matches a leading newline in the subject string pointed at by cursor.
   char *cursor, *newcursor, *ptr;
   	...
   newcursor = regex((ptr = regcmp("^\n", (char *)0)), cursor);
   free(ptr);

The following example matches through the string Testing3 and returns the address of the character after the last matched character (the ``4''). The string Testing3 is copied to the character array ret0.

   char ret0[9];
   char *newcursor, *name;
   	...
   name = regcmp("([A-Za-z][A-za-z0-9]{0,7})$0", (char *)0);
   newcursor = regex(name, "012Testing345", ret0);

The following example applies a precompiled regular expression in file.i [see regcmp(1)] against string.

   #include "file.i"
   char *string, *newcursor;
   	...
   newcursor = regex(name, string);

Return values

Upon successful completion, regcmp returns a pointer to the compiled regular expression. Otherwise, a NULL pointer is returned and errno is set to indicate the error.

Upon successful completion, regex returns a pointer to the next unmatched character in the subject string. Otherwise, a NULL pointer is returned. The regex function returns a NULL pointer on failure, or a pointer to the next unmatched character on success.

Errors

The regcmp function may fail if:

ENOMEM
Insufficient storage space was available.

Usage

User programs that use regcmp may run out of memory if regcmp is called iteratively without freeing compiled regular expression strings that are no longer required.

Compatibility

These functions were added to X/Open System Interfaces and Headers, Issue 4, Version 2, but are labelled to be withdrawn in a future issue. For portability, the routines documented on regcomp(3C) are preferred.

References

ed(1), regcmp(1), malloc(3C), regcomp(3C)

Standards conformance

These routines conform to X/Open System Interfaces and Headers, Issue 4, Version 2.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004