POSIX Regular Expression Compiling
----------------------------------

  With POSIX, you can only search for a given regular expression; you
can't match it.  To do this, you must first compile it in a pattern
buffer, using `regcomp'.

  To compile a pattern buffer, use:

     int
     regcomp (regex_t *PREG, const char *REGEX, int CFLAGS)

PREG is the initialized pattern buffer's address, REGEX is the regular
expression's address, and CFLAGS is the compilation flags, which Regex
considers as a collection of bits.  Here are the valid bits, as defined
in `regex.h':

`REG_EXTENDED'
     says to use POSIX Extended Regular Expression syntax; if this isn't
     set, then says to use POSIX Basic Regular Expression syntax.
     `regcomp' sets PREG's `syntax' field accordingly.

`REG_ICASE'
     says to ignore case; `regcomp' sets PREG's `translate' field to a
     translate table which ignores case, replacing anything you've put
     there before.

`REG_NOSUB'
     says to set PREG's `no_sub' field; see POSIX Matching., for
     what this means.

`REG_NEWLINE'
     says that a:

        * match-any-character operator (*note Match-any-character
          Operator::.) doesn't match a newline.

        * nonmatching list not containing a newline (*note List
          Operators::.) matches a newline.

        * match-beginning-of-line operator (
see Match-beginning-of-line Operator.) matches the empty string
          immediately after a newline, regardless of how `REG_NOTBOL'
          is set (see POSIX Matching., for an explanation of
          `REG_NOTBOL').

        * match-end-of-line operator (*note Match-beginning-of-line
          Operator::.) matches the empty string immediately before a
          newline, regardless of how `REG_NOTEOL' is set (*note POSIX
          Matching::., for an explanation of `REG_NOTEOL').

  If `regcomp' successfully compiles the regular expression, it returns
zero and sets `*PATTERN_BUFFER' to the compiled pattern. Except for
`syntax' (which it sets as explained above), it also sets the same
fields the same way as does the GNU compiling function (*note GNU
Regular Expression Compiling::.).

  If `regcomp' can't compile the regular expression, it returns one of
the error codes listed here.  (Except when noted differently, the
syntax of in all examples below is basic regular expression syntax.)

`REG_BADRPT'
     For example, the consecutive repetition operators `**' in `a**'
     are invalid.  As another example, if the syntax is extended
     regular expression syntax, then the repetition operator `*' with
     nothing on which to operate in `*' is invalid.

`REG_BADBR'
     For example, the COUNT `-1' in `a\{-1' is invalid.

`REG_EBRACE'
     For example, `a\{1' is missing a close-interval operator.

`REG_EBRACK'
     For example, `[a' is missing a close-list operator.

`REG_ERANGE'
     For example, the range ending point `z' that collates lower than
     does its starting point `a' in `[z-a]' is invalid.  Also, the
     range with the character class `[:alpha:]' as its starting point in
     `[[:alpha:]-|]'.

`REG_ECTYPE'
     For example, the character class name `foo' in `[[:foo:]' is
     invalid.

`REG_EPAREN'
     For example, `a\)' is missing an open-group operator and `\(a' is
     missing a close-group operator.

`REG_ESUBREG'
     For example, the back reference `\2' that refers to a nonexistent
     subexpression in `\(a\)\2' is invalid.

`REG_EEND'
     Returned when a regular expression causes no other more specific
     error.

`REG_EESCAPE'
     For example, the trailing backslash `\' in `a\' is invalid, as is
     the one in `\'.

`REG_BADPAT'
     For example, in the extended regular expression syntax, the empty
     group `()' in `a()b' is invalid.

`REG_ESIZE'
     Returned when a regular expression needs a pattern buffer larger
     than 65536 bytes.

`REG_ESPACE'
     Returned when a regular expression makes Regex to run out of
     memory.