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 9P 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 diagnostic string, and the data array should be
nil. The client blocks in the read system call until the
server sends its reply. The client receives only count
bytes even if data is larger.
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
Page 1 Plan 9 (printed 4/16/24)
SYS-FILE2CHAN(2) SYS-FILE2CHAN(2)
is an empty or nil string or an explanation of the problem.
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. Each distinct open of the
file will yield a distinct fid, unique to that open, which
will appear in the read and write messages corresponding to
reads and writes on that open instance of the file.
When the client closes the file, the server will be sent a
read message with a nil rc, then a write message with a nil
wc. A server typically ignores the former and uses the lat-
ter as a signal to stop processing for the given client
(more precisely, the given fid). Note that the fid can later
be re-used by another client.
SOURCE
/emu/port/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 4/16/24)