FILTER(2) FILTER(2)
NAME
filter - data processing interface
SYNOPSIS
include "filter.m";
filter = load Filter FilterModulePath;
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. For details of the filter modules that exist, see
filters(2).
Init must be called when a filter module has been loaded, to
initialise any internal data structures. 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 message sent is
always Rq.Start; pid is the process id of the new process
spawned. Other messages are:
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
Page 1 Plan 9 (printed 4/26/24)
FILTER(2) FILTER(2)
the data must be acknowledged by sending a value
on reply. If the value is -1, the filter will ter-
minate.
Rq.Finished
The filter has finished processing. Buf contains
the data that remains unconsumed by the filter, if
any. The filter terminates after sending this mes-
sage.
Rq.Info This message is used to communicate a string of
arbitrary information from the filter during the
course of its processing.
Rq.Error The filter has encountered an error when process-
ing. E is a string describing the error. The fil-
ter terminates after sending this message.
SOURCE
/module/filter.m
SEE ALSO
filters(2), gzip(1)
Page 2 Plan 9 (printed 4/26/24)