FILTER(2) FILTER(2)
NAME
filter - data processing interface
SYNOPSIS
include "filter.m";
filter := load Filter filterpath;
Rq: adt {
pick {
Start =>
pid: int;
Fill or Result =>
buf: array of byte;
reply: chan of int;
Finished =>
buf: array of byte;
Info =>
msg: string;
Error =>
e: string;
}
};
init: fn();
start: fn(param: string): chan of ref Rq;
DESCRIPTION
Filter defines a general module interface for byte-stream
processing. This manual page documents how to use the
interface, and by implication how a Filter module should
behave. There is a different implementation module for each
filter type and algorithm (eg, for compression or line
encoding). All implementations are instances of type
Filter, loaded from the Dis file filterpath, given in the
manual page for each standard filter (or you can write your
own to match this specification). For details of each
existing filter module, see filter-deflate(2) and following
manual pages.
Init must be called before any other operation of a filter
module.
Start sets the filter going; param can be used to pass any
filter-specific information to the processor. Start spawns
a new thread to do the processing; it returns a channel that
is used to receive requests from the filter. The first mes-
sage sent is always Rq.Start; pid is the process id of the
new process spawned.
Subsequent messages are:
Page 1 Plan 9 (printed 4/20/24)
FILTER(2) FILTER(2)
Rq.Fill A request by the filter to fill buf with data.
The number of bytes that have actually been
placed in the buffer should be sent on reply.
If -1 is sent, the filter will terminate. If
the value is 0, the filter will terminate once
it has processed all its input.
Rq.Result Buf contains data from the filter. Receipt of
the the data must be acknowledged by sending a
value on reply. If the value is -1, the filter
will terminate.
Rq.Finished The filter has finished processing. Buf con-
tains any data that was not consumed by the
filter. The filter terminates after sending
this message.
Rq.Info This message is used to send a string of arbi-
trary information from the filter during the
course of its processing.
Rq.Error The filter has encountered an error when pro-
cessing. E is a string describing the error.
The filter terminates after sending this mes-
sage.
SOURCE
/module/filter.m
SEE ALSO
gzip(1), filter-deflate(2), filter-slip(2)
Page 2 Plan 9 (printed 4/20/24)