1 7e8275c8 2006-06-25 devnull .TH ACME 3
3 7e8275c8 2006-06-25 devnull Event, Win,
6 7e8275c8 2006-06-25 devnull pipetowin,
7 7e8275c8 2006-06-25 devnull pipewinto,
10 7e8275c8 2006-06-25 devnull winclosefiles,
13 7e8275c8 2006-06-25 devnull windeleteall,
15 7e8275c8 2006-06-25 devnull wineventchan,
18 7e8275c8 2006-06-25 devnull winmread,
20 7e8275c8 2006-06-25 devnull winopenfd,
21 7e8275c8 2006-06-25 devnull winprint,
23 7e8275c8 2006-06-25 devnull winreadaddr,
24 7e8275c8 2006-06-25 devnull winreadevent,
26 7e8275c8 2006-06-25 devnull winwrite,
27 7e8275c8 2006-06-25 devnull winwriteevent \- acme client library
28 7e8275c8 2006-06-25 devnull .SH SYNOPSIS
31 7e8275c8 2006-06-25 devnull #include <u.h>
32 7e8275c8 2006-06-25 devnull #include <libc.h>
33 7e8275c8 2006-06-25 devnull #include <thread.h>
34 7e8275c8 2006-06-25 devnull #include <9pclient.h>
35 7e8275c8 2006-06-25 devnull #include <acme.h>
39 7e8275c8 2006-06-25 devnull .ta +\w'\fLxxxx'u +\w'\fLxxxxx'u
41 7e8275c8 2006-06-25 devnull struct Event
49 7e8275c8 2006-06-25 devnull int flag;
52 7e8275c8 2006-06-25 devnull char text[];
53 7e8275c8 2006-06-25 devnull char arg[];
54 7e8275c8 2006-06-25 devnull char loc[];
57 7e8275c8 2006-06-25 devnull .ta +\w'\fLxxxxxxxxxx'u
59 7e8275c8 2006-06-25 devnull int eventfmt(Fmt *fmt)
62 7e8275c8 2006-06-25 devnull Win* newwin(void)
65 7e8275c8 2006-06-25 devnull Win* openwin(int id, CFid *ctlfid)
68 7e8275c8 2006-06-25 devnull int pipetowin(Win *w, char *file, int fderr, char *fmt, ...)
71 7e8275c8 2006-06-25 devnull int pipewinto(Win *w, char *file, int fdout, char *fmt, ...)
74 7e8275c8 2006-06-25 devnull char* sysrun(char *fmt, ...)
77 7e8275c8 2006-06-25 devnull int winaddr(Win *w, char *fmt, ...)
80 7e8275c8 2006-06-25 devnull void winclosefiles(Win *w)
83 7e8275c8 2006-06-25 devnull int winctl(Win *w, char *fmt, ...)
86 7e8275c8 2006-06-25 devnull int windel(Win *w, int sure)
89 7e8275c8 2006-06-25 devnull void windeleteall(void)
92 7e8275c8 2006-06-25 devnull Channel* wineventchan(Win *w)
95 7e8275c8 2006-06-25 devnull int winfd(Win *w, char *name, int mode)
98 7e8275c8 2006-06-25 devnull void winfree(Win *w)
101 7e8275c8 2006-06-25 devnull char* winmread(Win *w, char *file)
104 7e8275c8 2006-06-25 devnull int winname(Win *w, char *fmt, ...)
107 7e8275c8 2006-06-25 devnull int winopenfd(Win *w, char *name, int mode)
110 7e8275c8 2006-06-25 devnull int winprint(Win *w, char *file, char *fmt, ...)
113 7e8275c8 2006-06-25 devnull int winread(Win *w, char *file, void *a, int n)
116 7e8275c8 2006-06-25 devnull int winreadaddr(Win *w, uint *q1)
119 7e8275c8 2006-06-25 devnull int winreadevent(Win *w, Event *e)
122 7e8275c8 2006-06-25 devnull int winseek(Win *w, char *file, int off, int type)
125 7e8275c8 2006-06-25 devnull int winwrite(Win *w, char *file, void *a, int n)
128 7e8275c8 2006-06-25 devnull int winwriteevent(Win *w, Event *e)
131 7e8275c8 2006-06-25 devnull void* emalloc(uint n)
134 7e8275c8 2006-06-25 devnull void* erealloc(void *v, uint n)
137 7e8275c8 2006-06-25 devnull char* estrdup(char *s)
140 7e8275c8 2006-06-25 devnull char* evsmprint(char *fmt, va_list arg)
141 7e8275c8 2006-06-25 devnull .SH DESCRIPTION
142 7e8275c8 2006-06-25 devnull .I Libacme
143 7e8275c8 2006-06-25 devnull provides a simple C interface for interacting with
144 7e8275c8 2006-06-25 devnull .IR acme (1)
145 7e8275c8 2006-06-25 devnull windows.
149 7e8275c8 2006-06-25 devnull structure represents a single window and its control files.
150 7e8275c8 2006-06-25 devnull The contents of the structure should not be accessed directly.
151 7e8275c8 2006-06-25 devnull .I Newwin
152 7e8275c8 2006-06-25 devnull creates a new window and returns a structure corresponding to that window.
153 7e8275c8 2006-06-25 devnull .I Openwin
154 7e8275c8 2006-06-25 devnull allocates a structure corresponding to the existing window with the given
155 7e8275c8 2006-06-25 devnull .IR id .
157 7e8275c8 2006-06-25 devnull .I ctlfid
158 7e8275c8 2006-06-25 devnull is non-nil,
159 7e8275c8 2006-06-25 devnull .I openwin
160 7e8275c8 2006-06-25 devnull assumes it is a file descriptor open for writing to the window's
163 7e8275c8 2006-06-25 devnull Ownership of
164 7e8275c8 2006-06-25 devnull .I ctlfid
165 7e8275c8 2006-06-25 devnull passes to the library.
167 7e8275c8 2006-06-25 devnull Most of the library routines access files in the window's
169 7e8275c8 2006-06-25 devnull directory.
171 7e8275c8 2006-06-25 devnull .IR acme (4)
172 7e8275c8 2006-06-25 devnull for details.
173 7e8275c8 2006-06-25 devnull Many library routines take a format string
175 7e8275c8 2006-06-25 devnull followed by a variable list of arguments.
176 7e8275c8 2006-06-25 devnull In the discussion below, the notation
177 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
178 7e8275c8 2006-06-25 devnull denotes the result of formatting the string and arguments
180 7e8275c8 2006-06-25 devnull .I smprint
182 7e8275c8 2006-06-25 devnull .IR print (3)).
184 7e8275c8 2006-06-25 devnull .I Pipetowin
185 7e8275c8 2006-06-25 devnull runs the
186 7e8275c8 2006-06-25 devnull .IR rc (1)
187 7e8275c8 2006-06-25 devnull command line
188 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
190 7e8275c8 2006-06-25 devnull .B /dev/null
191 7e8275c8 2006-06-25 devnull on standard input and the window's
193 7e8275c8 2006-06-25 devnull on standard output.
195 7e8275c8 2006-06-25 devnull .I fderr
196 7e8275c8 2006-06-25 devnull is non-zero (sic),
197 7e8275c8 2006-06-25 devnull it is used as standard error.
198 7e8275c8 2006-06-25 devnull Otherwise the command inherits the caller's standard error.
200 7e8275c8 2006-06-25 devnull .I Pipewinto
201 7e8275c8 2006-06-25 devnull runs the
202 7e8275c8 2006-06-25 devnull .IR rc (1)
203 7e8275c8 2006-06-25 devnull command line
204 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
205 7e8275c8 2006-06-25 devnull with the window's
207 7e8275c8 2006-06-25 devnull on standard input.
208 7e8275c8 2006-06-25 devnull The command runs with
209 7e8275c8 2006-06-25 devnull .I fdout
210 7e8275c8 2006-06-25 devnull as its standard output and standard error.
212 7e8275c8 2006-06-25 devnull .I Sysrun
213 7e8275c8 2006-06-25 devnull runs the
215 7e8275c8 2006-06-25 devnull command line
216 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
217 7e8275c8 2006-06-25 devnull and returns a pointer to the first kilobyte of output, NUL-terminated.
218 7e8275c8 2006-06-25 devnull The buffer holding the output is reused on each call.
220 7e8275c8 2006-06-25 devnull .I Winaddr
222 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
223 7e8275c8 2006-06-25 devnull to the window's
227 7e8275c8 2006-06-25 devnull .I Winclosefiles
228 7e8275c8 2006-06-25 devnull closes all the open file descriptors associated with the window.
229 7e8275c8 2006-06-25 devnull (These file descriptors are maintained from the library and
230 7e8275c8 2006-06-25 devnull cached across calls to
231 7e8275c8 2006-06-25 devnull .IR winctl ,
232 7e8275c8 2006-06-25 devnull .IR etc .)
234 7e8275c8 2006-06-25 devnull .I Winctl
236 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
237 7e8275c8 2006-06-25 devnull to the window's
241 7e8275c8 2006-06-25 devnull .I Windel
242 7e8275c8 2006-06-25 devnull deletes the window,
248 7e8275c8 2006-06-25 devnull .B delete)
249 7e8275c8 2006-06-25 devnull to the window's
253 7e8275c8 2006-06-25 devnull .I Winfd
254 7e8275c8 2006-06-25 devnull returns a file descriptor for the window's
256 7e8275c8 2006-06-25 devnull opened for
257 7e8275c8 2006-06-25 devnull .IR mode .
258 7e8275c8 2006-06-25 devnull The caller is responsible for closing the file descriptor.
260 7e8275c8 2006-06-25 devnull .I Winmread
261 7e8275c8 2006-06-25 devnull reads the contents of the window's
263 7e8275c8 2006-06-25 devnull into a dynamically allocated buffer
264 7e8275c8 2006-06-25 devnull and returns it.
265 7e8275c8 2006-06-25 devnull The caller is responsible for freeing the buffer.
267 7e8275c8 2006-06-25 devnull .I Winname
268 7e8275c8 2006-06-25 devnull sets the name of the window to
269 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
270 7e8275c8 2006-06-25 devnull by writing to the
274 7e8275c8 2006-06-25 devnull .I Winprint
276 7e8275c8 2006-06-25 devnull .I fmt\fR, \fP...
277 7e8275c8 2006-06-25 devnull to the window's
278 7e8275c8 2006-06-25 devnull .IR file .
280 7e8275c8 2006-06-25 devnull .I Winread
281 7e8275c8 2006-06-25 devnull reads at most
283 7e8275c8 2006-06-25 devnull bytes from the window's
284 7e8275c8 2006-06-25 devnull .IR file
285 7e8275c8 2006-06-25 devnull into the buffer pointed at by
288 7e8275c8 2006-06-25 devnull .I Winreadaddr
289 7e8275c8 2006-06-25 devnull reads the window's
291 7e8275c8 2006-06-25 devnull file, which contains two integers.
292 7e8275c8 2006-06-25 devnull It returns the first and stores the second in
293 7e8275c8 2006-06-25 devnull .BI * q1 \fR.
295 7e8275c8 2006-06-25 devnull .I Winseek
296 7e8275c8 2006-06-25 devnull seeks the file descriptor for the window's
298 7e8275c8 2006-06-25 devnull to position
300 7e8275c8 2006-06-25 devnull relative to
303 7e8275c8 2006-06-25 devnull .IR seek (3)).
305 7e8275c8 2006-06-25 devnull .I Winwrite
306 7e8275c8 2006-06-25 devnull writes the
308 7e8275c8 2006-06-25 devnull bytes pointed at by
310 7e8275c8 2006-06-25 devnull to the window's
311 7e8275c8 2006-06-25 devnull .IR file .
314 7e8275c8 2006-06-25 devnull .B Event
315 7e8275c8 2006-06-25 devnull structure represents an event originating in a particular window.
316 7e8275c8 2006-06-25 devnull The fields correspond to the fields in
317 7e8275c8 2006-06-25 devnull .IR acme 's
318 7e8275c8 2006-06-25 devnull event messages.
320 7e8275c8 2006-06-25 devnull .IR acme (4)
321 7e8275c8 2006-06-25 devnull for detailed explanations.
322 7e8275c8 2006-06-25 devnull The fields are:
324 7e8275c8 2006-06-25 devnull .BR c1 ", " c2
325 7e8275c8 2006-06-25 devnull The two event characters, indicating origin and type of action.
327 7e8275c8 2006-06-25 devnull .BR q0 ", " q1
328 7e8275c8 2006-06-25 devnull The character addresses of the action.
329 7e8275c8 2006-06-25 devnull If the original event had an empty selection
330 7e8275c8 2006-06-25 devnull .RB ( q0 = q1 )
331 7e8275c8 2006-06-25 devnull and was accompanied by an expansion
332 7e8275c8 2006-06-25 devnull (the 2 bit is set in the flag), then
336 7e8275c8 2006-06-25 devnull will indicate the expansion rather than original event.
338 7e8275c8 2006-06-25 devnull .BR oq0 ", " oq1
343 7e8275c8 2006-06-25 devnull of the original event, even if it was expanded.
344 7e8275c8 2006-06-25 devnull If there was no expansion,
345 7e8275c8 2006-06-25 devnull .BR oq0 = q0
347 7e8275c8 2006-06-25 devnull .BR oq1 = q1 .
350 7e8275c8 2006-06-25 devnull The flag.
353 7e8275c8 2006-06-25 devnull The number of characters (UTF sequences) included in the optional text.
356 7e8275c8 2006-06-25 devnull The optional text itself, encoded in UTF.
359 7e8275c8 2006-06-25 devnull The number of bytes included in the optional text.
362 7e8275c8 2006-06-25 devnull The chorded argument, if present
363 7e8275c8 2006-06-25 devnull (the 8 bit is set in the flag).
366 7e8275c8 2006-06-25 devnull The chorded location, if present
367 7e8275c8 2006-06-25 devnull (the 8 bit is set in the flag).
370 7e8275c8 2006-06-25 devnull .I Winreadevent
371 7e8275c8 2006-06-25 devnull reads the next event (q.v.)
372 7e8275c8 2006-06-25 devnull from the window's
373 7e8275c8 2006-06-25 devnull .B event
376 7e8275c8 2006-06-25 devnull .I Winwriteevent
377 7e8275c8 2006-06-25 devnull writes an event back to the window's
378 7e8275c8 2006-06-25 devnull .B event
379 7e8275c8 2006-06-25 devnull file, indicating to
381 7e8275c8 2006-06-25 devnull that it should be handled internally.
383 7e8275c8 2006-06-25 devnull .I Wineventchan
384 7e8275c8 2006-06-25 devnull returns a pointer to a
385 7e8275c8 2006-06-25 devnull .B Channel
387 7e8275c8 2006-06-25 devnull .IR thread (3))
388 7e8275c8 2006-06-25 devnull on which event structures (not pointers) can be read.
389 7e8275c8 2006-06-25 devnull The first call to
390 7e8275c8 2006-06-25 devnull .I wineventchan
391 7e8275c8 2006-06-25 devnull allocates a channel and
392 7e8275c8 2006-06-25 devnull starts a new thread that loops calling
393 7e8275c8 2006-06-25 devnull .I winreadevent
394 7e8275c8 2006-06-25 devnull and copying the events into the channel.
395 7e8275c8 2006-06-25 devnull Subsequent calls return the same channel.
396 7e8275c8 2006-06-25 devnull Clients should not call
397 7e8275c8 2006-06-25 devnull .I winreadevent
398 7e8275c8 2006-06-25 devnull after calling
399 7e8275c8 2006-06-25 devnull .IR wineventchan .
401 7e8275c8 2006-06-25 devnull .IR Emalloc ,
402 7e8275c8 2006-06-25 devnull .IR erealloc ,
403 7e8275c8 2006-06-25 devnull .IR estrdup ,
405 7e8275c8 2006-06-25 devnull .I evsmprint
406 7e8275c8 2006-06-25 devnull are like
407 7e8275c8 2006-06-25 devnull .IR malloc (3),
408 7e8275c8 2006-06-25 devnull .IR realloc ,
409 7e8275c8 2006-06-25 devnull .IR strdup
411 7e8275c8 2006-06-25 devnull .IR strcat (3)),
413 7e8275c8 2006-06-25 devnull .IR vsmprint
415 7e8275c8 2006-06-25 devnull .IR print (3)),
416 7e8275c8 2006-06-25 devnull but they call
417 7e8275c8 2006-06-25 devnull .IR sysfatal (3)
418 7e8275c8 2006-06-25 devnull on error rather than returning nil.
419 7e8275c8 2006-06-25 devnull .SH SOURCE
420 7e8275c8 2006-06-25 devnull .B \*9/src/libacme
421 7e8275c8 2006-06-25 devnull .SH SEE ALSO
422 7e8275c8 2006-06-25 devnull .IR acme (1),
423 7e8275c8 2006-06-25 devnull .IR acme (4)