[ezmlm] / substdio.3

.TH substdio 3
.SH NAME
substdio \- the Sub-Standard Input/Output Library
.SH SYNTAX
.B #include <substdio.h>

void \fBsubstdio_fdbuf\fP(&\fIs\fR,\fIop\fR,\fIfd\fR,\fIbuf\fR,\fIlen\fR);

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

substdio \fIs\fR;
.br
int (*\fIop\fR)();
.br
int \fIfd\fR;
.br
char *\fIbuf\fR;
.br
int \fIlen\fR;
.SH DESCRIPTION
.B substdio
is the Sub-Standard I/O Library.
.B substdio
contains only a few of the features of stdio;
it is a fast, lightweight, low-level library,
suitable for use as a component of higher-level I/O libraries.

The point of
.B substdio
is to provide buffered I/O.
The basic object in
.B substdio
is the
.B substdio
structure;
a
.B substdio
variable stores
an operation,
a descriptor,
and
a pointer into a buffer of some nonzero length.
The
.B substdio
operations read data from the buffer,
filling the buffer as necessary using the operation on the descriptor,
or write data to the buffer,
flushing the buffer as necessary using the operation on the descriptor.
Input and output operations cannot be mixed.

.B substdio_fdbuf
initializes a
.B substdio
variable.
The operation is
.IR op .
The descriptor is
.IR fd .
The buffer is
.IR buf ,
an array of
.I len
chars.

.I op
will be called as
.I op\fR(\fIfd\fR,\fIx\fR,\fIn\fR).
Here
.I x
is a pointer to an array of characters of length
.IR n ;
.I op
must read some characters from
.I fd
to that array, or write some characters to
.I fd
from that array.
The return value from
.I op
must be the number of characters read or written.
0 characters read means end of input;
0 characters written means that the write operation
should be tried again immediately.
On error,
.I op
must return -1,
setting
.B errno
appropriately, without reading or writing anything.
Most errors are returned directly to the
.B substdio
caller, but an error of
.B error_intr
means that the operation should be tried again immediately.

There is a
.B SUBSTDIO_FDBUF
macro that can be used to statically initialize a
.B substdio
variable:

.EX
   substdio s = SUBSTDIO_FDBUF(op,fd,buf,len);
.EE

.B substdio_fileno
returns the
descriptor for an initialized
.B substdio
variable.
.SH "SEE ALSO"
substdio_in(3),
substdio_out(3),
substdio_copy(3),
error(3)
Commit	Line	Data
5b62e993 MW	1	.TH substdio 3
	2	.SH NAME
	3	substdio \- the Sub-Standard Input/Output Library
	4	.SH SYNTAX
	5	.B #include <substdio.h>
	6
	7	void \fBsubstdio_fdbuf\fP(&\fIs\fR,\fIop\fR,\fIfd\fR,\fIbuf\fR,\fIlen\fR);
	8
	9	int \fBsubstdio_fileno\fP(&\fIs\fR);
	10
	11	substdio \fIs\fR;
	12	.br
	13	int (*\fIop\fR)();
	14	.br
	15	int \fIfd\fR;
	16	.br
	17	char *\fIbuf\fR;
	18	.br
	19	int \fIlen\fR;
	20	.SH DESCRIPTION
	21	.B substdio
	22	is the Sub-Standard I/O Library.
	23	.B substdio
	24	contains only a few of the features of stdio;
	25	it is a fast, lightweight, low-level library,
	26	suitable for use as a component of higher-level I/O libraries.
	27
	28	The point of
	29	.B substdio
	30	is to provide buffered I/O.
	31	The basic object in
	32	.B substdio
	33	is the
	34	.B substdio
	35	structure;
	36	a
	37	.B substdio
	38	variable stores
	39	an operation,
	40	a descriptor,
	41	and
	42	a pointer into a buffer of some nonzero length.
	43	The
	44	.B substdio
	45	operations read data from the buffer,
	46	filling the buffer as necessary using the operation on the descriptor,
	47	or write data to the buffer,
	48	flushing the buffer as necessary using the operation on the descriptor.
	49	Input and output operations cannot be mixed.
	50
	51	.B substdio_fdbuf
	52	initializes a
	53	.B substdio
	54	variable.
	55	The operation is
	56	.IR op .
	57	The descriptor is
	58	.IR fd .
	59	The buffer is
	60	.IR buf ,
	61	an array of
	62	.I len
	63	chars.
	64
65	.I op
66	will be called as
67	.I op\fR(\fIfd\fR,\fIx\fR,\fIn\fR).
68	Here
69	.I x
70	is a pointer to an array of characters of length
71	.IR n ;
72	.I op
73	must read some characters from
74	.I fd
75	to that array, or write some characters to
76	.I fd
77	from that array.
78	The return value from
79	.I op
80	must be the number of characters read or written.
81	0 characters read means end of input;
82	0 characters written means that the write operation
83	should be tried again immediately.
84	On error,
85	.I op
86	must return -1,
87	setting
88	.B errno
89	appropriately, without reading or writing anything.
90	Most errors are returned directly to the
91	.B substdio
92	caller, but an error of
93	.B error_intr
94	means that the operation should be tried again immediately.
95
96	There is a
97	.B SUBSTDIO_FDBUF
98	macro that can be used to statically initialize a
99	.B substdio
100	variable:
101
102	.EX
103	substdio s = SUBSTDIO_FDBUF(op,fd,buf,len);
104	.EE
105
106	.B substdio_fileno
107	returns the
108	descriptor for an initialized
109	.B substdio
110	variable.
111	.SH "SEE ALSO"
112	substdio_in(3),
113	substdio_out(3),
114	substdio_copy(3),
115	error(3)