1 cfa37a7b 2004-04-10 devnull .TH REGEXP 3
  2 cfa37a7b 2004-04-10 devnull .SH NAME
  3 cfa37a7b 2004-04-10 devnull regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror \- regular expression
  4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
  5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
  6 cfa37a7b 2004-04-10 devnull .br
  7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
  8 cfa37a7b 2004-04-10 devnull .br
  9 cfa37a7b 2004-04-10 devnull .B #include <regexp.h>
 10 cfa37a7b 2004-04-10 devnull .PP
 11 cfa37a7b 2004-04-10 devnull .ta \w'\fLRegprog 'u
 12 cfa37a7b 2004-04-10 devnull .B
 13 cfa37a7b 2004-04-10 devnull Reprog	*regcomp(char *exp)
 14 cfa37a7b 2004-04-10 devnull .PP
 15 cfa37a7b 2004-04-10 devnull .B
 16 cfa37a7b 2004-04-10 devnull Reprog	*regcomplit(char *exp)
 17 cfa37a7b 2004-04-10 devnull .PP
 18 cfa37a7b 2004-04-10 devnull .B
 19 cfa37a7b 2004-04-10 devnull Reprog	*regcompnl(char *exp)
 20 cfa37a7b 2004-04-10 devnull .PP
 21 cfa37a7b 2004-04-10 devnull .nf
 22 cfa37a7b 2004-04-10 devnull .B
 23 cfa37a7b 2004-04-10 devnull int  regexec(Reprog *prog, char *string, Resub *match, int msize)
 24 cfa37a7b 2004-04-10 devnull .PP
 25 cfa37a7b 2004-04-10 devnull .nf
 26 cfa37a7b 2004-04-10 devnull .B
 27 cfa37a7b 2004-04-10 devnull void regsub(char *source, char *dest, int dlen, Resub *match, int msize)
 28 cfa37a7b 2004-04-10 devnull .PP
 29 cfa37a7b 2004-04-10 devnull .nf
 30 cfa37a7b 2004-04-10 devnull .B
 31 cfa37a7b 2004-04-10 devnull int  rregexec(Reprog *prog, Rune *string, Resub *match, int msize)
 32 cfa37a7b 2004-04-10 devnull .PP
 33 cfa37a7b 2004-04-10 devnull .nf
 34 cfa37a7b 2004-04-10 devnull .B
 35 cfa37a7b 2004-04-10 devnull void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, int msize)
 36 cfa37a7b 2004-04-10 devnull .PP
 37 cfa37a7b 2004-04-10 devnull .B
 38 cfa37a7b 2004-04-10 devnull void regerror(char *msg)
 39 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
 40 cfa37a7b 2004-04-10 devnull .I Regcomp
 41 cfa37a7b 2004-04-10 devnull compiles a
 42 cfa37a7b 2004-04-10 devnull regular expression and returns
 43 cfa37a7b 2004-04-10 devnull a pointer to the generated description.
 44 cfa37a7b 2004-04-10 devnull The space is allocated by
 45 d32deab1 2020-08-16 rsc .MR malloc (3)
 46 cfa37a7b 2004-04-10 devnull and may be released by
 47 cfa37a7b 2004-04-10 devnull .IR free .
 48 cfa37a7b 2004-04-10 devnull Regular expressions are exactly as in
 49 d32deab1 2020-08-16 rsc .MR regexp (7) .
 50 cfa37a7b 2004-04-10 devnull .PP
 51 cfa37a7b 2004-04-10 devnull .I Regcomplit
 52 cfa37a7b 2004-04-10 devnull is like
 53 cfa37a7b 2004-04-10 devnull .I regcomp
 54 cfa37a7b 2004-04-10 devnull except that all characters are treated literally.
 55 cfa37a7b 2004-04-10 devnull .I Regcompnl
 56 cfa37a7b 2004-04-10 devnull is like
 57 cfa37a7b 2004-04-10 devnull .I regcomp
 58 cfa37a7b 2004-04-10 devnull except that the
 59 cfa37a7b 2004-04-10 devnull .B .
 60 cfa37a7b 2004-04-10 devnull metacharacter matches all characters, including newlines.
 61 cfa37a7b 2004-04-10 devnull .PP
 62 cfa37a7b 2004-04-10 devnull .I Regexec
 63 cfa37a7b 2004-04-10 devnull matches a null-terminated
 64 cfa37a7b 2004-04-10 devnull .I string
 65 cfa37a7b 2004-04-10 devnull against the compiled regular expression in
 66 cfa37a7b 2004-04-10 devnull .IR prog .
 67 cfa37a7b 2004-04-10 devnull If it matches,
 68 cfa37a7b 2004-04-10 devnull .I regexec
 69 cfa37a7b 2004-04-10 devnull returns
 70 cfa37a7b 2004-04-10 devnull .B 1
 71 cfa37a7b 2004-04-10 devnull and fills in the array
 72 cfa37a7b 2004-04-10 devnull .I match
 73 cfa37a7b 2004-04-10 devnull with character pointers to the substrings of
 74 cfa37a7b 2004-04-10 devnull .I string
 75 cfa37a7b 2004-04-10 devnull that correspond to the
 76 cfa37a7b 2004-04-10 devnull parenthesized subexpressions of 
 77 cfa37a7b 2004-04-10 devnull .IR exp :
 78 cfa37a7b 2004-04-10 devnull .BI match[ i ].sp
 79 cfa37a7b 2004-04-10 devnull points to the beginning and
 80 cfa37a7b 2004-04-10 devnull .BI match[ i ].ep
 81 cfa37a7b 2004-04-10 devnull points just beyond
 82 cfa37a7b 2004-04-10 devnull the end of the
 83 cfa37a7b 2004-04-10 devnull .IR i th
 84 cfa37a7b 2004-04-10 devnull substring.
 85 cfa37a7b 2004-04-10 devnull (Subexpression
 86 cfa37a7b 2004-04-10 devnull .I i
 87 cfa37a7b 2004-04-10 devnull begins at the
 88 cfa37a7b 2004-04-10 devnull .IR i th
 89 cfa37a7b 2004-04-10 devnull left parenthesis, counting from 1.)
 90 cfa37a7b 2004-04-10 devnull Pointers in
 91 cfa37a7b 2004-04-10 devnull .B match[0]
 92 cfa37a7b 2004-04-10 devnull pick out the substring that corresponds to
 93 cfa37a7b 2004-04-10 devnull the whole regular expression.
 94 cfa37a7b 2004-04-10 devnull Unused elements of
 95 cfa37a7b 2004-04-10 devnull .I match
 96 cfa37a7b 2004-04-10 devnull are filled with zeros.
 97 cfa37a7b 2004-04-10 devnull Matches involving
 98 cfa37a7b 2004-04-10 devnull .LR * ,
 99 cfa37a7b 2004-04-10 devnull .LR + ,
