rblock [ tag ]
fetchwdata [ tag ]
putrdata [ tag ]
rerror [ tag ] errmsg
rread [ tag ] readdata
rreadone [ tag ] readdata
rwrite [ tag [ count ] ]
${rget ( data|count|offset|fid ) [ tag ] }
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 currently 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:
10 rblock Rblock marks tag as a blocking request - no automatic reply will be made when the currently invoked command has terminated; the process making the request will block until a reply is made.
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 offset of the read request is ignored.
rreadone Rreadone is similar to rread except that it honours 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 operation.
offset The file offset associated with the request tag .
The following code implements a single-threaded logfile which can support multiple concurrent writers: .EX {file2chan /chan/log {} {fetchwdata}} >> /tmp/logfile
The following code makes the command cmd available to external 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. .EX load std file2chan /chan/cmdchan {} {cmd ${unquote ${rget data}}} fn runcmd {echo -n ${quote $*} > /chan/cmdchan}