From 7e8275c89834c5cba2f9f5beedc95b4ff8b65a36 Mon Sep 17 00:00:00 2001 From: rsc Date: Sun, 25 Jun 2006 23:02:33 +0000 Subject: acme --- man/man3/acme.3 | 423 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 423 insertions(+) create mode 100644 man/man3/acme.3 (limited to 'man/man3') diff --git a/man/man3/acme.3 b/man/man3/acme.3 new file mode 100644 index 00000000..1683061a --- /dev/null +++ b/man/man3/acme.3 @@ -0,0 +1,423 @@ +.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 +.IR 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 +.IR 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 +.IR print (3)). +.PP +.I Pipetowin +runs the +.IR 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 +.IR 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 +.IR 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 +.IR 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 +.IR 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 +.IR malloc (3), +.IR realloc , +.IR strdup +(see +.IR strcat (3)), +and +.IR vsmprint +(see +.IR print (3)), +but they call +.IR sysfatal (3) +on error rather than returning nil. +.SH SOURCE +.B \*9/src/libacme +.SH SEE ALSO +.IR acme (1), +.IR acme (4) -- cgit v1.2.3