100 cfa37a7b 2004-04-10 devnull and 
101 cfa37a7b 2004-04-10 devnull .L ?
102 cfa37a7b 2004-04-10 devnull are extended as far as possible.
103 cfa37a7b 2004-04-10 devnull The number of array elements in 
104 cfa37a7b 2004-04-10 devnull .I match
105 cfa37a7b 2004-04-10 devnull is given by
106 cfa37a7b 2004-04-10 devnull .IR msize .
107 cfa37a7b 2004-04-10 devnull The structure of elements of
108 cfa37a7b 2004-04-10 devnull .I match 
109 cfa37a7b 2004-04-10 devnull is:
110 cfa37a7b 2004-04-10 devnull .IP
111 cfa37a7b 2004-04-10 devnull .EX
112 cfa37a7b 2004-04-10 devnull typedef struct {
113 cfa37a7b 2004-04-10 devnull 	union {
114 cfa37a7b 2004-04-10 devnull 	   char *sp;
115 cfa37a7b 2004-04-10 devnull 	   Rune *rsp;
116 c8b6342d 2005-01-13 devnull 	} s;
117 cfa37a7b 2004-04-10 devnull 	union {
118 cfa37a7b 2004-04-10 devnull 	   char *ep;
119 cfa37a7b 2004-04-10 devnull 	   Rune *rep;
120 c8b6342d 2005-01-13 devnull 	} e;
121 cfa37a7b 2004-04-10 devnull } Resub;
122 cfa37a7b 2004-04-10 devnull .EE
123 cfa37a7b 2004-04-10 devnull .LP
124 cfa37a7b 2004-04-10 devnull If
125 c8b6342d 2005-01-13 devnull .B match[0].s.sp
126 cfa37a7b 2004-04-10 devnull is nonzero on entry,
127 cfa37a7b 2004-04-10 devnull .I regexec
128 cfa37a7b 2004-04-10 devnull starts matching at that point within
129 cfa37a7b 2004-04-10 devnull .IR string .
130 cfa37a7b 2004-04-10 devnull If
131 c8b6342d 2005-01-13 devnull .B match[0].e.ep
132 cfa37a7b 2004-04-10 devnull is nonzero on entry,
133 cfa37a7b 2004-04-10 devnull the last character matched is the one
134 cfa37a7b 2004-04-10 devnull preceding that point.
135 cfa37a7b 2004-04-10 devnull .PP
136 cfa37a7b 2004-04-10 devnull .I Regsub
137 cfa37a7b 2004-04-10 devnull places in
138 cfa37a7b 2004-04-10 devnull .I dest
139 cfa37a7b 2004-04-10 devnull a substitution instance of
140 cfa37a7b 2004-04-10 devnull .I source
141 cfa37a7b 2004-04-10 devnull in the context of the last
142 cfa37a7b 2004-04-10 devnull .I regexec
143 cfa37a7b 2004-04-10 devnull performed using
144 cfa37a7b 2004-04-10 devnull .IR match .
145 cfa37a7b 2004-04-10 devnull Each instance of
146 cfa37a7b 2004-04-10 devnull .BI \e n\f1,
147 cfa37a7b 2004-04-10 devnull where
148 cfa37a7b 2004-04-10 devnull .I n
149 cfa37a7b 2004-04-10 devnull is a digit, is replaced by the
150 cfa37a7b 2004-04-10 devnull string delimited by
151 cfa37a7b 2004-04-10 devnull .BI match[ n ].sp
152 cfa37a7b 2004-04-10 devnull and
153 cfa37a7b 2004-04-10 devnull .BI match[ n ].ep\f1.
154 cfa37a7b 2004-04-10 devnull Each instance of 
155 cfa37a7b 2004-04-10 devnull .L &
156 cfa37a7b 2004-04-10 devnull is replaced by the string delimited by
157 cfa37a7b 2004-04-10 devnull .B match[0].sp
158 cfa37a7b 2004-04-10 devnull and
159 cfa37a7b 2004-04-10 devnull .BR match[0].ep .
160 cfa37a7b 2004-04-10 devnull The substitution will always be null terminated and
161 cfa37a7b 2004-04-10 devnull trimmed to fit into dlen bytes.
162 cfa37a7b 2004-04-10 devnull .PP
163 cfa37a7b 2004-04-10 devnull .IR Regerror ,
164 cfa37a7b 2004-04-10 devnull called whenever an error is detected in
165 cfa37a7b 2004-04-10 devnull .IR regcomp ,
166 cfa37a7b 2004-04-10 devnull writes the string
167 cfa37a7b 2004-04-10 devnull .I msg
168 cfa37a7b 2004-04-10 devnull on the standard error file and exits.
169 cfa37a7b 2004-04-10 devnull .I Regerror
170 cfa37a7b 2004-04-10 devnull can be replaced to perform
171 cfa37a7b 2004-04-10 devnull special error processing.
172 cfa37a7b 2004-04-10 devnull If the user supplied
173 cfa37a7b 2004-04-10 devnull .I regerror
174 cfa37a7b 2004-04-10 devnull returns rather than exits,
175 cfa37a7b 2004-04-10 devnull .I regcomp
176 cfa37a7b 2004-04-10 devnull will return 0. 
177 cfa37a7b 2004-04-10 devnull .PP
178 cfa37a7b 2004-04-10 devnull .I Rregexec
179 cfa37a7b 2004-04-10 devnull and
180 cfa37a7b 2004-04-10 devnull .I rregsub
181 cfa37a7b 2004-04-10 devnull are variants of 
182 cfa37a7b 2004-04-10 devnull .I regexec
183 cfa37a7b 2004-04-10 devnull and
184 cfa37a7b 2004-04-10 devnull .I regsub
185 cfa37a7b 2004-04-10 devnull that use strings of
186 cfa37a7b 2004-04-10 devnull .B Runes
187 cfa37a7b 2004-04-10 devnull instead of strings of
188 cfa37a7b 2004-04-10 devnull .BR chars .
189 cfa37a7b 2004-04-10 devnull With these routines, the 
190 cfa37a7b 2004-04-10 devnull .I rsp
191 cfa37a7b 2004-04-10 devnull and
192 cfa37a7b 2004-04-10 devnull .I rep
193 cfa37a7b 2004-04-10 devnull fields of the
194 cfa37a7b 2004-04-10 devnull .I match
195 cfa37a7b 2004-04-10 devnull array elements should be used.
196 cfa37a7b 2004-04-10 devnull .SH SOURCE
197 c3674de4 2005-01-11 devnull .B \*9/src/libregexp
198 cfa37a7b 2004-04-10 devnull .SH "SEE ALSO"
199 d32deab1 2020-08-16 rsc .MR grep (1)
200 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
201 cfa37a7b 2004-04-10 devnull .I Regcomp
202 cfa37a7b 2004-04-10 devnull returns 
203 cfa37a7b 2004-04-10 devnull .B 0
204 cfa37a7b 2004-04-10 devnull for an illegal expression
205 cfa37a7b 2004-04-10 devnull or other failure.
206 cfa37a7b 2004-04-10 devnull .I Regexec
207 cfa37a7b 2004-04-10 devnull returns 0
208 cfa37a7b 2004-04-10 devnull if
209 cfa37a7b 2004-04-10 devnull .I string
210 cfa37a7b 2004-04-10 devnull is not matched.
211 cfa37a7b 2004-04-10 devnull .SH BUGS
212 cfa37a7b 2004-04-10 devnull There is no way to specify or match a NUL character; NULs terminate patterns and strings.