10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
93 lines
1.8 KiB
Groff
93 lines
1.8 KiB
Groff
.TH READ 3
|
|
.SH NAME
|
|
read, readn, write, pread, pwrite \- read or write file
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.B
|
|
long read(int fd, void *buf, long nbytes)
|
|
.PP
|
|
.B
|
|
long readn(int fd, void *buf, long nbytes)
|
|
.PP
|
|
.B
|
|
long write(int fd, void *buf, long nbytes)
|
|
.PP
|
|
.B
|
|
long pread(int fd, void *buf, long nbytes, vlong offset)
|
|
.PP
|
|
.B
|
|
long pwrite(int fd, void *buf, long nbytes, vlong offset)
|
|
.SH DESCRIPTION
|
|
.I Read
|
|
reads
|
|
.I nbytes
|
|
bytes of data
|
|
from the offset in the file associated with
|
|
.I fd
|
|
into memory at
|
|
.IR buf .
|
|
The 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
|
|
.I Readn
|
|
is just like read, but does successive
|
|
.I read
|
|
calls until
|
|
.I nbytes
|
|
have been read, or a read system call
|
|
returns a non-positive count.
|
|
.PP
|
|
.I 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 characters actually written is returned.
|
|
It should be regarded as an error
|
|
if this is not the same as requested.
|
|
.PP
|
|
.I Pread
|
|
and
|
|
.I Pwrite
|
|
equivalent to a
|
|
.MR seek 3
|
|
to
|
|
.I offset
|
|
followed by a
|
|
.I read
|
|
or
|
|
.IR write .
|
|
By combining the operations in a single atomic call, they more closely
|
|
match the 9P protocol
|
|
(see
|
|
.IR intro (9p))
|
|
and, more important,
|
|
permit multiprocess programs to execute multiple concurrent
|
|
read and write operations on the same file descriptor
|
|
without interference.
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/readn.c
|
|
.SH SEE ALSO
|
|
.MR intro 3 ,
|
|
.IR open (3),
|
|
.MR dup 3 ,
|
|
.MR pipe 3
|
|
.SH DIAGNOSTICS
|
|
These functions set
|
|
.IR errstr .
|