Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FILTER(3)		 BSD Library Functions Manual		     FILTER(3)

     filter_read, filter_write,	filter_end, filter_convert, filter_destroy,
     filter_fopen, filter_process -- generic data filtering

     PDEL Library (libpdel, -lpdel)

     #include <sys/types.h>
     #include <stdio.h>
     #include <pdel/io/filter.h>

     filter_read(struct	filter *f, void	*buf, int len);

     filter_write(struct filter	*f, const void *data, int len);

     filter_end(struct filter *f);

     filter_convert(struct filter *f, int num, int forward);

     filter_destroy(struct filter **fp);

     FILE *
     filter_fopen(struct filter	*filter, int flags, FILE *fp,
	 const char *mode);

     filter_process(struct filter *filter, const void *input, int len,
	 int final, u_char **outputp, const char *mtype);

     These functions operate on	filters, which are objects that	have an	input
     side and an output	side and perform some kind of encoding or operation on
     data as it	passes through.

   Filter Objects
     A filter object looks like	this:

	struct filter {
	    filter_read_t	*read;		/* read	data out of filter */
	    filter_write_t	*write;		/* write data into filter */
	    filter_end_t	*end;		/* signal end of data */
	    filter_convert_t	*convert;	/* map # bytes in <-> out */
	    filter_destroy_t	*destroy;	/* destroy filter */
	    void		*private;	/* object private data */

     The read, write, end, convert, and	destroy	fields are pointers to func-
     tions having the following	types:

	typedef	int   filter_read_t(struct filter *f, void *buf, int len);
	typedef	int   filter_write_t(struct filter *f,
			  const	void *data, int	len);
	typedef	int   filter_end_t(struct filter *f);
	typedef	int   filter_convert_t(struct filter *f,
			  int num, int forward);
	typedef	void  filter_destroy_t(struct filter **fp);

     Note: these functions must	be implemented to be thread-safe.  For exam-
     ple, two threads should be	able to	write to and read from the same	filter
     object simultaneously.

     The read()	method should read data	from the filter	and return the number
     of	bytes read (up to len bytes), or 0 if more data	needs to be written to
     the filter	(i.e., the filter's internal buffer is empty).	If an error is
     encountered, it should return -1 with errno set appropriately.

     The write() method	inputs data into the filter, returning the number of
     bytes input (up to	len bytes).  It	should return 0	if the filter's	inter-
     nal buffer	is full, or -1 and set errno on	error.

     The end() method indicates	to the filter that no more data	will be	input.
     It	should return 0	on success or -1 and set errno on error.  After	this
     method is called, any calls to write() should return -1 with errno	set to

     The convert() method provides estimates of	the ratio of input length to
     output length, and	vice-versa.  If	forward	is non-zero, convert() should
     return an upper bound on the number of bytes of that num bytes of input
     will generate.  Otherwise,	it should return an upper bound	on the number
     of	bytes of input that are	required to generate num (or more) bytes of

     The destroy() method should free all resources associated with the	filter
     and set *fp to NULL. If *fp is already equal to NULL, destroy() should do

     The filter_read(),	filter_write(),	filter_end(), filter_convert() and
     filter_destroy() functions	are convenience	wrappers for the corresponding
     object methods.

     By	implementing these methods and providing a constructor function	to
     create new	instances, user-defined	filters	may be used with the functions

   Filter Functions
     filter_fopen() pushes a filter on top of a	uni-directional	stream,	re-
     turning a new stream.  Data read from or written to the newly created
     stream will pass through the filter.  The mode argument is	as described
     for fopen(3), but is restricted to	being either "r" or "w".

     If	flags is zero, calling fclose(3) on the	newly created stream causes
     the underlying stream fp to be closed and filter to be destroyed.	Other-
     wise, the flags value may contain any of the following values OR'd	to-

	FILTER_NO_CLOSE_STREAM	  fclose() does	not close underlying stream
	FILTER_NO_DESTROY_FILTER  fclose() does	not destroy the	filter

     filter_process() sends len	bytes of data pointed to by input through the
     filter.  Upon successful return, the results are placed into a newly-al-
     located buffer having typed_mem(3)	type mtype and pointed to by *outputp;
     the caller	must eventually	free this buffer.  If final is non-zero, then
     the filter's end()	method is called after the last	input byte is written.

     All functions that	have a return value use	-1 or NULL to indicate an er-
     ror, with errno set appropriately.

     base64(3),	fopen(3), libpdel(3), string_fp(3), typed_mem(3)

     The PDEL library was developed at Packet Design, LLC.

     Archie Cobbs <>

BSD				April 22, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help