GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  FILTER_WRITE (3)

NAME

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

CONTENTS

Library
Synopsis
Description
Return Values
See Also
History
Authors

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS


.In sys/types.h
.In stdio.h
.In pdel/io/filter.h int filter_read struct filter *f void *buf int len int filter_write struct filter *f const void *data int len int filter_end struct filter *f int filter_convert struct filter *f int num int forward void filter_destroy struct filter **fp FILE * filter_fopen struct filter *filter int flags FILE *fp const char *mode int filter_process struct filter *filter const void *input int len int final u_char **outputp const char *mtype

DESCRIPTION

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 functions 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 example, 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 internal 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 EPIPE.

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 output.

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 nothing.

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 below.

    Filter Functions

filter_fopen pushes a filter on top of a uni-directional stream, returning 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. Otherwise, the flags value may contain any of the following values OR’d together:

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-allocated 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.

RETURN VALUES

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

SEE ALSO

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

HISTORY

The PDEL library was developed at Packet Design, LLC. http://www.packetdesign.com/

AUTHORS


.An Archie Cobbs Aq archie@freebsd.org
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.