da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.TH SFDISC 3 "16 June 1993"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fBsfdisc\fR \- \fBsfio\fP disciplines
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SYNOPSIS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ta 1.0i 2.0i 3.0i 4.0i 5.0i
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern Sfdisc_t* dcnewskable(Sfio_t* f);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern int dcdelskable(Sfdisc_t* disc);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern Sfdisc_t* dcnewtee(Sfio_t* tee);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern int dcdeltee(Sfdisc_t* disc);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern Sfdisc_t* dcnewfilter(char* cmd);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern int dcdelfilter(Sfdisc_t* disc);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern Sfdisc_t* dcnewsubstream(Sfio_t* f, long offset, long extent);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern int dcdelsubstream(Sfdisc_t* disc);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern Sfdisc_t* dcnewlzw(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern int dcdellzw(Sfdisc_t* disc);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern Sfdisc_t* dcnewunion(Sfio_t** flist, int n);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinextern int dcdelunion(Sfdisc_t* disc);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH DESCRIPTION
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinI/O disciplines are used to extend the data processing power of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIsfio\fP streams. The convention for using the disciplines
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin this package is to use the call \f5dcnewXXX()\fP to create
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china discipline of the type \f5XXX\fP and to use \f5dcdelXXX()\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto destroy it.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA discipline is enable by inserting it into the desired
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinstream using the \f5sfdisc()\fP call. A discipline can be used on only
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinone stream. It is unsafe to share a discipline on two or more streams
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinsince the discipline may maintain states between successive IO calls.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFor multiple uses, \f5dcnewXXX()\fP should be used
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto create a distinct discipline for each stream.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinEach discipline structure is equipped with an exception handler
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthat causes self-destruction when the associated stream is closed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " Sfdisc_t* dcnewskable(Sfio_t* f);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " int dcdelskable(Sfdisc_t* disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewskable()\fP creates a discipline that when inserted
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon the stream \f5f\fP will ensure that \f5f\fP is seekable.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \f5f\fP is originally unseekable, data will be shadowed
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin a temporary file stream to allow seekability.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewskable()\fP returns the discipline on success and \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " Sfdisc_t* dcnewtee(Sfio_t* tee);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " int dcdeltee(Sfdisc_t* disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewtee()\fP creates a discipline that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwhen inserted into a stream \f5f\fP will duplicate to the stream \f5tee\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinany data written to \f5f\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewtee()\fP returns the discipline on success and \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " Sfdisc_t* dcnewfilter(char* cmd);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " int dcdelfilter(Sfdisc_t* disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewfilter()\fP creates a discipline that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwhen inserted into a stream \f5f\fP will run the command \f5cmd\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto process any input data before making it available to the application.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFor example, \f5dcnewfilter("uncompress")\fP is an equivalent but slower
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinalternative to the lzw discipline below.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewfilter()\fP returns the discipline on success and \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " Sfdisc_t* dcnewsubstream(Sfio_t* base, long offset, long extent);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " int dcdelsubstream(Sfdisc_t* disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewsubstream()\fP creates a discipline that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreserves a portion of the stream \f5base\fP starting at \f5offset\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwith length \f5extent\fP and makes this portion appear as if it is
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china stream. When this discipline is inserted into a stream, it will make
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincause all IO operations on this stream to take place in the reserved
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinportion of the \f5base\fP stream.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewsubstream()\fP returns the discipline on success and \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " Sfdisc_t* dcnewlzw(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " int dcdellzw(Sfdisc_t* disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewlzw()\fP creates a discipline that when inserted into
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china stream \f5f\fP will run the \fBuncompress\fP algorithm
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon input data from \f5f\fP before making it available to the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinapplication. This is useful to allow applications to process
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindata from a file packed with the UNIX \fBcompress\fP utility
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinas if the data is in plain text.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewlzw()\fP returns the discipline on success and \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " Sfdisc_t* dcnewunion(Sfio_t** list, int n);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Ss " int dcdelunion(Sfdisc_t* disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewunion()\fP creates a discipline that concatenates
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininput data from all \f5n\fP streams in \f5list\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhen inserted into a stream \f5f\fP, this discipline will cause
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinall input operations on \f5f\fP to come from the merged data stream.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dcnewunion()\fP returns the discipline on success and \f5NULL\fP on failure.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.SH ACKNOWLEDGMENTS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinDave Korn contributed the substream discipline.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinJim Arnold contributed the lzw discipline.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSince we are not sure of the legal responsibilities concerning the lzw patent,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe lzw discipline is not currently distributed with any release of sfio
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinoutside of AT&T.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinKiem-Phong Vo, kpv@research.att.com.