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