SYS-FILE2CHAN(2)                                 SYS-FILE2CHAN(2)

     NAME
          file2chan - create file connected to Limbo channel

     SYNOPSIS
          include "sys.m";
          sys := load Sys Sys->PATH;

          Rread:  type chan of (array of byte, string);
          Rwrite: type chan of (int, string);
          FileIO: adt
          {
              read:   chan of (int, int, int, Rread);
              write:  chan of (int, array of byte, int, Rwrite);
          };

          file2chan:  fn(dir, file: string): ref FileIO;

     DESCRIPTION
          File2chan presents an interface for binding Limbo channels
          to files in the file name space.  A server program calls
          file2chan to create a file in a directory dir, which must be
          a directory on which device `#s' has been bound (see
          srv(3)). A client program can open the file for reading or
          writing (see sys-open(2) and sys-read(2)) to communicate
          with the server.

          File2chan returns a FileIO type holding two channels used to
          deliver tuples representing the contents of the Tread and
          Twrite Styx messages received by the system on the server's
          behalf; see intro(5).

          When the client invokes the read system call on the file,
          the server receives a tuple, say (offset, count, fid, rc),
          on the read channel.  The request asks for count bytes of
          data, starting at offset bytes from the beginning of the
          file associated with fid. The server sends its reply to the
          client by transmitting a tuple, say (data, error), that con-
          tains the data for the read, on the channel rc received as
          part of the read tuple.  If the request was successful, the
          error string should be nil.  If an error occurred, error
          should be a string that describes the problem, and the data
          array should contain zero bytes.  The client blocks in the
          read system call until the server sends its reply.

          When the client does a write system call on the file, the
          server receives a tuple, (offset, data, fid, wc), on the
          write channel.  A (count, error) response is sent back on
          the wc channel received in the write tuple: count gives the
          number of bytes written (zero if an error occurs), and error
          is an empty or nil string or an explanation of the problem.

     Page 1                       Plan 9             (printed 3/29/24)

     SYS-FILE2CHAN(2)                                 SYS-FILE2CHAN(2)

          If the client closes the file for reading (writing), the
          server will receive a read (write) message with a nil rc
          (wc).  The server can use these signals to determine when to
          stop processing.  The fid received by the server can be used
          to manage the multiplexing of multiple active clients shar-
          ing a single file; see intro(5) for details.

     SOURCE
          /emu/devsrv.c
          /os/port/devsrv.c

     SEE ALSO
          sh-file2chan(1), sys-intro(2), sys-open(2), sys-read(2),
          sys-bind(2), intro(5)

     BUGS
          Read and write system calls for the file will not return
          until the server sends its reply on the appropriate channel,
          so the process doing the read or write cannot be the one
          serving.

     Page 2                       Plan 9             (printed 3/29/24)