| 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) |