REGCOMP (3)
POSIX regex functions
SYNOPSIS
#include <regex.h>
\w'\fBint\ regcomp(\fR'u
int\ regcomp(regex_t * preg , const char * regex ,
int cflags );
\w'\fBint\ regexec(\fR'u
int\ regexec(const regex_t * preg , const char * string ,
size_t nmatch , regmatch_t pmatch[] ,
int eflags );
\w'\fBsize_t\ regerror(\fR'u
size_t\ regerror(int errcode ,
const regex_t * preg , char * errbuf ,
size_t errbuf_size );
\w'\fBvoid\ regfree(\fR'
void\ regfree(regex_t * preg );
POSIX REGEX COMPILING
regcomp
is used to compile a regular expression into a form that is suitable
for subsequent
regexec
searches.
regcomp
is supplied with
preg ,
a pointer to a pattern buffer storage area;
regex ,
a pointer to the null-terminated string and
cflags ,
flags used to determine the type of compilation.
All regular expression searching must be done via a compiled pattern
buffer, thus
regexec
must always be supplied with the address of a
regcomp
initialised pattern buffer.
cflags
may be the
bitwise- or
of one or more of the following:
REG_EXTENDED
Use
POSIX
Extended Regular Expression syntax when interpreting
regex .
If not set,
POSIX
Basic Regular Expression syntax is used.
REG_ICASE
Do not differentiate case. Subsequent
regexec
searches using this pattern buffer will be case insensitive.
REG_NOSUB
Support for substring addressing of matches is not required.
The
nmatch
and
pmatch
parameters to
regexec
are ignored if the pattern buffer supplied was compiled with this flag set.
REG_NEWLINE
Match-any-character operators don't match a newline.
A non-matching list
( [^...] )
not containing a newline does not match a newline.
Match-beginning-of-line operator
( ^ )
matches the empty string immediately after a newline, regardless of
whether
eflags ,
the execution flags of
regexec ,
contains
REG_NOTBOL .
Match-end-of-line operator
( $ )
matches the empty string immediately before a newline, regardless of
whether
eflags
contains
REG_NOTEOL .
POSIX REGEX MATCHING
regexec
is used to match a null-terminated string
against the precompiled pattern buffer,
preg .
nmatch
and
pmatch
are used to provide information regarding the location of any matches.
eflags
may be the
bitwise- or
of one or both of
REG_NOTBOL
and
REG_NOTEOL
which cause changes in matching behaviour described below.
REG_NOTBOL
The match-beginning-of-line operator always fails to match (but see the
compilation flag
REG_NEWLINE
above)
This flag may be used when different portions of a string are passed to
regexec
and the beginning of the string should not be interpreted as the
beginning of the line.
REG_NOTEOL
The match-end-of-line operator always fails to match (but see the
compilation flag
REG_NEWLINE
above)
Unless
REG_NOSUB
was set for the compilation of the pattern buffer, it is possible to
obtain substring match addressing information.
pmatch
must be dimensioned to have at least
nmatch
elements.
These are filled in by
regexec
with substring match addresses. Any unused structure elements
will contain the value -1.
The
regmatch_t
structure which is the type of
pmatch
is defined in
regex.h .
typedef struct
{
regoff_t rm_so ;
regoff_t rm_eo ;
}
regmatch_t;
Each
rm_so
element that is not -1 indicates the start offset of the next largest
substring match within the string. The relative
rm_eo
element indicates the end offset of the match.
POSIX ERROR REPORTING
regerror
is used to turn the error codes that can be returned by both
regcomp
and
regexec
into error message strings.
regerror
is passed the error code,
errcode ,
the pattern buffer,
preg ,
a pointer to a character string buffer,
errbuf ,
and the size of the string buffer,
errbuf_size .
It returns the size of the
errbuf
required to contain the null-terminated error message string. If both
errbuf
and
errbuf_size
are non-zero,
errbuf
is filled in with the first
errbuf_size - 1
characters of the error message and a terminating null.
POSIX PATTERN BUFFER FREEING
Supplying
regfree
with a precompiled pattern buffer,
preg
will free the memory allocated to the pattern buffer by the compiling
process,
regcomp .
RETURN VALUE
ERRORS
The following errors can be returned by
regcomp :
REG_BADRPT
Invalid use of repetition operators such as using
` * '
as the first character.
REG_BADBR
Invalid use of back reference operator.
REG_EBRACE
Un-matched brace interval operators.
REG_EBRACK
Un-matched bracket list operators.
REG_ERANGE
Invalid use of the range operator, eg. the ending point of the range
occurs prior to the starting point.
REG_ECTYPE
Unknown character class name.
REG_ECOLLATE
Invalid collating element.
REG_EPAREN
Un-matched parenthesis group operators.
REG_ESUBREG
Invalid back reference to a subexpression.
REG_EEND
Non specific error. This is not defined by POSIX.2.
REG_EESCAPE
REG_BADPAT
Invalid use of pattern operators such as group or list.
REG_ESIZE
Compiled regular expression requires a pattern buffer larger than 64Kb.
This is not defined by POSIX.2.
REG_ESPACE
The regex routines ran out of memory.
CONFORMING TO
BUGS
Currently (GNU libc snapshot 980503), GNU libc does not support
collating elements in regular expressions.
SEE ALSO
- regex (7) -
GNU regex manual man3/regex 3 ' " ' " Copyright(c) 1994 The Regents of the University of California ' " Copyright(c) 1994-1996 Sun Microsystems Inc ' " ' " See the file "license terms" for information on usage and redistribution ' " of this file and for a DISCLAIMER OF ALL WARRANTIES ' " ' " RCS: @(#) $Id: RegExp (3) v 1 2 1998/09/14 18:39:50 stanton Exp $ ' " ' " The definitions below are for supplemental macros used in Tcl/Tk ' " manual entries ' " ' " AP type name in/out ?indent? ' " Start paragraph describing an argument to a library procedure ' " type is type of argument(int etc ) in/out is either "in" "out" ' " or "in/out" to describe whether procedure reads or modifies arg ' " and indent is equivalent to second arg of IP(shouldn't ever be ' " needed; use AS below instead) ' " ' " AS ?type? ?name? ' " Give maximum sizes of arguments for setting tab stops Type and ' " name are examples of largest possible arguments that will be passed ' " to AP later If args are omitted default tab stops are used ' " ' " BS ' " Start box enclosure From here until next BE everything will be ' " enclosed in one large box ' " ' " BE ' " End of box enclosure ' " ' " CS ' " Begin code excerpt ' " ' " CE ' " End code excerpt ' " ' " VS ?version? ?br? ' " Begin vertical sidebar for use in marking newly-changed parts ' " of man pages The first argument is ignored and used for recording ' " the version when the VS was added so that the sidebars can be ' " found and removed when they reach a certain age If another argument ' " is present then a line break is forced before starting the sidebar ' " ' " VE ' " End of vertical sidebar ' " ' " DS ' " Begin an indented unfilled display ' " ' " DE ' " End of indented unfilled display ' " ' " SO ' " Start of list of standard options for a Tk widget The ' " options follow on successive lines in four columns separated ' " by tabs ' " ' " SE ' " End of list of standard options for a Tk widget ' " ' " OP cmdName dbName dbClass ' " Start of description of a specific option cmdName gives the ' " option's name as specified in the class command dbName gives ' " the option's name in the option database and dbClass gives ' " the option's class in the option database ' " ' " UL arg1 arg2 ' " Print arg1 underlined then print arg2 normally ' " ' " RCS: @(#) $Id: man macros v 1 2 1998/09/14 18:39:54 stanton Exp $ ' " ' " # Set up traps and other miscellaneous stuff for Tcl/Tk man pages t wh -1 3i ^B ^l n( l b ' " # Start an argument description AP !" $4"" TP $4 { !" $2"" TP n()Cu 15
|
|
