1. Manuals
  2. Tumbleweed
  3. ksh-devel
  4. sfdisc(3ast)

Scroll to navigation

SFDISC(3) Library Functions Manual SFDISC(3)

NAME

sfdisc - sfio disciplines

SYNOPSIS

#include	<sfdisc.h>
extern Sfdisc_t*	dcnewskable(Sfio_t* f);
extern int		dcdelskable(Sfdisc_t* disc);
extern Sfdisc_t*	dcnewtee(Sfio_t* tee);
extern int		dcdeltee(Sfdisc_t* disc);
extern Sfdisc_t*	dcnewfilter(char* cmd);
extern int		dcdelfilter(Sfdisc_t* disc);
extern Sfdisc_t*	dcnewsubstream(Sfio_t* f, long offset, long extent);
extern int		dcdelsubstream(Sfdisc_t* disc);
extern Sfdisc_t*	dcnewlzw(void);
extern int		dcdellzw(Sfdisc_t* disc);
extern Sfdisc_t*	dcnewunion(Sfio_t** flist, int n);
extern int		dcdelunion(Sfdisc_t* disc);

DESCRIPTION

I/O disciplines are used to extend the data processing power of sfio streams. The convention for using the disciplines in this package is to use the call dcnewXXX() to create a discipline of the type XXX and to use dcdelXXX() to destroy it. A discipline is enable by inserting it into the desired stream using the sfdisc() call. A discipline can be used on only one stream. It is unsafe to share a discipline on two or more streams since the discipline may maintain states between successive IO calls. For multiple uses, dcnewXXX() should be used to create a distinct discipline for each stream. Each discipline structure is equipped with an exception handler that causes self-destruction when the associated stream is closed.

Sfdisc_t* dcnewskable(Sfio_t* f);

int dcdelskable(Sfdisc_t* disc);

dcnewskable() creates a discipline that when inserted on the stream f will ensure that f is seekable. If f is originally unseekable, data will be shadowed in a temporary file stream to allow seekability. dcnewskable() returns the discipline on success and NULL on failure.

Sfdisc_t* dcnewtee(Sfio_t* tee);

int dcdeltee(Sfdisc_t* disc);

dcnewtee() creates a discipline that when inserted into a stream f will duplicate to the stream tee any data written to f. dcnewtee() returns the discipline on success and NULL on failure.

Sfdisc_t* dcnewfilter(char* cmd);

int dcdelfilter(Sfdisc_t* disc);

dcnewfilter() creates a discipline that when inserted into a stream f will run the command cmd to process any input data before making it available to the application. For example, dcnewfilter("uncompress") is an equivalent but slower alternative to the lzw discipline below. dcnewfilter() returns the discipline on success and NULL on failure.

Sfdisc_t* dcnewsubstream(Sfio_t* base, long offset, long extent);

int dcdelsubstream(Sfdisc_t* disc);

dcnewsubstream() creates a discipline that reserves a portion of the stream base starting at offset with length extent and makes this portion appear as if it is a stream. When this discipline is inserted into a stream, it will make cause all IO operations on this stream to take place in the reserved portion of the base stream. dcnewsubstream() returns the discipline on success and NULL on failure.

Sfdisc_t* dcnewlzw(void);

int dcdellzw(Sfdisc_t* disc);

dcnewlzw() creates a discipline that when inserted into a stream f will run the uncompress algorithm on input data from f before making it available to the application. This is useful to allow applications to process data from a file packed with the UNIX compress utility as if the data is in plain text. dcnewlzw() returns the discipline on success and NULL on failure.

Sfdisc_t* dcnewunion(Sfio_t** list, int n);

int dcdelunion(Sfdisc_t* disc);

dcnewunion() creates a discipline that concatenates input data from all n streams in list. When inserted into a stream f, this discipline will cause all input operations on f to come from the merged data stream. dcnewunion() returns the discipline on success and NULL on failure.

ACKNOWLEDGMENTS

Dave Korn contributed the substream discipline. Jim Arnold contributed the lzw discipline.

NOTES

Since we are not sure of the legal responsibilities concerning the lzw patent, the lzw discipline is not currently distributed with any release of sfio outside of AT&T.

AUTHOR

Kiem-Phong Vo, kpv@research.att.com.

16 June 1993