.TH ACME 3 .SH NAME Event, Win, eventfmt, newwin, pipetowin, pipewinto, sysrun, winaddr, winclosefiles, winctl, windel, windeleteall, windows, wineventchan, winfd, winfree, winmread, winname, winopenfd, winprint, winread, winreadaddr, winreadevent, winseek, winwrite, winwriteevent \- acme client library .SH SYNOPSIS .ft L .nf #include #include #include #include <9pclient.h> #include .fi .PP .ft L .ta +\w'\fLxxxx'u +\w'\fLxxxxx'u .nf struct Event { int c1; int c2; int q0; int q1; int oq0; int oq1; int flag; int nb; int nr; char text[]; char arg[]; char loc[]; }; .PP .ta +\w'\fLxxxxxxxxxx'u .B int eventfmt(Fmt *fmt) .PP .B Win* newwin(void) .PP .B Win* openwin(int id, CFid *ctlfid) .PP .B int pipetowin(Win *w, char *file, int fderr, char *fmt, ...) .PP .B int pipewinto(Win *w, char *file, int fdout, char *fmt, ...) .PP .B char* sysrun(char *fmt, ...) .PP .B int winaddr(Win *w, char *fmt, ...) .PP .B void winclosefiles(Win *w) .PP .B int winctl(Win *w, char *fmt, ...) .PP .B int windel(Win *w, int sure) .PP .B void windeleteall(void) .PP .B Channel* wineventchan(Win *w) .PP .B int winfd(Win *w, char *name, int mode) .PP .B void winfree(Win *w) .PP .B char* winmread(Win *w, char *file) .PP .B int winname(Win *w, char *fmt, ...) .PP .B int winopenfd(Win *w, char *name, int mode) .PP .B int winprint(Win *w, char *file, char *fmt, ...) .PP .B int winread(Win *w, char *file, void *a, int n) .PP .B int winreadaddr(Win *w, uint *q1) .PP .B int winreadevent(Win *w, Event *e) .PP .B int winseek(Win *w, char *file, int off, int type) .PP .B int winwrite(Win *w, char *file, void *a, int n) .PP .B int winwriteevent(Win *w, Event *e) .PP .B void* emalloc(uint n) .PP .B void* erealloc(void *v, uint n) .PP .B char* estrdup(char *s) .PP .B char* evsmprint(char *fmt, va_list arg) .SH DESCRIPTION .I Libacme provides a simple C interface for interacting with .MR acme (1) windows. .PP A .B Win structure represents a single window and its control files. The contents of the structure should not be accessed directly. .I Newwin creates a new window and returns a structure corresponding to that window. .I Openwin allocates a structure corresponding to the existing window with the given .IR id . If .I ctlfid is non-nil, .I openwin assumes it is a file descriptor open for writing to the window's .B ctl file. Ownership of .I ctlfid passes to the library. .PP Most of the library routines access files in the window's .I acme directory. See .MR acme (4) for details. Many library routines take a format string .I fmt followed by a variable list of arguments. In the discussion below, the notation .I fmt\fR, \fP... denotes the result of formatting the string and arguments using .I smprint (see .MR print (3) ). .PP .I Pipetowin runs the .MR rc (1) command line .I fmt\fR, \fP... with .B /dev/null on standard input and the window's .I file on standard output. If .I fderr is non-zero (sic), it is used as standard error. Otherwise the command inherits the caller's standard error. .PP .I Pipewinto runs the .MR rc (1) command line .I fmt\fR, \fP... with the window's .I file on standard input. The command runs with .I fdout as its standard output and standard error. .PP .I Sysrun runs the .I rc command line .I fmt\fR, \fP... and returns a pointer to the first kilobyte of output, NUL-terminated. The buffer holding the output is reused on each call. .PP .I Winaddr writes .I fmt\fR, \fP... to the window's .B addr file. .PP .I Winclosefiles closes all the open file descriptors associated with the window. (These file descriptors are maintained from the library and cached across calls to .IR winctl , .IR etc .) .PP .I Winctl writes .I fmt\fR, \fP... to the window's .B ctl file. .PP .I Windel deletes the window, writing .B del (or, if .I sure is set, .B delete) to the window's .B ctl file. .PP .I Winfd returns a file descriptor for the window's .I file opened for .IR mode . The caller is responsible for closing the file descriptor. .PP .I Winmread reads the contents of the window's .I file into a dynamically allocated buffer and returns it. The caller is responsible for freeing the buffer. .PP .I Winname sets the name of the window to .I fmt\fR, \fP... by writing to the .B ctl file. .PP .I Winprint prints .I fmt\fR, \fP... to the window's .IR file . .PP .I Winread reads at most .I n bytes from the window's .IR file into the buffer pointed at by .IR a . .PP .I Winreadaddr reads the window's .B addr file, which contains two integers. It returns the first and stores the second in .BI * q1 \fR. .PP .I Winseek seeks the file descriptor for the window's .I file to position .I off relative to .I type (see .MR seek (3) ). .PP .I Winwrite writes the .I n bytes pointed at by .I a to the window's .IR file . .PP An .B Event structure represents an event originating in a particular window. The fields correspond to the fields in .IR acme 's event messages. See .MR acme (4) for detailed explanations. The fields are: .TP .BR c1 ", " c2 The two event characters, indicating origin and type of action. .TP .BR q0 ", " q1 The character addresses of the action. If the original event had an empty selection .RB ( q0 = q1 ) and was accompanied by an expansion (the 2 bit is set in the flag), then .B q0 and .B q1 will indicate the expansion rather than original event. .TP .BR oq0 ", " oq1 The .B q0 and .B q1 of the original event, even if it was expanded. If there was no expansion, .BR oq0 = q0 and .BR oq1 = q1 . .TP .B flag The flag. .TP .B nr The number of characters (UTF sequences) included in the optional text. .TP .B text The optional text itself, encoded in UTF. .TP .B nb The number of bytes included in the optional text. .TP .B arg The chorded argument, if present (the 8 bit is set in the flag). .TP .B loc The chorded location, if present (the 8 bit is set in the flag). .PD .PP .I Winreadevent reads the next event (q.v.) from the window's .B event file. .PP .I Winwriteevent writes an event back to the window's .B event file, indicating to .I acme that it should be handled internally. .PP .I Wineventchan returns a pointer to a .B Channel (see .MR thread (3) ) on which event structures (not pointers) can be read. The first call to .I wineventchan allocates a channel and starts a new thread that loops calling .I winreadevent and copying the events into the channel. Subsequent calls return the same channel. Clients should not call .I winreadevent after calling .IR wineventchan . .PP .IR Emalloc , .IR erealloc , .IR estrdup , and .I evsmprint are like .MR malloc (3) , .IR realloc , .IR strdup (see .MR strcat (3) ), and .IR vsmprint (see .MR print (3) ), but they call .MR sysfatal (3) on error rather than returning nil. .SH SOURCE .B \*9/src/libacme .SH SEE ALSO .MR acme (1) , .MR acme (4)