.fp 5 CW
.TH SFDISC 3 "16 June 1993"
.SH NAME
\fBsfdisc\fR \- \fBsfio\fP disciplines
.SH SYNOPSIS
.de Tp
.fl
.ne 2
.TP
..
.de Ss
.fl
.ne 2
.SS "\\$1"
..
.ta 1.0i 2.0i 3.0i 4.0i 5.0i
.nf
.ft 5
#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);
.ft 1
.fi
.SH DESCRIPTION
.PP
I/O disciplines are used to extend the data processing power of
\fIsfio\fP streams. The convention for using the disciplines
in this package is to use the call \f5dcnewXXX()\fP to create
a discipline of the type \f5XXX\fP and to use \f5dcdelXXX()\fP
to destroy it.
A discipline is enable by inserting it into the desired
stream using the \f5sfdisc()\fP 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, \f5dcnewXXX()\fP 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.
.PP
.Ss "  Sfdisc_t* dcnewskable(Sfio_t* f);"
.Ss "  int dcdelskable(Sfdisc_t* disc);"
\f5dcnewskable()\fP creates a discipline that when inserted
on the stream \f5f\fP will ensure that \f5f\fP is seekable.
If \f5f\fP is originally unseekable, data will be shadowed
in a temporary file stream to allow seekability.
\f5dcnewskable()\fP returns the discipline on success and \f5NULL\fP on failure.

.Ss "  Sfdisc_t* dcnewtee(Sfio_t* tee);"
.Ss "  int dcdeltee(Sfdisc_t* disc);"
\f5dcnewtee()\fP creates a discipline that
when inserted into a stream \f5f\fP will duplicate to the stream \f5tee\fP
any data written to \f5f\fP.
\f5dcnewtee()\fP returns the discipline on success and \f5NULL\fP on failure.

.Ss "  Sfdisc_t* dcnewfilter(char* cmd);"
.Ss "  int dcdelfilter(Sfdisc_t* disc);"
\f5dcnewfilter()\fP creates a discipline that
when inserted into a stream \f5f\fP will run the command \f5cmd\fP
to process any input data before making it available to the application.
For example, \f5dcnewfilter("uncompress")\fP is an equivalent but slower
alternative to the lzw discipline below.
\f5dcnewfilter()\fP returns the discipline on success and \f5NULL\fP on failure.

.Ss "  Sfdisc_t* dcnewsubstream(Sfio_t* base, long offset, long extent);"
.Ss "  int dcdelsubstream(Sfdisc_t* disc);"
\f5dcnewsubstream()\fP creates a discipline that
reserves a portion of the stream \f5base\fP starting at \f5offset\fP
with length \f5extent\fP 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 \f5base\fP stream.
\f5dcnewsubstream()\fP returns the discipline on success and \f5NULL\fP on failure.

.Ss "  Sfdisc_t* dcnewlzw(void);
.Ss "  int dcdellzw(Sfdisc_t* disc);"
\f5dcnewlzw()\fP creates a discipline that when inserted into
a stream \f5f\fP will run the \fBuncompress\fP algorithm
on input data from \f5f\fP before making it available to the
application. This is useful to allow applications to process
data from a file packed with the UNIX \fBcompress\fP utility
as if the data is in plain text.
\f5dcnewlzw()\fP returns the discipline on success and \f5NULL\fP on failure.

.Ss "  Sfdisc_t* dcnewunion(Sfio_t** list, int n);
.Ss "  int dcdelunion(Sfdisc_t* disc);"
\f5dcnewunion()\fP creates a discipline that concatenates
input data from all \f5n\fP streams in \f5list\fP.
When inserted into a stream \f5f\fP, this discipline will cause
all input operations on \f5f\fP to come from the merged data stream.
\f5dcnewunion()\fP returns the discipline on success and \f5NULL\fP on failure.

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

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

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