usr/src/lib/libast/common/man/sfdisc.3

   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
  21 extern Sfdisc_t*        dcnewskable(Sfio_t* f);
  22 extern int              dcdelskable(Sfdisc_t* disc);
  23
  24 extern Sfdisc_t*        dcnewtee(Sfio_t* tee);
  25 extern int              dcdeltee(Sfdisc_t* disc);
  26
  27 extern Sfdisc_t*        dcnewfilter(char* cmd);
  28 extern int              dcdelfilter(Sfdisc_t* disc);
  29
  30 extern Sfdisc_t*        dcnewsubstream(Sfio_t* f, long offset, long extent);
  31 extern int              dcdelsubstream(Sfdisc_t* disc);
  32
  33 extern Sfdisc_t*        dcnewlzw(void);
  34 extern int              dcdellzw(Sfdisc_t* disc);
  35
  36 extern Sfdisc_t*        dcnewunion(Sfio_t** flist, int n);
  37 extern int              dcdelunion(Sfdisc_t* disc);
  38 .ft 1
  39 .fi
  40 .SH DESCRIPTION
  41 .PP
  42 I/O disciplines are used to extend the data processing power of
  43 \fIsfio\fP streams. The convention for using the disciplines
  44 in this package is to use the call \f5dcnewXXX()\fP to create
  45 a discipline of the type \f5XXX\fP and to use \f5dcdelXXX()\fP
  46 to destroy it.
  47 A discipline is enable by inserting it into the desired
  48 stream using the \f5sfdisc()\fP call. A discipline can be used on only
  49 one stream. It is unsafe to share a discipline on two or more streams
  50 since the discipline may maintain states between successive IO calls.
  51 For multiple uses, \f5dcnewXXX()\fP should be used
  52 to create a distinct discipline for each stream.
  53 Each discipline structure is equipped with an exception handler
  54 that 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
  59 on the stream \f5f\fP will ensure that \f5f\fP is seekable.
  60 If \f5f\fP is originally unseekable, data will be shadowed
  61 in 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
  67 when inserted into a stream \f5f\fP will duplicate to the stream \f5tee\fP
  68 any 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
  74 when inserted into a stream \f5f\fP will run the command \f5cmd\fP
  75 to process any input data before making it available to the application.
  76 For example, \f5dcnewfilter("uncompress")\fP is an equivalent but slower
  77 alternative 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
  83 reserves a portion of the stream \f5base\fP starting at \f5offset\fP
  84 with length \f5extent\fP and makes this portion appear as if it is
  85 a stream. When this discipline is inserted into a stream, it will make
  86 cause all IO operations on this stream to take place in the reserved
  87 portion 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
  93 a stream \f5f\fP will run the \fBuncompress\fP algorithm
  94 on input data from \f5f\fP before making it available to the
  95 application. This is useful to allow applications to process
  96 data from a file packed with the UNIX \fBcompress\fP utility
  97 as 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
 103 input data from all \f5n\fP streams in \f5list\fP.
 104 When inserted into a stream \f5f\fP, this discipline will cause
 105 all 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
 109 Dave Korn contributed the substream discipline.
 110 Jim Arnold contributed the lzw discipline.
 111
 112 .SH NOTES
 113 Since we are not sure of the legal responsibilities concerning the lzw patent,
 114 the lzw discipline is not currently distributed with any release of sfio
 115 outside of AT&T.
 116
 117 .SH AUTHOR
 118 Kiem-Phong Vo, kpv@research.att.com.