[ezmlm] / substdio_in.3

.TH substdio_in 3
.SH NAME
substdio_in \- substdio input routines
.SH SYNTAX
.B #include <substdio.h>

int \fBsubstdio_get\fP(&\fIs\fR,\fIto\fR,\fIlen\fR);

int \fBsubstdio_bget\fP(&\fIs\fR,\fIto\fR,\fIlen\fR);

int \fBsubstdio_feed\fP(&\fIs\fR);

char *\fBsubstdio_peek\fP(&\fIs\fR);

void \fBsubstdio_seek\fP(&\fIs\fR,\fIlen\fR);

substdio \fIs\fR;
.br
char *\fIto\fR;
.br
int \fIlen\fR;
.SH DESCRIPTION
.B substdio_get
reads at most
.I len
characters from
.I s
into the character array
.IR to .
It returns the number of characters read,
0 for end of file,
or -1 for error,
setting
.B errno
appropriately.

.B substdio_bget
has the same function as
.BR substdio_get .
The difference is what happens when there is no buffered data and
.I len
exceeds the buffer size:
.B substdio_get
tries to read
.I len
characters, whereas
.B substdio_bget
tries to read one buffer of characters.
In some cases
.B substdio_bget
will be more efficient than
.BR substdio_get .

.B substdio_feed
makes sure that there is buffered data,
so that the next
.B substdio_get
or
.B substdio_bget
will succeed.
If the buffer is empty,
.B substdio_feed
tries to fill it;
it returns 0 for end of file, -1 for error,
or the number of buffered characters on success.
If the buffer already had data,
.B substdio_feed
leaves it alone and returns the number of buffered characters.

.B substdio_peek
returns a pointer to the buffered data.

.B substdio_seek
throws away
.I len
buffered characters,
as if they had been read.
.I len
must be at least 0 and at most the amount of buffered data.

The
.B substdio_PEEK
and
.B substdio_SEEK
macros behave the same way as
.B substdio_peek
and
.B substdio_seek
but may evaluate their arguments several times.

The point of
.B substdio_peek
and
.B substdio_seek
is to read data without unnecessary copies.
Sample code:

.EX
  for (;;) {
.br
    n = substdio_feed(s);
.br
    if (n <= 0) return n;
.br
    x = substdio_PEEK(s);
.br
    handle(x,n);
.br
    substdio_SEEK(s,n);
.br
  }
.EE

The
.B SUBSTDIO_INSIZE
macro is defined as a reasonably large input buffer size for
.BR substdio_fdbuf .
.SH "INTERNALS"
When a
.B substdio
variable
.I s
is used for input,
there is free buffer space from
.I s\fB.x
to
.I s\fB.x\fR +
.I s\fB.n\fR;
data is buffered from
.I s\fB.x\fR +
.I s\fB.n
to
.I s\fB.x\fR +
.I s\fB.n\fR +
.I s\fB.p\fR;
the total buffer length is
.I s\fB.n\fR +
.I s\fB.p\fR.
.SH "SEE ALSO"
substdio(3)
Commit	Line	Data
5b62e993 MW	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)