mdw@git.distorted.org.uk Git - ezmlm/blob - substdio_in.3

   1 .TH substdio_in 3
   2 .SH NAME
   3 substdio_in \- substdio input routines
   4 .SH SYNTAX
   5 .B #include <substdio.h>
   6
   7 int \fBsubstdio_get\fP(&\fIs\fR,\fIto\fR,\fIlen\fR);
   8
   9 int \fBsubstdio_bget\fP(&\fIs\fR,\fIto\fR,\fIlen\fR);
  10
  11 int \fBsubstdio_feed\fP(&\fIs\fR);
  12
  13 char *\fBsubstdio_peek\fP(&\fIs\fR);
  14
  15 void \fBsubstdio_seek\fP(&\fIs\fR,\fIlen\fR);
  16
  17 substdio \fIs\fR;
  18 .br
  19 char *\fIto\fR;
  20 .br
  21 int \fIlen\fR;
  22 .SH DESCRIPTION
  23 .B substdio_get
  24 reads at most
  25 .I len
  26 characters from
  27 .I s
  28 into the character array
  29 .IR to .
  30 It returns the number of characters read,
  31 0 for end of file,
  32 or -1 for error,
  33 setting
  34 .B errno
  35 appropriately.
  36
  37 .B substdio_bget
  38 has the same function as
  39 .BR substdio_get .
  40 The difference is what happens when there is no buffered data and
  41 .I len
  42 exceeds the buffer size:
  43 .B substdio_get
  44 tries to read
  45 .I len
  46 characters, whereas
  47 .B substdio_bget
  48 tries to read one buffer of characters.
  49 In some cases
  50 .B substdio_bget
  51 will be more efficient than
  52 .BR substdio_get .
  53
  54 .B substdio_feed
  55 makes sure that there is buffered data,
  56 so that the next
  57 .B substdio_get
  58 or
  59 .B substdio_bget
  60 will succeed.
  61 If the buffer is empty,
  62 .B substdio_feed
  63 tries to fill it;
  64 it returns 0 for end of file, -1 for error,
  65 or the number of buffered characters on success.
  66 If the buffer already had data,
  67 .B substdio_feed
  68 leaves it alone and returns the number of buffered characters.
  69
  70 .B substdio_peek
  71 returns a pointer to the buffered data.
  72
  73 .B substdio_seek
  74 throws away
  75 .I len
  76 buffered characters,
  77 as if they had been read.
  78 .I len
  79 must be at least 0 and at most the amount of buffered data.
  80
  81 The
  82 .B substdio_PEEK
  83 and
  84 .B substdio_SEEK
  85 macros behave the same way as
  86 .B substdio_peek
  87 and
  88 .B substdio_seek
  89 but may evaluate their arguments several times.
  90
  91 The point of
  92 .B substdio_peek
  93 and
  94 .B substdio_seek
  95 is to read data without unnecessary copies.
  96 Sample code:
  97
  98 .EX
  99   for (;;) {
 100 .br
 101     n = substdio_feed(s);
 102 .br
 103     if (n <= 0) return n;
 104 .br
 105     x = substdio_PEEK(s);
 106 .br
 107     handle(x,n);
 108 .br
 109     substdio_SEEK(s,n);
 110 .br
 111   }
 112 .EE
 113
 114 The
 115 .B SUBSTDIO_INSIZE
 116 macro is defined as a reasonably large input buffer size for
 117 .BR substdio_fdbuf .
 118 .SH "INTERNALS"
 119 When a
 120 .B substdio
 121 variable
 122 .I s
 123 is used for input,
 124 there is free buffer space from
 125 .I s\fB.x
 126 to
 127 .I s\fB.x\fR +
 128 .I s\fB.n\fR;
 129 data is buffered from
 130 .I s\fB.x\fR +
 131 .I s\fB.n
 132 to
 133 .I s\fB.x\fR +
 134 .I s\fB.n\fR +
 135 .I s\fB.p\fR;
 136 the total buffer length is
 137 .I s\fB.n\fR +
 138 .I s\fB.p\fR.
 139 .SH "SEE ALSO"
 140 substdio(3)