.TH SYS-READ 2.SH NAMEread, write, pread, pwrite, stream \- read or write file.SH SYNOPSIS.EXinclude "sys.m";sys := load Sys Sys->PATH;read: fn(fd: ref FD, buf: array of byte, nbytes: int): int;readn: fn(fd: ref FD, buf: array of byte, nbytes: int): int;write: fn(fd: ref FD, buf: array of byte, nbytes: int): int;pread: fn(fd: ref FD, buf: array of byte, nbytes: int, offset: big): int;pwrite: fn(fd: ref FD, buf: array of byte, nbytes: int, offset: big): int;stream: fn(src, dst: ref FD, bufsiz: int): int;.EE.SH DESCRIPTION.B Readreads.I nbytesbytes of data from the offset in the fileassociated with.I fdinto memory at.IR buf .The file offset is advanced by the number of bytes read.It is not guaranteedthat all.I nbytesbytes will be read; for exampleif the file refers to the console, at most one linewill be returned.In any event the number of bytes read is returned.A return value of0 is conventionally interpreted as end of file..PP.B Readncontinues to.B readfrom.I fdsequentially into.IR buf ,until.I nbyteshave been read, or.B readreturns a non-positive count..PP.B Writewrites.I nbytesbytes of data starting at.I bufto the file associated with.I fdat the file offset.The offset is advanced by the number of bytes written.The number of bytes actually written is returned.It should be regarded as an errorif this is not the same as requested..PP.B Preadand.B pwritetake an explicit file.I offsetas a parameter, leaving.IR fd 'scurrent offset untouched;they are otherwise identical in behaviour to.B readand.BR write .They are particulary useful when several processes must access the same.I fdconcurrently and it is inconvenient or undesirable to synchronise their activityto avoid interference..PP.B Streamcontinually reads data from.IR src ,using a buffer of.I bufsizbytes, and writes the data to.IR dst .It copies datauntil a read fails (returningzero bytes or an error) or a write fails..B Streamreturns the number of bytes actually copied.The implementation may be more efficient than a.BR read / writeloop in the application, but is otherwiseequivalent to calling.B readand.B writedirectly..SH SEE ALSO.IR bufio (2),.IR sys-intro (2),.IR sys-dup (2),.IR sys-open (2),.IR read (5)
.TH SYS-READ 2
.SH NAME
read, write, pread, pwrite, stream \- read or write file
.SH SYNOPSIS
.EX
include "sys.m";
sys := load Sys Sys->PATH;
read: fn(fd: ref FD, buf: array of byte, nbytes: int): int;
readn: fn(fd: ref FD, buf: array of byte, nbytes: int): int;
write: fn(fd: ref FD, buf: array of byte, nbytes: int): int;
pread: fn(fd: ref FD, buf: array of byte, nbytes: int,
offset: big): int;
pwrite: fn(fd: ref FD, buf: array of byte, nbytes: int,
offset: big): int;
stream: fn(src, dst: ref FD, bufsiz: int): int;
.EE
.SH DESCRIPTION
.B Read
reads
.I nbytes
bytes of data from the offset in the file
associated with
.I fd
into memory at
.IR buf .
The file offset is advanced by the number of bytes read.
It is not guaranteed
that all
.I nbytes
bytes will be read; for example
if the file refers to the console, at most one line
will be returned.
In any event the number of bytes read is returned.
A return value of
0 is conventionally interpreted as end of file.
.PP
.B Readn
continues to
.B read
from
.I fd
sequentially into
.IR buf ,
until
.I nbytes
have been read, or
.B read
returns a non-positive count.
.PP
.B Write
writes
.I nbytes
bytes of data starting at
.I buf
to the file associated with
.I fd
at the file offset.
The offset is advanced by the number of bytes written.
The number of bytes actually written is returned.
It should be regarded as an error
if this is not the same as requested.
.PP
.B Pread
and
.B pwrite
take an explicit file
.I offset
as a parameter, leaving
.IR fd 's
current offset untouched;
they are otherwise identical in behaviour to
.B read
and
.BR write .
They are particulary useful when several processes must access the same
.I fd
concurrently and it is inconvenient or undesirable to synchronise their activity
to avoid interference.
.PP
.B Stream
continually reads data from
.IR src ,
using a buffer of
.I bufsiz
bytes, and writes the data to
.IR dst .
It copies data
until a read fails (returning
zero bytes or an error) or a write fails.
.B Stream
returns the number of bytes actually copied.
The implementation may be more efficient than a
.BR read / write
loop in the application, but is otherwise
equivalent to calling
.B read
and
.B write
directly.
.SH SEE ALSO
.IR bufio (2),
.IR sys-intro (2),
.IR sys-dup (2),
.IR sys-open (2),
.IR read (5)