[unix-history] / usr / man / man2 / vread.2

.UC
.TH VREAD 2
.SH NAME
vread \- read virtually
.SH SYNOPSIS
\fBvread(fildes, buffer, nbytes)\fR
.br
\fBchar *buffer;\fR
.SH DESCRIPTION
A file descriptor is a word returned from a successful
.I open,
.I creat,
.I dup
or
.I pipe
call.
.I Buffer
is the location of
.I nbytes
contiguous bytes into which the input will be placed.
It is not guaranteed that all
.I nbytes
will be read (see
.I read
(2)).
In particular, if the returned value is 0, then end-of-file has been reached.
.PP
Unlike
.I read
(2),
.I vread
does not necessarily or immediately fetch the data requested from
.I fildes,
but merely insures that the data will be fetched from the file descriptor
.I "sometime before"
the first reference to the data, at the system's discretion.
Thus
.I vread
allows the system, among other possibilities,
to choose to read data on demand,
with whatever granularity is allowed by the memory management hardware,
or to just read it in immediately as with
.I read.
A companion
.I vwrite
(2) call may be used with
.I vread
to provide an efficient mechanism for updating large files.
The behavior of
.I vread
if other processes are writing to
.I fildes
is not defined.
.PP
Both the address of
.I buffer
and the current offset in
.I fildes
(as told by
.I tell
(2)) must be aligned to a multiple of VALSIZ (defined in ``<valign.h>'').
The library routine
.I valloc
(3) allocates properly aligned blocks from the free list.
.PP
Note for non-virtual systems: the
.I vread
system call can be simulated (exactly, if less efficiently) by
.I read.
If the unit on which a
.I vread
is done is not capable of supporting efficient demand initialization
(e.g. a terminal or a pipe), then the system may choose to treat a call to
.I vread
as if it were a call to
.I read
at its discretion.
.SH SEE ALSO
read(2), write(2), vwrite (2), valloc(3)
.SH DIAGNOSTICS
A 0 is returned at end-of-file.  If the read was otherwise unsuccessful,
a -1 is returned.  Physical I/O errors, non-aligned or bad buffer addresses,
preposterous
.I nbytes,
file descriptor not that of an input file, and file offset not properly
aligned can all generate errors.
.SH BUGS
You can't
.I close
a file descriptor which you have
.I vread
from while there are still pages in the file which haven't been fetched by the
system into your address space.  In no case can a file descriptor which had
such pages at the point of a
.I vfork
be closed during the
.I vfork.
.PP
The system refuses to truncate a file to which any process has a pending
.I vread.
.PP
There is no primitive inverting
.I vread
to release the binding
.I vread
sets up so that the file may be closed.
This can be only be done, clumsily, by reading another (plain) file onto the
buffer area, or pulling the break back with
.IR break (2)
to completely release the pages.
Commit	Line	Data
d477989c BJ	1	.UC
	2	.TH VREAD 2
	3	.SH NAME
	4	vread \- read virtually
	5	.SH SYNOPSIS
	6	\fBvread(fildes, buffer, nbytes)\fR
	7	.br
	8	\fBchar *buffer;\fR
	9	.SH DESCRIPTION
	10	A file descriptor is a word returned from a successful
	11	.I open,
	12	.I creat,
	13	.I dup
	14	or
	15	.I pipe
	16	call.
	17	.I Buffer
	18	is the location of
	19	.I nbytes
	20	contiguous bytes into which the input will be placed.
	21	It is not guaranteed that all
	22	.I nbytes
	23	will be read (see
	24	.I read
	25	(2)).
	26	In particular, if the returned value is 0, then end-of-file has been reached.
	27	.PP
	28	Unlike
	29	.I read
	30	(2),
	31	.I vread
	32	does not necessarily or immediately fetch the data requested from
	33	.I fildes,
	34	but merely insures that the data will be fetched from the file descriptor
	35	.I "sometime before"
	36	the first reference to the data, at the system's discretion.
	37	Thus
	38	.I vread
	39	allows the system, among other possibilities,
	40	to choose to read data on demand,
	41	with whatever granularity is allowed by the memory management hardware,
	42	or to just read it in immediately as with
	43	.I read.
	44	A companion
	45	.I vwrite
	46	(2) call may be used with
	47	.I vread
	48	to provide an efficient mechanism for updating large files.
	49	The behavior of
	50	.I vread
	51	if other processes are writing to
	52	.I fildes
	53	is not defined.
	54	.PP
	55	Both the address of
	56	.I buffer
	57	and the current offset in
	58	.I fildes
	59	(as told by
	60	.I tell
	61	(2)) must be aligned to a multiple of VALSIZ (defined in ``<valign.h>'').
	62	The library routine
	63	.I valloc
	64	(3) allocates properly aligned blocks from the free list.
65	.PP
66	Note for non-virtual systems: the
67	.I vread
68	system call can be simulated (exactly, if less efficiently) by
69	.I read.
70	If the unit on which a
71	.I vread
72	is done is not capable of supporting efficient demand initialization
73	(e.g. a terminal or a pipe), then the system may choose to treat a call to
74	.I vread
75	as if it were a call to
76	.I read
77	at its discretion.
78	.SH SEE ALSO
79	read(2), write(2), vwrite (2), valloc(3)
80	.SH DIAGNOSTICS
81	A 0 is returned at end-of-file. If the read was otherwise unsuccessful,
82	a -1 is returned. Physical I/O errors, non-aligned or bad buffer addresses,
83	preposterous
84	.I nbytes,
85	file descriptor not that of an input file, and file offset not properly
86	aligned can all generate errors.
87	.SH BUGS
88	You can't
89	.I close
90	a file descriptor which you have
91	.I vread
92	from while there are still pages in the file which haven't been fetched by the
93	system into your address space. In no case can a file descriptor which had
94	such pages at the point of a
95	.I vfork
96	be closed during the
97	.I vfork.
98	.PP
99	The system refuses to truncate a file to which any process has a pending
100	.I vread.
101	.PP
102	There is no primitive inverting
103	.I vread
104	to release the binding
105	.I vread
106	sets up so that the file may be closed.
107	This can be only be done, clumsily, by reading another (plain) file onto the
108	buffer area, or pulling the break back with
109	.IR break (2)
110	to completely release the pages.