[unix-history] / usr / src / old / man / vread.2v

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