[unix-history] / usr / src / lib / libc / stdio / funopen.3

.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)funopen.3	5.1 (Berkeley) %G%
.\"
.TH FUNOPEN 3 ""
.UC 7
.SH NAME
funopen, fropen, fwopen \- open a stream
.SH SYNOPSIS
.nf
.ft B
#include <stdio.h>

FILE *
funopen(void *cookie, int (*readfn)(void *, char *, int),
.RS
.\" old man macros need the reset of bold mode
.ft B
int (*writefn)(void *, char *, int),
fpos_t (*seekfn)(void *, off_t, int), int (*closefn)(void *));
.RE
.\" old man macros need the reset of bold mode
.ft B

FILE *
fropen(void *cookie, int (*readfn)(void *, char *, int));

FILE *
fwopen(void *cookie, int (*writefn)(void *, char *, int));
.ft R
.fi
.SH DESCRIPTION
.I Funopen
associates a stream with up to four ``I/O functions''.
Either 
.I readfn
or
.I writefn
must be specified;
the others can be given as an appropriately-typed NULL pointer.
These I/O functions will be used to read, write, seek and
close the new stream.
.PP
In general, omitting a function means that any attempt to perform the
associated operation on the resulting stream will fail.
If the close function is omitted, closing the stream will flush 
any buffered output and then succeed.
.PP
The calling conventions of
.IR readfn ,
.IR writefn ,
.I seekfn 
and
.I closefn
must match those, respectively, of
.IR read (2),
.IR write (2),
.IR seek (2),
and
.IR close (2)
with the single exception that they are passed the
.I cookie
argument specified to 
.I funopen
in place of the traditional file descriptor argument.
.PP
Read and write I/O functions are allowed to change the underlying buffer
on fully buffered or line buffered streams by calling
.IR setvbuf .
They are also not required to completely fill or empty the buffer.
They are not, however, allowed to change streams from unbuffered to buffered
or to change the state of the line buffering flag.
They must also be prepared to have read or write calls occur on buffers other
than the one most recently specified.
.PP
All user I/O functions can report an error by returning \-1.
Additionally, all of the functions should set the external variable
.I errno
appropriately if an error occurs.
.PP
An error on 
.I closefn
does not keep the stream open.
.PP
As a convenience, the include file ``<stdio.h>'' defines the macros
.I fropen
and
.I fwopen
as calls to
.I funopen
with only a read or write function specified.
.SH "SEE ALSO"
fcntl(2), open(2), fclose(3), fopen(3), fseek(3), setbuf(3)
.SH "RETURN VALUES"
Upon successful completion, 
.I funopen
returns a FILE pointer.
Otherwise, NULL is returned and the global variable
.I errno
is set to indicate the error.
.SH ERRORS
.TP 15
[EINVAL]
.I Funopen
was called without either a read or write function.
.I Funopen
may also fail and set errno for any of the errors
specified for the routine
.IR malloc (3).
.SH BUGS
.I Funopen
may not be portable to systems other than BSD.
Commit	Line	Data
75964a78 KB	1	.\" Copyright (c) 1990 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" Chris Torek.
	6	.\"
	7	.\" %sccs.include.redist.man%
	8	.\"
	9	.\" @(#)funopen.3 5.1 (Berkeley) %G%
	10	.\"
	11	.TH FUNOPEN 3 ""
	12	.UC 7
	13	.SH NAME
	14	funopen, fropen, fwopen \- open a stream
	15	.SH SYNOPSIS
	16	.nf
	17	.ft B
	18	#include <stdio.h>
	19
	20	FILE *
	21	funopen(void cookie, int (readfn)(void , char , int),
	22	.RS
	23	.\" old man macros need the reset of bold mode
	24	.ft B
	25	int (writefn)(void , char *, int),
	26	fpos_t (seekfn)(void , off_t, int), int (closefn)(void ));
	27	.RE
	28	.\" old man macros need the reset of bold mode
	29	.ft B
	30
	31	FILE *
	32	fropen(void cookie, int (readfn)(void , char , int));
	33
	34	FILE *
	35	fwopen(void cookie, int (writefn)(void , char , int));
	36	.ft R
	37	.fi
	38	.SH DESCRIPTION
	39	.I Funopen
	40	associates a stream with up to four ``I/O functions''.
	41	Either
	42	.I readfn
	43	or
	44	.I writefn
	45	must be specified;
	46	the others can be given as an appropriately-typed NULL pointer.
	47	These I/O functions will be used to read, write, seek and
	48	close the new stream.
	49	.PP
	50	In general, omitting a function means that any attempt to perform the
	51	associated operation on the resulting stream will fail.
	52	If the close function is omitted, closing the stream will flush
	53	any buffered output and then succeed.
	54	.PP
	55	The calling conventions of
	56	.IR readfn ,
	57	.IR writefn ,
	58	.I seekfn
	59	and
	60	.I closefn
	61	must match those, respectively, of
	62	.IR read (2),
	63	.IR write (2),
	64	.IR seek (2),
65	and
66	.IR close (2)
67	with the single exception that they are passed the
68	.I cookie
69	argument specified to
70	.I funopen
71	in place of the traditional file descriptor argument.
72	.PP
73	Read and write I/O functions are allowed to change the underlying buffer
74	on fully buffered or line buffered streams by calling
75	.IR setvbuf .
76	They are also not required to completely fill or empty the buffer.
77	They are not, however, allowed to change streams from unbuffered to buffered
78	or to change the state of the line buffering flag.
79	They must also be prepared to have read or write calls occur on buffers other
80	than the one most recently specified.
81	.PP
82	All user I/O functions can report an error by returning \-1.
83	Additionally, all of the functions should set the external variable
84	.I errno
85	appropriately if an error occurs.
86	.PP
87	An error on
88	.I closefn
89	does not keep the stream open.
90	.PP
91	As a convenience, the include file ``<stdio.h>'' defines the macros
92	.I fropen
93	and
94	.I fwopen
95	as calls to
96	.I funopen
97	with only a read or write function specified.
98	.SH "SEE ALSO"
99	fcntl(2), open(2), fclose(3), fopen(3), fseek(3), setbuf(3)
100	.SH "RETURN VALUES"
101	Upon successful completion,
102	.I funopen
103	returns a FILE pointer.
104	Otherwise, NULL is returned and the global variable
105	.I errno
106	is set to indicate the error.
107	.SH ERRORS
108	.TP 15
109	[EINVAL]
110	.I Funopen
111	was called without either a read or write function.
112	.I Funopen
113	may also fail and set errno for any of the errors
114	specified for the routine
115	.IR malloc (3).
116	.SH BUGS
117	.I Funopen
118	may not be portable to systems other than BSD.