'\"! tbl | mmdoc
'\"macro stdmacro
.if n .pH g3x.regcmp @(#)regcmp	40.12 of 10/27/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} regcmp 3G "Specialized Libraries" "\&"
.if \nX=1 .ds x} regcmp 3G "Specialized Libraries"
.if \nX=2 .ds x} regcmp 3G "" "\&"
.if \nX=3 .ds x} regcmp "" "" "\&"
.TH \*(x}
.SH NAME
\f4regcmp\f1, \f4regex\f1 \- compile and execute regular expression
.SH SYNOPSIS
\f4#include <libgen.h>\f1
.PP
.nf
\f4cc\f1 [\f2flag\fP \|.\|.\|.] \f2file\fP \|.\|.\|.  \f4\-lgen\f1 [\f2library\fP \|.\|.\|.]
.PP
\f4char \(**regcmp (const char \(**string1 [, char \(**string2, .\|.\|.],
    (char \(**)0);\f1
.PP
\f4char \(**regex (const char \(**re, const char \(**subject 
    [, char \(**ret0, .\|.\|.]);\f1
.PP
\f4extern char \(**_\^_loc1;\f1
.fi
.SH DESCRIPTION
\f4regcmp\fP
compiles a regular expression
(consisting of the concatenated arguments)
and returns a pointer to the compiled form.
\f4malloc\fP(3C)
is used to create space for the compiled form.
It is the user's responsibility to free unneeded space so allocated.
A
\f4NULL\fP
return from
\f4regcmp\fP
indicates an incorrect argument.
\f4regcmp\fP(1)
has been written to generally preclude the need
for this routine at execution time.
.PP
\f4regex\fP
executes a compiled pattern against the subject string.
Additional arguments are passed to receive values back.
\f4regex\fP
returns
\f4NULL\fP
on failure or a pointer to the next unmatched character on success.
A global character pointer
\f4__loc1\fP
points to where the match began.
\f4regcmp\fP
and
\f4regex\fP
were mostly borrowed from the editor,
\f4ed\fP(1);
however, the syntax and semantics have been changed slightly.
The following are the valid symbols and associated meanings.
.TP "\w'\f4(.\|.\|.\^)$n\f1\ \ \ 'u"
\f4[\|]\|\(**\|.^\f1
These symbols retain their meaning in 
\f4ed\fP(1).
.TP
\f4$\f1
Matches the end of the string; \f4\en\fP matches a newline.
.TP
\f4\-\f1
Within brackets the minus means
.IR through .
For example,
\f4[\^a\-z\^]\f1
is equivalent to
\f4[\^abcd\|.\|.\|.xyz\^]\f1.
The \f4\-\fP can
appear as itself only if used as the
first or last character.
For example, the character class expression
\f4[\^]\-\^]\f1
matches the characters
\f4]\f1 and \f4\-\f1.
.TP
\f4+\f1
A regular expression followed by \f4+\fP means
.IR "one or more times" .
For example,
\f4[0\-9]+\f1
is equivalent to
\f4[0\-9][0\-9]\(**.\f1
.TP
\f4{\f2m\fP} {\f2m,\fP} {\f2m,u\fP}\f1
Integer values enclosed in \f4{\|}\fP indicate the
number of times the preceding regular expression is to be applied.
The value
.I m\^
is the minimum number and
.I u\^
is a number, less than 256, which is the maximum.
If only
.I m\^
is present (i.e., \f4{\f2m\fP}\f1),
it indicates the exact number of times the regular
expression is to be applied.
The value
\f4{\f2m\fP,}\f1 is analogous to \f4{\f2m,infinity\f4}.\f1
The plus (\f4+\fP) and star (\f4\(**\fP) operations are
equivalent to \f4{1,}\fP and \f4{0,}\fP respectively.
.TP
\f4( .\|.\|. )$\f2n\^\fP\f1
The value of the enclosed regular expression is
to be returned.
The value
will be stored in the
(\f2n\f1+1)th
argument following the subject argument.
At most, ten enclosed regular expressions are allowed.
\f4regex\fP
makes its assignments unconditionally.
.br
.ne 5
.TP
\f4( .\|.\|. )\f1
Parentheses are used for grouping.
An operator, e.g.,
\f4\(**\f1, \f4+\f1, \f4{\|}\f1,
can work on a single character or a regular
expression enclosed in parentheses.
For example, \f4(a\(**(cb+)\(**)$0\fP.
.PP
By necessity, all the above defined symbols are special.
They must, therefore, be escaped with a \f4\e\fP (backslash) 
to be used as themselves.
.SH EXAMPLES
The following example matches a leading newline in the subject string
pointed at by cursor.
.PP
.RS
.ft 4
.nf
char \(**cursor, \(**newcursor, \(**ptr;
	\&.\|.\|.
newcursor = regex((ptr = regcmp("^\\n", (char \(**)0)), cursor);
free(ptr);
.ft 1
.fi
.RE
.PP
The following example matches through the string \f4Testing3\fP and returns
the address of the character after the last matched character 
(the ``\f4\&4\fP'').
The string \f4Testing3\fP is copied to the
character array
\f4ret0\fP.
.PP
.RS
.ft 4
.nf
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);
.fi
.ft 1
.RE
.PP
The following example applies a precompiled regular expression
in
\f4file.i\f1
[see
\f4regcmp\fP(1)]
against
.IR string .
.PP
.RS
.nf
.ft 4
#include "file.i"
char \(**string, \(**newcursor;
	\&.\|.\|.
newcursor = regex(name, string);
.ft 1
.fi
.RE
.SH SEE ALSO
\f4regcmp\fP(1), \f4malloc\fP(3C).
.br
\f4ed\fP(1) in the
\f2User's Reference Manual\f1.
.SH NOTES
The user program may run out of memory if
\f4regcmp\fP
is called iteratively without freeing the vectors no longer required.
.\"	@(#)regcmp.3x	6.3 of 10/20/83
.Ee
