1 .TH ACME 3
2 .SH NAME
3 Event, Win,
4 eventfmt,
5 newwin,
6 pipetowin,
7 pipewinto,
8 sysrun,
9 winaddr,
10 winclosefiles,
11 winctl,
12 windel,
13 windeleteall,
14 windows,
15 wineventchan,
16 winfd,
17 winfree,
18 winmread,
19 winname,
20 winopenfd,
21 winprint,
22 winread,
23 winreadaddr,
24 winreadevent,
25 winseek,
26 winwrite,
27 winwriteevent \- acme client library
28 .SH SYNOPSIS
29 .ft L
30 .nf
31 #include <u.h>
32 #include <libc.h>
33 #include <thread.h>
34 #include <9pclient.h>
35 #include <acme.h>
36 .fi
37 .PP
38 .ft L
39 .ta +\w'\fLxxxx'u +\w'\fLxxxxx'u
40 .nf
41 struct Event
42 {
43 	int	c1;
44 	int	c2;
45 	int	q0;
46 	int	q1;
47 	int	oq0;
48 	int	oq1;
49 	int	flag;
50 	int	nb;
51 	int	nr;
52 	char	text[];
53 	char	arg[];
54 	char	loc[];
55 };
56 .PP
57 .ta +\w'\fLxxxxxxxxxx'u
58 .B
59 int	eventfmt(Fmt *fmt)
60 .PP
61 .B
62 Win*	newwin(void)
63 .PP
64 .B
65 Win*	openwin(int id, CFid *ctlfid)
66 .PP
67 .B
68 int	pipetowin(Win *w, char *file, int fderr, char *fmt, ...)
69 .PP
70 .B
71 int	pipewinto(Win *w, char *file, int fdout, char *fmt, ...)
72 .PP
73 .B
74 char*	sysrun(char *fmt, ...)
75 .PP
76 .B
77 int	winaddr(Win *w, char *fmt, ...)
78 .PP
79 .B
80 void	winclosefiles(Win *w)
81 .PP
82 .B
83 int	winctl(Win *w, char *fmt, ...)
84 .PP
85 .B
86 int	windel(Win *w, int sure)
87 .PP
88 .B
89 void	windeleteall(void)
90 .PP
91 .B
92 Channel*	wineventchan(Win *w)
93 .PP
94 .B
95 int	winfd(Win *w, char *name, int mode)
96 .PP
97 .B
98 void	winfree(Win *w)
99 .PP
100 .B
101 char*	winmread(Win *w, char *file)
102 .PP
103 .B
104 int	winname(Win *w, char *fmt, ...)
105 .PP
106 .B
107 int	winopenfd(Win *w, char *name, int mode)
108 .PP
109 .B
110 int	winprint(Win *w, char *file, char *fmt, ...)
111 .PP
112 .B
113 int	winread(Win *w, char *file, void *a, int n)
114 .PP
115 .B
116 int	winreadaddr(Win *w, uint *q1)
117 .PP
118 .B
119 int	winreadevent(Win *w, Event *e)
120 .PP
121 .B
122 int	winseek(Win *w, char *file, int off, int type)
123 .PP
124 .B
125 int	winwrite(Win *w, char *file, void *a, int n)
126 .PP
127 .B
128 int	winwriteevent(Win *w, Event *e)
129 .PP
130 .B
131 void*	emalloc(uint n)
132 .PP
133 .B
134 void*	erealloc(void *v, uint n)
135 .PP
136 .B
137 char*	estrdup(char *s)
138 .PP
139 .B
140 char*	evsmprint(char *fmt, va_list arg)
141 .SH DESCRIPTION
142 .I Libacme
143 provides a simple C interface for interacting with
144 .MR acme (1)
145 windows.
146 .PP
147 A
148 .B Win
149 structure represents a single window and its control files.
150 The contents of the structure should not be accessed directly.
151 .I Newwin
152 creates a new window and returns a structure corresponding to that window.
153 .I Openwin
154 allocates a structure corresponding to the existing window with the given
155 .IR id .
156 If
157 .I ctlfid
158 is non-nil, 
159 .I openwin
160 assumes it is a file descriptor open for writing to the window's
161 .B ctl
162 file.
163 Ownership of
164 .I ctlfid
165 passes to the library.
166 .PP
167 Most of the library routines access files in the window's
168 .I acme
169 directory.
170 See
171 .MR acme (4)
172 for details.
173 Many library routines take a format string
174 .I fmt
175 followed by a variable list of arguments.
176 In the discussion below, the notation
177 .I fmt\fR, \fP...
178 denotes the result of formatting the string and arguments
179 using
180 .I smprint
181 (see
182 .MR print (3) ).
183 .PP
184 .I Pipetowin
185 runs the
186 .MR rc (1)
187 command line
188 .I fmt\fR, \fP...
189 with 
190 .B /dev/null
191 on standard input and the window's
192 .I file
193 on standard output.
194 If
195 .I fderr
196 is non-zero (sic), 
197 it is used as standard error.
198 Otherwise the command inherits the caller's standard error.
199 .PP
200 .I Pipewinto
201 runs the 
202 .MR rc (1)
203 command line
204 .I fmt\fR, \fP...
205 with the window's
206 .I file
207 on standard input.
208 The command runs with
209 .I fdout 
210 as its standard output and standard error.
211 .PP
212 .I Sysrun
213 runs the
214 .I rc
215 command line
216 .I fmt\fR, \fP...
217 and returns a pointer to the first kilobyte of output, NUL-terminated.
218 The buffer holding the output is reused on each call.
219 .PP
220 .I Winaddr
221 writes
222 .I fmt\fR, \fP...
223 to the window's
224 .B addr
225 file.
226 .PP
227 .I Winclosefiles
228 closes all the open file descriptors associated with the window.
229 (These file descriptors are maintained from the library and 
230 cached across calls to 
231 .IR winctl ,
232 .IR etc .)
233 .PP
234 .I Winctl
235 writes
236 .I fmt\fR, \fP...
237 to the window's
238 .B ctl
239 file.
240 .PP
241 .I Windel
242 deletes the window,
243 writing
244 .B del
245 (or, if
246 .I sure
247 is set,
248 .B delete)
249 to the window's
250 .B ctl
251 file.
252 .PP
253 .I Winfd
254 returns a file descriptor for the window's
255 .I file
256 opened for
257 .IR mode .
258 The caller is responsible for closing the file descriptor.
259 .PP
260 .I Winmread
261 reads the contents of the window's
262 .I file
263 into a dynamically allocated buffer
264 and returns it.
265 The caller is responsible for freeing the buffer.
266 .PP
267 .I Winname
268 sets the name of the window to
269 .I fmt\fR, \fP...
270 by writing to the
271 .B ctl
272 file.
273 .PP
274 .I Winprint
275 prints
276 .I fmt\fR, \fP...
277 to the window's
278 .IR file .
279 .PP
280 .I Winread
281 reads at most 
282 .I n
283 bytes from the window's
284 .IR file
285 into the buffer pointed at by
286 .IR a .
287 .PP
288 .I Winreadaddr
289 reads the window's
290 .B addr
291 file, which contains two integers.
292 It returns the first and stores the second in 
293 .BI * q1 \fR.
294 .PP
295 .I Winseek
296 seeks the file descriptor for the window's
297 .I file
298 to position
299 .I off
300 relative to
301 .I type
302 (see
303 .MR seek (3) ).
304 .PP
305 .I Winwrite
306 writes the
307 .I n
308 bytes pointed at by
309 .I a
310 to the window's
311 .IR file .
312 .PP
313 An
314 .B Event
315 structure represents an event originating in a particular window.
316 The fields correspond to the fields in
317 .IR acme 's
318 event messages.
319 See 
320 .MR acme (4)
321 for detailed explanations.
322 The fields are:
323 .TP
324 .BR c1 ", " c2
325 The two event characters, indicating origin and type of action.
326 .TP
327 .BR q0 ", " q1
328 The character addresses of the action.
329 If the original event had an empty selection
330 .RB ( q0 = q1 )
331 and was accompanied by an expansion
332 (the 2 bit is set in the flag), then 
333 .B q0
334 and
335 .B q1
336 will indicate the expansion rather than original event.
337 .TP
338 .BR oq0 ", " oq1
339 The 
340 .B q0
341 and
342 .B q1
343 of the original event, even if it was expanded.
344 If there was no expansion,
345 .BR oq0 = q0
346 and
347 .BR oq1 = q1 .
348 .TP
349 .B flag
350 The flag.
351 .TP
352 .B nr
353 The number of characters (UTF sequences) included in the optional text.
354 .TP
355 .B text
356 The optional text itself, encoded in UTF.
357 .TP
358 .B nb
359 The number of bytes included in the optional text.
360 .TP
361 .B arg
362 The chorded argument, if present
363 (the 8 bit is set in the flag).
364 .TP
365 .B loc
366 The chorded location, if present
367 (the 8 bit is set in the flag).
368 .PD
369 .PP
370 .I Winreadevent
371 reads the next event (q.v.)
372 from the window's
373 .B event
374 file.
375 .PP
376 .I Winwriteevent
377 writes an event back to the window's 
378 .B event
379 file, indicating to
380 .I acme
381 that it should be handled internally.
382 .PP
383 .I Wineventchan
384 returns a pointer to a
385 .B Channel
386 (see
387 .MR thread (3) )
388 on which event structures (not pointers) can be read.
389 The first call to
390 .I wineventchan
391 allocates a channel and
392 starts a new thread that loops calling
393 .I winreadevent
394 and copying the events into the channel.
395 Subsequent calls return the same channel.
396 Clients should not call
397 .I winreadevent
398 after calling
399 .IR wineventchan .
400 .PP
401 .IR Emalloc ,
402 .IR erealloc ,
403 .IR estrdup ,
404 and
405 .I evsmprint
406 are like
407 .MR malloc (3) ,
408 .IR realloc ,
409 .IR strdup
410 (see
411 .MR strcat (3) ),
412 and
413 .IR vsmprint
414 (see
415 .MR print (3) ),
416 but they call
417 .MR sysfatal (3)
418 on error rather than returning nil.
419 .SH SOURCE
420 .B \*9/src/libacme
421 .SH SEE ALSO
422 .MR acme (1) ,
423 .MR acme (4)