Return to vread.2v CVS log

Up to [CSRG BSD Unix] / 43BSDReno / old / man

Annotation of 43BSDReno/old/man/vread.2v, revision 1.1.1.1

1.1       root        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) 5/9/85
                      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.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.