NAME

regcmp, regex - compile and execute a regular expression (LEGACY)

 SYNOPSIS

#include <libgen.h>

char *regcmp (const char *string1 , ... /*, (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. If an insufficient number of arguments is passed to accept all the values that the regular expression returns, the behaviour is undefined. 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, and are defined in re_comp(), but the syntax and semantics have been changed slightly. The following are the valid symbols and their associated meanings:

[]*.^

These symbols retain their meaning as defined in re_comp().

$

Matches the end of the string; \n matches a new-line.

-

Used within brackets, the hyphen signifies an ASCII character range. For example, [a-z] is equivalent to [abcd ... xyz] . The - can represent 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 can be applied. The value m is the minimum number and u is a number, less than 256, which is the maximum. If the value of either m or u is 256 or greater, the behaviour is undefined. The syntax {m} indicates the exact number of times the regular expression can be applied. The syntax {m,} is analogous to {m,infinity}. The plus (+) and asterisk (*) operations are equivalent to {1,} and {0,} respectively.

( ... )$n

The value of the enclosed regular expression is returned. The value is stored in the (n+1)th argument following the subject argument. A maximum of ten enclosed regular expressions are allowed. The regex() function makes its assignments unconditionally.

( ... )

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

Since all of the above defined symbols are special characters, they must be escaped to be used as themselves.

The behaviour of regcmp() and regex() in locales other than the POSIX locale is unspecified.

These interfaces need not be reentrant.

 RETURN VALUE

Upon successful completion, regcmp() returns a pointer to the compiled regular expression. Otherwise, a null pointer is returned and errno may be 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.

No errors are defined for regex().

 EXAMPLES

None.

 APPLICATION USAGE

For portability to implementations conforming to earlier versions of this specification, regcomp() is preferred over this function.

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.

 FUTURE DIRECTIONS

None.

 SEE ALSO

malloc(), regcomp(), <libgen.h>.