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     ! 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.