.TH SYS-FILE2CHAN 2.SH NAMEfile2chan \- create file connected to Limbo channel.SH SYNOPSIS.EXinclude "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;.EE.fi.SH DESCRIPTION.B File2chanpresents an interface for binding Limbo channels to files in the file name space.A.I serverprogram calls.B file2chanto create a.I filein a directory.IR dir ,which must be a directory on which device.RB ` #s 'has been bound(see.IR srv (3)).A.I clientprogram can open the file for reading or writing (see.IR sys-open (2)and.IR sys-read (2))to communicate with the server..PP.B File2chanreturns a.B FileIOtype holding two channels used to deliver tuples representingthe contents of the.B Treadand.B Twrite9P messages received by the system on the server's behalf; see.IR intro (5)..PPWhen the client invokes the.B readsystem call on the file, the serverreceives a tuple, say.BI ( offset\fP,\fP\ count\fP,\fP\ fid\fP,\fP\ rc )\f1,on the.B readchannel.The request asks for.I countbytes of data, starting at.I offsetbytes from the beginning of the fileassociated with.IR fid .The server sends its reply to the client by transmitting a tuple, say.BI ( data\fP,\fP\ error )\f1,that contains the.I datafor the.BR read ,on the channel.I rcreceived as part of the.B readtuple.If the request was successful, the.I errorstring should be.BR nil .If an error occurred,.I errorshould be a diagnostic string,and the.I dataarray should be.BR nil .The client blocks in the.B readsystem call until the server sends its reply.The client receives only.I countbytes even if.I datais larger..PPWhen the client does a.B writesystem call on the file,the server receives a tuple,.BI ( offset\fP,\fP\ data\fP,\fP\ fid\fP,\fP\ wc )\f1,on the.B writechannel.A.BI ( count\fP,\fP\ error )response is sent back on the.I wcchannel received in the.B writetuple:.I countgives the number of bytes written (zero if an error occurs), and.I erroris an empty or.B nilstring or an explanation of the problem..PPThe.I fidreceived by the server can be used to manage the multiplexing of multipleactive clients sharing a single file; see.IR intro (5)for details.Each distinctopen of the file will yield a distinct.IR fid ,unique to that open, which will appear in the read and writemessages corresponding to reads and writes on that open instance of the file..PPWhen the client closes the file,the server will be sent a.B readmessage with a nil.IR rc ,then a.B writemessage with a nil.IR wc .A server typically ignores the former and uses the latter as a signal to stop processing for the given client(more precisely, the given.IR fid ).Note that the.I fidcan later be re-used by another client..SH SOURCE.B /emu/port/devsrv.c.br.B /os/port/devsrv.c.SH SEE ALSO.IR sh-file2chan (1),.IR sys-intro (2),.IR sys-open (2),.IR sys-read (2),.IR sys-bind (2),.IR intro (5).SH BUGS.B Readand.B writesystem calls for the file will not return until theserver sends its reply on the appropriate channel,so the process doing the.B reador.B writecannot be the one serving.
.TH SYS-FILE2CHAN 2
.SH NAME
file2chan \- create file connected to Limbo channel
.SH SYNOPSIS
.EX
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;
.EE
.fi
.SH DESCRIPTION
.B File2chan
presents an interface for binding Limbo channels to files in the file name space.
A
.I server
program calls
.B file2chan
to create a
.I file
in a directory
.IR dir ,
which must be a directory on which device
.RB ` #s '
has been bound
(see
.IR srv (3)).
A
.I client
program can open the file for reading or writing (see
.IR sys-open (2)
and
.IR sys-read (2))
to communicate with the server.
.PP
.B File2chan
returns a
.B FileIO
type holding two channels used to deliver tuples representing
the contents of the
.B Tread
and
.B Twrite
9P messages received by the system on the server's behalf; see
.IR intro (5).
.PP
When the client invokes the
.B read
system call on the file, the server
receives a tuple, say
.BI ( offset\fP,\fP\ count\fP,\fP\ fid\fP,\fP\ rc )\f1,
on the
.B read
channel.
The request asks for
.I count
bytes of data, starting at
.I offset
bytes from the beginning of the file
associated with
.IR fid .
The server sends its reply to the client by transmitting a tuple, say
.BI ( data\fP,\fP\ error )\f1,
that contains the
.I data
for the
.BR read ,
on the channel
.I rc
received as part of the
.B read
tuple.
If the request was successful, the
.I error
string should be
.BR nil .
If an error occurred,
.I error
should be a diagnostic string,
and the
.I data
array should be
.BR nil .
The client blocks in the
.B read
system call until the server sends its reply.
The client receives only
.I count
bytes even if
.I data
is larger.
.PP
When the client does a
.B write
system call on the file,
the server receives a tuple,
.BI ( offset\fP,\fP\ data\fP,\fP\ fid\fP,\fP\ wc )\f1,
on the
.B write
channel.
A
.BI ( count\fP,\fP\ error )
response is sent back on the
.I wc
channel received in the
.B write
tuple:
.I count
gives the number of bytes written (zero if an error occurs), and
.I error
is an empty or
.B nil
string or an explanation of the problem.
.PP
The
.I fid
received by the server can be used to manage the multiplexing of multiple
active clients sharing a single file; see
.IR intro (5)
for details.
Each distinct
open of the file will yield a distinct
.IR 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.
.PP
When the client closes the file,
the server will be sent a
.B read
message with a nil
.IR rc ,
then a
.B write
message with a nil
.IR wc .
A server typically ignores the former and uses the latter as a signal to stop processing for the given client
(more precisely, the given
.IR fid ).
Note that the
.I fid
can later be re-used by another client.
.SH SOURCE
.B /emu/port/devsrv.c
.br
.B /os/port/devsrv.c
.SH SEE ALSO
.IR sh-file2chan (1),
.IR sys-intro (2),
.IR sys-open (2),
.IR sys-read (2),
.IR sys-bind (2),
.IR intro (5)
.SH BUGS
.B Read
and
.B write
system calls for the file will not return until the
server sends its reply on the appropriate channel,
so the process doing the
.B read
or
.B write
cannot be the one serving.