Return to vread.2v CVS log

Up to [Research Unix] / researchv10dc / man / manb

Annotation of researchv10dc/man/manb/vread.2v, revision 1.1

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