1.fp 5 CW 2.TH SFDISC 3 "16 June 1993" 3.SH NAME 4\fBsfdisc\fR \- \fBsfio\fP disciplines 5.SH SYNOPSIS 6.de Tp 7.fl 8.ne 2 9.TP 10.. 11.de Ss 12.fl 13.ne 2 14.SS "\\$1" 15.. 16.ta 1.0i 2.0i 3.0i 4.0i 5.0i 17.nf 18.ft 5 19#include <sfdisc.h> 20 21extern Sfdisc_t* dcnewskable(Sfio_t* f); 22extern int dcdelskable(Sfdisc_t* disc); 23 24extern Sfdisc_t* dcnewtee(Sfio_t* tee); 25extern int dcdeltee(Sfdisc_t* disc); 26 27extern Sfdisc_t* dcnewfilter(char* cmd); 28extern int dcdelfilter(Sfdisc_t* disc); 29 30extern Sfdisc_t* dcnewsubstream(Sfio_t* f, long offset, long extent); 31extern int dcdelsubstream(Sfdisc_t* disc); 32 33extern Sfdisc_t* dcnewlzw(void); 34extern int dcdellzw(Sfdisc_t* disc); 35 36extern Sfdisc_t* dcnewunion(Sfio_t** flist, int n); 37extern int dcdelunion(Sfdisc_t* disc); 38.ft 1 39.fi 40.SH DESCRIPTION 41.PP 42I/O disciplines are used to extend the data processing power of 43\fIsfio\fP streams. The convention for using the disciplines 44in this package is to use the call \f5dcnewXXX()\fP to create 45a discipline of the type \f5XXX\fP and to use \f5dcdelXXX()\fP 46to destroy it. 47A discipline is enable by inserting it into the desired 48stream using the \f5sfdisc()\fP call. A discipline can be used on only 49one stream. It is unsafe to share a discipline on two or more streams 50since the discipline may maintain states between successive IO calls. 51For multiple uses, \f5dcnewXXX()\fP should be used 52to create a distinct discipline for each stream. 53Each discipline structure is equipped with an exception handler 54that causes self-destruction when the associated stream is closed. 55.PP 56.Ss " Sfdisc_t* dcnewskable(Sfio_t* f);" 57.Ss " int dcdelskable(Sfdisc_t* disc);" 58\f5dcnewskable()\fP creates a discipline that when inserted 59on the stream \f5f\fP will ensure that \f5f\fP is seekable. 60If \f5f\fP is originally unseekable, data will be shadowed 61in a temporary file stream to allow seekability. 62\f5dcnewskable()\fP returns the discipline on success and \f5NULL\fP on failure. 63 64.Ss " Sfdisc_t* dcnewtee(Sfio_t* tee);" 65.Ss " int dcdeltee(Sfdisc_t* disc);" 66\f5dcnewtee()\fP creates a discipline that 67when inserted into a stream \f5f\fP will duplicate to the stream \f5tee\fP 68any data written to \f5f\fP. 69\f5dcnewtee()\fP returns the discipline on success and \f5NULL\fP on failure. 70 71.Ss " Sfdisc_t* dcnewfilter(char* cmd);" 72.Ss " int dcdelfilter(Sfdisc_t* disc);" 73\f5dcnewfilter()\fP creates a discipline that 74when inserted into a stream \f5f\fP will run the command \f5cmd\fP 75to process any input data before making it available to the application. 76For example, \f5dcnewfilter("uncompress")\fP is an equivalent but slower 77alternative to the lzw discipline below. 78\f5dcnewfilter()\fP returns the discipline on success and \f5NULL\fP on failure. 79 80.Ss " Sfdisc_t* dcnewsubstream(Sfio_t* base, long offset, long extent);" 81.Ss " int dcdelsubstream(Sfdisc_t* disc);" 82\f5dcnewsubstream()\fP creates a discipline that 83reserves a portion of the stream \f5base\fP starting at \f5offset\fP 84with length \f5extent\fP and makes this portion appear as if it is 85a stream. When this discipline is inserted into a stream, it will make 86cause all IO operations on this stream to take place in the reserved 87portion of the \f5base\fP stream. 88\f5dcnewsubstream()\fP returns the discipline on success and \f5NULL\fP on failure. 89 90.Ss " Sfdisc_t* dcnewlzw(void); 91.Ss " int dcdellzw(Sfdisc_t* disc);" 92\f5dcnewlzw()\fP creates a discipline that when inserted into 93a stream \f5f\fP will run the \fBuncompress\fP algorithm 94on input data from \f5f\fP before making it available to the 95application. This is useful to allow applications to process 96data from a file packed with the UNIX \fBcompress\fP utility 97as if the data is in plain text. 98\f5dcnewlzw()\fP returns the discipline on success and \f5NULL\fP on failure. 99 100.Ss " Sfdisc_t* dcnewunion(Sfio_t** list, int n); 101.Ss " int dcdelunion(Sfdisc_t* disc);" 102\f5dcnewunion()\fP creates a discipline that concatenates 103input data from all \f5n\fP streams in \f5list\fP. 104When inserted into a stream \f5f\fP, this discipline will cause 105all input operations on \f5f\fP to come from the merged data stream. 106\f5dcnewunion()\fP returns the discipline on success and \f5NULL\fP on failure. 107 108.SH ACKNOWLEDGMENTS 109Dave Korn contributed the substream discipline. 110Jim Arnold contributed the lzw discipline. 111 112.SH NOTES 113Since we are not sure of the legal responsibilities concerning the lzw patent, 114the lzw discipline is not currently distributed with any release of sfio 115outside of AT&T. 116 117.SH AUTHOR 118Kiem-Phong Vo, kpv@research.att.com. 119