acme.3 (6800B)
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)