SH-FILE2CHAN(1) SH-FILE2CHAN(1)
NAME
file2chan, rblock, rdata, rerror, rget, rread, rreadone,
rwrite - shell interface to file2chan
SYNOPSIS
load file2chan
file2chan filename readcmd writecmd [ closecmd ]
rblock [ tag ]
fetchwdata [ tag ]
putrdata [ tag ]
rerror [ tag ] errmsg
rread [ tag ] readdata
rreadone [ tag ] readdata
rwrite [ tag [ count ] ]
${rget (data|count|offset|fid) [ tag ] }
DESCRIPTION
File2chan is a loadable module for sh(1) that provides
facilities to create a file in the namespace with properties
determined by a shell script. File2chan creates filename in
the namespace and spawns a new thread to serve the file. If
the creation succeeds and the thread is spawned success-
fully, then the environment variable $apid is set to the
process id of the new thread; otherwise an error (non-nil)
status is returned. Readcmd, writecmd and closecmd should
be executable sh(1) command blocks. Subsequently, whenever
a process reads from filename, readcmd will be invoked;
whenever a process writes to filename, writecmd will be
invoked; whenever an open file on filename is closed, then
closecmd will be invoked, if present.
When a read or write request arrives, it is added to a list
of currently outstanding tags maintained by file2chan. If
the request is not replied to or acknowledged by the time
the invoked command has finished, then a reply will be made
automatically (the default is to accept all writes and to
give an error on all reads). Each tag is assigned a unique
tag id which is stored in the environment variable $tag for
the duration of the invoked command. Most commands take an
optional tag argument which should be the tag id of a cur-
rently outstanding request; if omitted, the value of $tag
will be used. The following commands are provided to reply
to requests and obtain information about requests:
rblock Rblock marks tag as a blocking request - no auto-
matic reply will be made when the currently
invoked command has terminated; the process making
the request will block until a reply is made.
Page 1 Plan 9 (printed 12/22/24)
SH-FILE2CHAN(1) SH-FILE2CHAN(1)
fetchwdata
Fetchwdata writes the data associated with tag
(which must be a write request) to its standard
output. It is useful if an uncorrupted version of
binary data is wanted, as it avoids the data being
interpreted as a utf-8 string.
putrdata Putrdata is the converse of fetchwdata: it reads
data from its standard input and replies to tag
(which must be a read request) with the data read.
Any data in excess of that requested will be lost.
rerror Rerror replies to tag with an error code; the
remote read or write request will return an error,
with the description errmsg.
rread Rread replies to the read request tag with the
data in readdata. If readdata is longer than the
number of bytes requested, then only the requested
number of bytes of readdata will be sent. The off-
set of the read request is ignored.
rreadone Rreadone is similar to rread except that it hon-
ours the offset of the client's read request, so
the client can use consecutive reads to retrieve
all of readdata.
rwrite Rwrite replies to the write request tag. If count
is given, then the client's write request will
return that number (it is usually considered an
error if the return from write (see sys-read(2))
is not the same as the number of bytes written).
If count is omitted, all the bytes are assumed to
have been written.
${rget} Rget retrieves information associated with tag.
The information it yields depends on its first
argument, which must be one of:
data The data associated with write request tag.
count
The number of bytes requested by read
request tag.
fid The client's file identifier associated with
tag. A unique fid is associated with all
client requests emanating from the same open
file. This is the only rget request valid
with the tag associated with a close opera-
tion.
Page 2 Plan 9 (printed 12/22/24)
SH-FILE2CHAN(1) SH-FILE2CHAN(1)
offset
The file offset associated with the request
tag.
EXAMPLES
The following code creates a very simple memory-based file
called /tmp/memfile.
file2chan /tmp/memfile {rreadone $data} {data = ${rget data}}
It is, however, very limited, as binary data stored in the
file will be corrupted, and the size of the file is limited
to the amount of data that can be transmitted in a single
Styx message (8192 bytes).
The following code implements a single-threaded logfile
which can support multiple concurrent writers:
{file2chan /chan/log {} {fetchwdata}} >> /tmp/logfile
The following code makes the command cmd available to exter-
nal programs, and defines a shell function to use it. Note
that there's an approximate 8K limit on the size of the
argument list that can be passed in this way.
load std
file2chan /chan/cmdchan {} {cmd ${unquote ${rget data}}}
fn runcmd {echo -n ${quote $*} > /chan/cmdchan}
SOURCE
/appl/cmd/sh/file2chan.b
SEE ALSO
sys-file2chan(2), sh(1), intro(5),
Page 3 Plan 9 (printed 12/22/24)