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