REGCMP(3X)               DOMAIN/IX SYS5                REGCMP(3X)



NAME
     regcmp, regex - compile and execute regular expression

USAGE
     char *regcmp(string1 [, string2, ...], (char *)0)
     char *string1, *string2, ...;

     char *regex(re, subject[, ret0, ...])
     char *re, *subject, *ret0, ...;
     extern char *_loc1;


DESCRIPTION
     Regcmp compiles a regular expression and returns a pointer
     to the compiled form.  Malloc(3C) creates space for the vec-
     tor, though it does not automatically free unneeded space
     that was allocated.  A NULL return from regcmp indicates an
     incorrect argument.  Regcmp(1) was written to preclude the
     need to use this routine at execution time.

     Regex executes a compiled pattern against the subject
     string.  Additional arguments are passed to receive values
     back.  Regex returns NULL on failure, a pointer to the next
     unmatched character on success.  A global character pointer
     _loc1 points to where the match began.  Regcmp and regex
     derive from the editor, ed(1); however, the syntax and
     semantics have been changed slightly.

SYMBOLS
     The following are the valid symbols and their associated
     meanings.

     [ ]*.^    These symbols retain their current meaning.

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

     -         Within brackets, the minus means "through." For
               example, [a-z] is equivalent to [abcd...xyz].  The
               - can appear as itself only if it is used as the
               first or last character.  For example, the charac-
               ter 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}




Printed 12/4/86                                          REGCMP-1

REGCMP(3X)               DOMAIN/IX SYS5                REGCMP(3X)



     {m,}

     {m,u}     Integer values enclosed in braces indicate the
               number of times the preceding regular expression
               is to be applied.  The value m is the minimum
               number and u is a number, less than 256, which is
               the maximum.  If only m is present (e.g., {m}), it
               indicates the exact number of times the regular
               expression is to be applied.  The value {m,} is
               analogous to {m,infinity}.  The plus (+) and star
               (*) operations are equivalent to {1,} and {0,}
               respectively.

     ( ... )$n The value of the enclosed regular expression is to
               be returned.  The value will be stored in the
               argument following the subject argument.  At most,
               ten enclosed regular expressions are allowed.
               Regex makes its assignments unconditionally.

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

     By necessity, all the above defined symbols are special.
     They must, therefore, be escaped to be treated as literals.

EXAMPLES
     Example 1:

       char *cursor, *newcursor, *ptr;
            ...
       newcursor = regex((ptr = regcmp("^\n", 0)), cursor);
       free(ptr);

     This example will match a leading new-line in the subject
     string pointed at by cursor.

     Example 2:

       char ret0[9];
       char *newcursor, *name;
            ...
       name = regcmp("([A-Za-z][A-za-z0-9_]{0,7})$0", 0);
       newcursor = regex(name, "123Testing321", ret0);

     This example will match through the string "Testing3" and
     will return the address of the character after the last
     matched character (cursor+11).  The string "Testing3" will
     be copied to the character array "ret0."



REGCMP-2                                          Printed 12/4/86

REGCMP(3X)               DOMAIN/IX SYS5                REGCMP(3X)



     Example 3:

     #include "file.i"
     char *string, *newcursor;
          ...
     newcursor = regex(name, string);

     This example applies a precompiled regular expression in
     file.i (see regcmp(1)) against string.

     This routine is kept in the directory "/lib/libPW.a."

NOTES
     The user program may run out of memory if regcmp is called
     iteratively without first freeing those vectors that are no
     longer required.  The following user-supplied replacement
     for malloc(3C) reuses the same vector saving time and space:

       /* user's program */
            ...
       char *
       malloc(n)
       unsigned n;
       {
            static char rebuf[512];
            return (n <= sizeof rebuf) ? rebuf : NULL;
       }


RELATED INFORMATION
     ed(1), regcmp(1) malloc(3C)






















Printed 12/4/86                                          REGCMP-3