sfdisc.3 revision 3e14f97f673e8a630f076077de35afdd43dc1587
199767f8919635c4928607450d9e0abb932109ceToomas Soome.TH SFDISC 3 "16 June 1993"
199767f8919635c4928607450d9e0abb932109ceToomas Soome\fBsfdisc\fR \- \fBsfio\fP disciplines
199767f8919635c4928607450d9e0abb932109ceToomas Soome.ta 1.0i 2.0i 3.0i 4.0i 5.0i
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern Sfdisc_t* dcnewskable(Sfio_t* f);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern int dcdelskable(Sfdisc_t* disc);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern Sfdisc_t* dcnewtee(Sfio_t* tee);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern int dcdeltee(Sfdisc_t* disc);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern Sfdisc_t* dcnewfilter(char* cmd);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern int dcdelfilter(Sfdisc_t* disc);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern Sfdisc_t* dcnewsubstream(Sfio_t* f, long offset, long extent);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern int dcdelsubstream(Sfdisc_t* disc);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern Sfdisc_t* dcnewlzw(void);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern int dcdellzw(Sfdisc_t* disc);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern Sfdisc_t* dcnewunion(Sfio_t** flist, int n);
199767f8919635c4928607450d9e0abb932109ceToomas Soomeextern int dcdelunion(Sfdisc_t* disc);
199767f8919635c4928607450d9e0abb932109ceToomas Soome.SH DESCRIPTION
199767f8919635c4928607450d9e0abb932109ceToomas SoomeI/O disciplines are used to extend the data processing power of
199767f8919635c4928607450d9e0abb932109ceToomas Soome\fIsfio\fP streams. The convention for using the disciplines
199767f8919635c4928607450d9e0abb932109ceToomas Soomein this package is to use the call \f5dcnewXXX()\fP to create
199767f8919635c4928607450d9e0abb932109ceToomas Soomea discipline of the type \f5XXX\fP and to use \f5dcdelXXX()\fP
199767f8919635c4928607450d9e0abb932109ceToomas Soometo destroy it.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeA discipline is enable by inserting it into the desired
199767f8919635c4928607450d9e0abb932109ceToomas Soomestream using the \f5sfdisc()\fP call. A discipline can be used on only
199767f8919635c4928607450d9e0abb932109ceToomas Soomeone stream. It is unsafe to share a discipline on two or more streams
199767f8919635c4928607450d9e0abb932109ceToomas Soomesince the discipline may maintain states between successive IO calls.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeFor multiple uses, \f5dcnewXXX()\fP should be used
199767f8919635c4928607450d9e0abb932109ceToomas Soometo create a distinct discipline for each stream.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeEach discipline structure is equipped with an exception handler
199767f8919635c4928607450d9e0abb932109ceToomas Soomethat causes self-destruction when the associated stream is closed.
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " Sfdisc_t* dcnewskable(Sfio_t* f);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " int dcdelskable(Sfdisc_t* disc);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewskable()\fP creates a discipline that when inserted
199767f8919635c4928607450d9e0abb932109ceToomas Soomeon the stream \f5f\fP will ensure that \f5f\fP is seekable.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeIf \f5f\fP is originally unseekable, data will be shadowed
199767f8919635c4928607450d9e0abb932109ceToomas Soomein a temporary file stream to allow seekability.
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewskable()\fP returns the discipline on success and \f5NULL\fP on failure.
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " Sfdisc_t* dcnewtee(Sfio_t* tee);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " int dcdeltee(Sfdisc_t* disc);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewtee()\fP creates a discipline that
199767f8919635c4928607450d9e0abb932109ceToomas Soomewhen inserted into a stream \f5f\fP will duplicate to the stream \f5tee\fP
199767f8919635c4928607450d9e0abb932109ceToomas Soomeany data written to \f5f\fP.
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewtee()\fP returns the discipline on success and \f5NULL\fP on failure.
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " Sfdisc_t* dcnewfilter(char* cmd);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " int dcdelfilter(Sfdisc_t* disc);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewfilter()\fP creates a discipline that
199767f8919635c4928607450d9e0abb932109ceToomas Soomewhen inserted into a stream \f5f\fP will run the command \f5cmd\fP
199767f8919635c4928607450d9e0abb932109ceToomas Soometo process any input data before making it available to the application.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeFor example, \f5dcnewfilter("uncompress")\fP is an equivalent but slower
199767f8919635c4928607450d9e0abb932109ceToomas Soomealternative to the lzw discipline below.
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewfilter()\fP returns the discipline on success and \f5NULL\fP on failure.
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " Sfdisc_t* dcnewsubstream(Sfio_t* base, long offset, long extent);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " int dcdelsubstream(Sfdisc_t* disc);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewsubstream()\fP creates a discipline that
199767f8919635c4928607450d9e0abb932109ceToomas Soomereserves a portion of the stream \f5base\fP starting at \f5offset\fP
199767f8919635c4928607450d9e0abb932109ceToomas Soomewith length \f5extent\fP and makes this portion appear as if it is
199767f8919635c4928607450d9e0abb932109ceToomas Soomea stream. When this discipline is inserted into a stream, it will make
199767f8919635c4928607450d9e0abb932109ceToomas Soomecause all IO operations on this stream to take place in the reserved
199767f8919635c4928607450d9e0abb932109ceToomas Soomeportion of the \f5base\fP stream.
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewsubstream()\fP returns the discipline on success and \f5NULL\fP on failure.
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " Sfdisc_t* dcnewlzw(void);
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " int dcdellzw(Sfdisc_t* disc);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewlzw()\fP creates a discipline that when inserted into
199767f8919635c4928607450d9e0abb932109ceToomas Soomea stream \f5f\fP will run the \fBuncompress\fP algorithm
199767f8919635c4928607450d9e0abb932109ceToomas Soomeon input data from \f5f\fP before making it available to the
199767f8919635c4928607450d9e0abb932109ceToomas Soomeapplication. This is useful to allow applications to process
199767f8919635c4928607450d9e0abb932109ceToomas Soomedata from a file packed with the UNIX \fBcompress\fP utility
199767f8919635c4928607450d9e0abb932109ceToomas Soomeas if the data is in plain text.
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewlzw()\fP returns the discipline on success and \f5NULL\fP on failure.
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " Sfdisc_t* dcnewunion(Sfio_t** list, int n);
199767f8919635c4928607450d9e0abb932109ceToomas Soome.Ss " int dcdelunion(Sfdisc_t* disc);"
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewunion()\fP creates a discipline that concatenates
199767f8919635c4928607450d9e0abb932109ceToomas Soomeinput data from all \f5n\fP streams in \f5list\fP.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeWhen inserted into a stream \f5f\fP, this discipline will cause
199767f8919635c4928607450d9e0abb932109ceToomas Soomeall input operations on \f5f\fP to come from the merged data stream.
199767f8919635c4928607450d9e0abb932109ceToomas Soome\f5dcnewunion()\fP returns the discipline on success and \f5NULL\fP on failure.
199767f8919635c4928607450d9e0abb932109ceToomas Soome.SH ACKNOWLEDGMENTS
199767f8919635c4928607450d9e0abb932109ceToomas SoomeDave Korn contributed the substream discipline.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeJim Arnold contributed the lzw discipline.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeSince we are not sure of the legal responsibilities concerning the lzw patent,
199767f8919635c4928607450d9e0abb932109ceToomas Soomethe lzw discipline is not currently distributed with any release of sfio
199767f8919635c4928607450d9e0abb932109ceToomas Soomeoutside of AT&T.
199767f8919635c4928607450d9e0abb932109ceToomas SoomeKiem-Phong Vo, kpv@research.att.com.