Standard C Library Functions                           regcmp(3C)



NAME
     regcmp, regex - compile and execute regular expression

SYNOPSIS
     #include 

     char *regcmp(const char *string1, /* char *string2 */ ...,
          int /*(char*)0*/);


     char *regex(const char *re, const char *subject,
          /* char *ret0 */ ...);


     extern char *loc1;


DESCRIPTION
     The regcmp() function compiles a  regular  expression  (con-
     sisting of the concatenated arguments) and returns a pointer
     to the compiled form.  The malloc(3C) function  is  used  to
     create space for the compiled form. It is the user's respon-
     sibility to free unneeded space so allocated. A NUL  return
     from regcmp() indicates an incorrect argument. regcmp(1) has
     been written to generally preclude the need for this routine
     at execution time.


     The regex() function executes a compiled pattern against the
     subject  string.  Additional arguments are passed to receive
     values back.  The regex() function returns NUL  on  failure
     or  a  pointer to the next unmatched character on success. A
     global character pointer loc1 points to  where  the  match
     began.   The regcmp() and regex() functions were mostly bor-
     rowed from the editor ed(1); however, the syntax and  seman-
     tics have been changed slightly. The following are the valid
     symbols and associated meanings.

     []*.^             This group of symbols retains its  meaning
                       as described on the regexp(5) manual page.


     $                 Matches the end of the string; \n  matches
                       a newline.


     -                 Within brackets the minus  means  through.
                       For   example,   [a-z]  is  equivalent  to
                       [abcd...xyz]. The - can appear  as  itself
                       only  if used as the first or last charac-
                       ter.  For  example,  the  character  class
                       expression  []-]  matches the characters ]



SunOS 5.11          Last change: 14 Nov 2002                    1






Standard C Library Functions                           regcmp(3C)



                       and -.


     ]                 A regular expression followed by  ]  means
                       one  or more times. For example, [0-9] is
                       equivalent to [0-9][0-9]*.


     {m} {m,} {m,u}    Integer values enclosed in {} 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 (that is, {m}), it indi-
                       cates the exact number of times the  regu-
                       lar 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  expres-
                       sion  is to be returned. The value will be
                       stored in the (n]1)th  argument  following
                       the   subject   argument.   At  most,  ten
                       enclosed regular expressions are  allowed.
                       The regex() function makes its assignments
                       unconditionally.


     ( ... )           Parentheses  are  used  for  grouping.  An
                       operator,  for example, *, ], {}, can work
                       on a single character or a regular expres-
                       sion enclosed in parentheses. For example,
                       (a*(cb])*)$0. By necessity, all the  above
                       defined  symbols  are  special. They must,
                       therefore, be escaped with a \ (backslash)
                       to be used as themselves.


EXAMPLES
     Example 1 Example matching a leading newline in the  subject
     string.


     The following example matches a leading newline in the  sub-
     ject string pointed at by cursor.


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



SunOS 5.11          Last change: 14 Nov 2002                    2






Standard C Library Functions                           regcmp(3C)



       free(ptr);



     The following example matches through  the  string  Testing3
     and  returns  the  address  of  the character after the last
     matched character   (the  ``4'').  The  string  Testing3  is
     copied to the character array ret0.


       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);



     The following example applies a precompiled regular  expres-
     sion in file.i (see regcmp(1)) against string.


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


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     ed(1), regcmp(1), malloc(3C), attributes(5), regexp(5)

NOTES
     The user program may run out of memory if regcmp() is called
     iteratively without freeing the vectors no longer required.


     When compiling multithreaded  applications,  the  RENTRANT
     flag  must be defined on the compile line.  This flag should
     only be used in multithreaded applications.



SunOS 5.11          Last change: 14 Nov 2002                    3