Blob
1 .TH ACME 32 .SH NAME3 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 library28 .SH SYNOPSIS29 .ft L30 .nf31 #include <u.h>32 #include <libc.h>33 #include <thread.h>34 #include <9pclient.h>35 #include <acme.h>36 .fi37 .PP38 .ft L39 .ta +\w'\fLxxxx'u +\w'\fLxxxxx'u40 .nf41 struct Event42 {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 .PP57 .ta +\w'\fLxxxxxxxxxx'u58 .B59 int eventfmt(Fmt *fmt)60 .PP61 .B62 Win* newwin(void)63 .PP64 .B65 Win* openwin(int id, CFid *ctlfid)66 .PP67 .B68 int pipetowin(Win *w, char *file, int fderr, char *fmt, ...)69 .PP70 .B71 int pipewinto(Win *w, char *file, int fdout, char *fmt, ...)72 .PP73 .B74 char* sysrun(char *fmt, ...)75 .PP76 .B77 int winaddr(Win *w, char *fmt, ...)78 .PP79 .B80 void winclosefiles(Win *w)81 .PP82 .B83 int winctl(Win *w, char *fmt, ...)84 .PP85 .B86 int windel(Win *w, int sure)87 .PP88 .B89 void windeleteall(void)90 .PP91 .B92 Channel* wineventchan(Win *w)93 .PP94 .B95 int winfd(Win *w, char *name, int mode)96 .PP97 .B98 void winfree(Win *w)99 .PP100 .B101 char* winmread(Win *w, char *file)102 .PP103 .B104 int winname(Win *w, char *fmt, ...)105 .PP106 .B107 int winopenfd(Win *w, char *name, int mode)108 .PP109 .B110 int winprint(Win *w, char *file, char *fmt, ...)111 .PP112 .B113 int winread(Win *w, char *file, void *a, int n)114 .PP115 .B116 int winreadaddr(Win *w, uint *q1)117 .PP118 .B119 int winreadevent(Win *w, Event *e)120 .PP121 .B122 int winseek(Win *w, char *file, int off, int type)123 .PP124 .B125 int winwrite(Win *w, char *file, void *a, int n)126 .PP127 .B128 int winwriteevent(Win *w, Event *e)129 .PP130 .B131 void* emalloc(uint n)132 .PP133 .B134 void* erealloc(void *v, uint n)135 .PP136 .B137 char* estrdup(char *s)138 .PP139 .B140 char* evsmprint(char *fmt, va_list arg)141 .SH DESCRIPTION142 .I Libacme143 provides a simple C interface for interacting with144 .IR acme (1)145 windows.146 .PP147 A148 .B Win149 structure represents a single window and its control files.150 The contents of the structure should not be accessed directly.151 .I Newwin152 creates a new window and returns a structure corresponding to that window.153 .I Openwin154 allocates a structure corresponding to the existing window with the given155 .IR id .156 If157 .I ctlfid158 is non-nil,159 .I openwin160 assumes it is a file descriptor open for writing to the window's161 .B ctl162 file.163 Ownership of164 .I ctlfid165 passes to the library.166 .PP167 Most of the library routines access files in the window's168 .I acme169 directory.170 See171 .IR acme (4)172 for details.173 Many library routines take a format string174 .I fmt175 followed by a variable list of arguments.176 In the discussion below, the notation177 .I fmt\fR, \fP...178 denotes the result of formatting the string and arguments179 using180 .I smprint181 (see182 .IR print (3)).183 .PP184 .I Pipetowin185 runs the186 .IR rc (1)187 command line188 .I fmt\fR, \fP...189 with190 .B /dev/null191 on standard input and the window's192 .I file193 on standard output.194 If195 .I fderr196 is non-zero (sic),197 it is used as standard error.198 Otherwise the command inherits the caller's standard error.199 .PP200 .I Pipewinto201 runs the202 .IR rc (1)203 command line204 .I fmt\fR, \fP...205 with the window's206 .I file207 on standard input.208 The command runs with209 .I fdout210 as its standard output and standard error.211 .PP212 .I Sysrun213 runs the214 .I rc215 command line216 .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 .PP220 .I Winaddr221 writes222 .I fmt\fR, \fP...223 to the window's224 .B addr225 file.226 .PP227 .I Winclosefiles228 closes all the open file descriptors associated with the window.229 (These file descriptors are maintained from the library and230 cached across calls to231 .IR winctl ,232 .IR etc .)233 .PP234 .I Winctl235 writes236 .I fmt\fR, \fP...237 to the window's238 .B ctl239 file.240 .PP241 .I Windel242 deletes the window,243 writing244 .B del245 (or, if246 .I sure247 is set,248 .B delete)249 to the window's250 .B ctl251 file.252 .PP253 .I Winfd254 returns a file descriptor for the window's255 .I file256 opened for257 .IR mode .258 The caller is responsible for closing the file descriptor.259 .PP260 .I Winmread261 reads the contents of the window's262 .I file263 into a dynamically allocated buffer264 and returns it.265 The caller is responsible for freeing the buffer.266 .PP267 .I Winname268 sets the name of the window to269 .I fmt\fR, \fP...270 by writing to the271 .B ctl272 file.273 .PP274 .I Winprint275 prints276 .I fmt\fR, \fP...277 to the window's278 .IR file .279 .PP280 .I Winread281 reads at most282 .I n283 bytes from the window's284 .IR file285 into the buffer pointed at by286 .IR a .287 .PP288 .I Winreadaddr289 reads the window's290 .B addr291 file, which contains two integers.292 It returns the first and stores the second in293 .BI * q1 \fR.294 .PP295 .I Winseek296 seeks the file descriptor for the window's297 .I file298 to position299 .I off300 relative to301 .I type302 (see303 .IR seek (3)).304 .PP305 .I Winwrite306 writes the307 .I n308 bytes pointed at by309 .I a310 to the window's311 .IR file .312 .PP313 An314 .B Event315 structure represents an event originating in a particular window.316 The fields correspond to the fields in317 .IR acme 's318 event messages.319 See320 .IR acme (4)321 for detailed explanations.322 The fields are:323 .TP324 .BR c1 ", " c2325 The two event characters, indicating origin and type of action.326 .TP327 .BR q0 ", " q1328 The character addresses of the action.329 If the original event had an empty selection330 .RB ( q0 = q1 )331 and was accompanied by an expansion332 (the 2 bit is set in the flag), then333 .B q0334 and335 .B q1336 will indicate the expansion rather than original event.337 .TP338 .BR oq0 ", " oq1339 The340 .B q0341 and342 .B q1343 of the original event, even if it was expanded.344 If there was no expansion,345 .BR oq0 = q0346 and347 .BR oq1 = q1 .348 .TP349 .B flag350 The flag.351 .TP352 .B nr353 The number of characters (UTF sequences) included in the optional text.354 .TP355 .B text356 The optional text itself, encoded in UTF.357 .TP358 .B nb359 The number of bytes included in the optional text.360 .TP361 .B arg362 The chorded argument, if present363 (the 8 bit is set in the flag).364 .TP365 .B loc366 The chorded location, if present367 (the 8 bit is set in the flag).368 .PD369 .PP370 .I Winreadevent371 reads the next event (q.v.)372 from the window's373 .B event374 file.375 .PP376 .I Winwriteevent377 writes an event back to the window's378 .B event379 file, indicating to380 .I acme381 that it should be handled internally.382 .PP383 .I Wineventchan384 returns a pointer to a385 .B Channel386 (see387 .IR thread (3))388 on which event structures (not pointers) can be read.389 The first call to390 .I wineventchan391 allocates a channel and392 starts a new thread that loops calling393 .I winreadevent394 and copying the events into the channel.395 Subsequent calls return the same channel.396 Clients should not call397 .I winreadevent398 after calling399 .IR wineventchan .400 .PP401 .IR Emalloc ,402 .IR erealloc ,403 .IR estrdup ,404 and405 .I evsmprint406 are like407 .IR malloc (3),408 .IR realloc ,409 .IR strdup410 (see411 .IR strcat (3)),412 and413 .IR vsmprint414 (see415 .IR print (3)),416 but they call417 .IR sysfatal (3)418 on error rather than returning nil.419 .SH SOURCE420 .B \*9/src/libacme421 .SH SEE ALSO422 .IR acme (1),423 .IR acme (4)