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 contains 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. 

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 sharing 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. 

Plan 9  —  June 29, 2000