GNU Regular Expression Compiling
--------------------------------

  In GNU, you can both match and search for a given regular expression.
To do either, you must first compile it in a pattern buffer (*note GNU
Pattern Buffers::.).

  Regular expressions match according to the syntax with which they were
compiled; with GNU, you indicate what syntax you want by setting the
variable `re_syntax_options' (declared in `regex.h' and defined in
`regex.c') before calling the compiling function, `re_compile_pattern'
(see below).  See Syntax Bits, and See Predefined Syntaxes.

  You can change the value of `re_syntax_options' at any time.
Usually, however, you set its value once and then never change it.

  `re_compile_pattern' takes a pattern buffer as an argument.  You must
initialize the following fields:

`translate initialization'
`translate'
     Initialize this to point to a translate table if you want one, or
     to zero if you don't.  We explain translate tables in *Note GNU
     Translate Tables::.

`fastmap'
     Initialize this to nonzero if you want a fastmap, or to zero if you
     don't.

`buffer'
`allocated'
     If you want `re_compile_pattern' to allocate memory for the
     compiled pattern, set both of these to zero.  If you have an
     existing block of memory (allocated with `malloc') you want Regex
     to use, set `buffer' to its address and `allocated' to its size (in
     bytes).

     `re_compile_pattern' uses `realloc' to extend the space for the
     compiled pattern as necessary.

  To compile a pattern buffer, use:

     char *
     re_compile_pattern (const char *REGEX, const int REGEX_SIZE,
                         struct re_pattern_buffer *PATTERN_BUFFER)

REGEX is the regular expression's address, REGEX_SIZE is its length,
and PATTERN_BUFFER is the pattern buffer's address.

  If `re_compile_pattern' successfully compiles the regular expression,
it returns zero and sets `*PATTERN_BUFFER' to the compiled pattern.  It
sets the pattern buffer's fields as follows:

`buffer'
     to the compiled pattern.

`used'
     to the number of bytes the compiled pattern in `buffer' occupies.

`syntax'
     to the current value of `re_syntax_options'.

`re_nsub'
     to the number of subexpressions in REGEX.

`fastmap_accurate'
     to zero on the theory that the pattern you're compiling is
     different than the one previously compiled into `buffer'; in that
     case (since you can't make a fastmap without a compiled pattern),
     `fastmap' would either contain an incompatible fastmap, or nothing
     at all.

  If `re_compile_pattern' can't compile REGEX, it returns an error
string corresponding to one of the errors listed in *Note POSIX Regular
Expression Compiling::.