ACME(3)                                                   ACME(3)

     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

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <thread.h>
          #include <9pclient.h>
          #include <acme.h>

          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[];
          };

          int       eventfmt(Fmt *fmt)

          Win*      newwin(void)

          Win*      openwin(int id, CFid *ctlfid)

          int       pipetowin(Win *w, char *file, int fderr, char *fmt, ...)

          int       pipewinto(Win *w, char *file, int fdout, char *fmt, ...)

          char*     sysrun(char *fmt, ...)

          int       winaddr(Win *w, char *fmt, ...)

          void      winclosefiles(Win *w)

          int       winctl(Win *w, char *fmt, ...)

          int       windel(Win *w, int sure)

     ACME(3)                                                   ACME(3)

          void      windeleteall(void)

          Channel*  wineventchan(Win *w)

          int       winfd(Win *w, char *name, int mode)

          void      winfree(Win *w)

          char*     winmread(Win *w, char *file)

          int       winname(Win *w, char *fmt, ...)

          int       winopenfd(Win *w, char *name, int mode)

          int       winprint(Win *w, char *file, char *fmt, ...)

          int       winread(Win *w, char *file, void *a, int n)

          int       winreadaddr(Win *w, uint *q1)

          int       winreadevent(Win *w, Event *e)

          int       winseek(Win *w, char *file, int off, int type)

          int       winwrite(Win *w, char *file, void *a, int n)

          int       winwriteevent(Win *w, Event *e)

          void*     emalloc(uint n)

          void*     erealloc(void *v, uint n)

          char*     estrdup(char *s)

          char*     evsmprint(char *fmt, va_list arg)

     DESCRIPTION
          Libacme provides a simple C interface for interacting with
          acme(1) windows.

          A Win structure represents a single window and its control
          files.  The contents of the structure should not be accessed
          directly.  Newwin creates a new window and returns a struc-
          ture corresponding to that window.  Openwin allocates a
          structure corresponding to the existing window with the
          given id. If ctlfid is non-nil, openwin assumes it is a file
          descriptor open for writing to the window's ctl file.  Own-
          ership of ctlfid passes to the library.

          Most of the library routines access files in the window's
          acme directory.  See acme(4) for details.  Many library rou-
          tines take a format string fmt followed by a variable list

     ACME(3)                                                   ACME(3)

          of arguments.  In the discussion below, the notation fmt,
          ... denotes the result of formatting the string and argu-
          ments using smprint (see print(3)).

          Pipetowin runs the rc(1) command line fmt, ... with
          /dev/null on standard input and the window's file on stan-
          dard output.  If fderr is non-zero (sic), it is used as
          standard error.  Otherwise the command inherits the caller's
          standard error.

          Pipewinto runs the rc(1) command line fmt, ... with the
          window's file on standard input.  The command runs with
          fdout as its standard output and standard error.

          Sysrun runs the rc command line fmt, ... and returns a
          pointer to the first kilobyte of output, NUL-terminated.
          The buffer holding the output is reused on each call.

          Winaddr writes fmt, ... to the window's addr file.

          Winclosefiles closes all the open file descriptors associ-
          ated with the window.  (These file descriptors are main-
          tained from the library and cached across calls to winctl,
          etc.)

          Winctl writes fmt, ... to the window's ctl file.

          Windel deletes the window, writing del (or, if sure is set,
          delete) to the window's ctl file.

          Winfd returns a file descriptor for the window's file opened
          for mode. The caller is responsible for closing the file
          descriptor.

          Winmread reads the contents of the window's file into a
          dynamically allocated buffer and returns it.  The caller is
          responsible for freeing the buffer.

          Winname sets the name of the window to fmt, ... by writing
          to the ctl file.

          Winprint prints fmt, ... to the window's file.

          Winread reads at most n bytes from the window's file into
          the buffer pointed at by a.

          Winreadaddr reads the window's addr file, which contains two
          integers.  It returns the first and stores the second in
          *q1.

          Winseek seeks the file descriptor for the window's file to
          position off relative to type (see seek(3)).

     ACME(3)                                                   ACME(3)

          Winwrite writes the n bytes pointed at by a to the window's
          file.

          An Event structure represents an event originating in a par-
          ticular window.  The fields correspond to the fields in
          acme's event messages.  See acme(4) for detailed explana-
          tions.  The fields are:

          c1, c2
               The two event characters, indicating origin and type of
               action.

          q0, q1
               The character addresses of the action.  If the original
               event had an empty selection (q0=q1) and was accompa-
               nied by an expansion (the 2 bit is set in the flag),
               then q0 and q1 will indicate the expansion rather than
               original event.

          oq0, oq1
               The q0 and q1 of the original event, even if it was
               expanded.  If there was no expansion, oq0=q0 and
               oq1=q1.

          flag The flag.

          nr   The number of characters (UTF sequences) included in
               the optional text.

          text The optional text itself, encoded in UTF.

          nb   The number of bytes included in the optional text.

          arg  The chorded argument, if present (the 8 bit is set in
               the flag).

          loc  The chorded location, if present (the 8 bit is set in
               the flag).

          Winreadevent reads the next event (q.v.)  from the window's
          event file.

          Winwriteevent writes an event back to the window's event
          file, indicating to acme that it should be handled inter-
          nally.

          Wineventchan returns a pointer to a Channel (see thread(3))
          on which event structures (not pointers) can be read.  The
          first call to wineventchan allocates a channel and starts a
          new thread that loops calling winreadevent and copying the
          events into the channel.  Subsequent calls return the same
          channel.  Clients should not call winreadevent after calling

     ACME(3)                                                   ACME(3)

          wineventchan.

          Emalloc, erealloc, estrdup, and evsmprint are like
          malloc(3), realloc, strdup (see strcat(3)), and vsmprint
          (see print(3)), but they call sysfatal(3) on error rather
          than returning nil.

     SOURCE
          /src/libacme

     SEE ALSO
          acme(1), acme(4)