1 .TH READ 3
2 .SH NAME
3 read, readn, write, pread, pwrite \- read or write file
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .B
10 long read(int fd, void *buf, long nbytes)
11 .PP
12 .B
13 long readn(int fd, void *buf, long nbytes)
14 .PP
15 .B
16 long write(int fd, void *buf, long nbytes)
17 .PP
18 .B
19 long pread(int fd, void *buf, long nbytes, vlong offset)
20 .PP
21 .B
22 long pwrite(int fd, void *buf, long nbytes, vlong offset)
23 .SH DESCRIPTION
24 .I Read
25 reads
26 .I nbytes
27 bytes of data
28 from the offset in the file associated with
29 .I fd
30 into memory at
31 .IR buf .
32 The offset is advanced by the number of bytes read.
33 It is not guaranteed
34 that all
35 .I nbytes
36 bytes will be read; for example
37 if the file refers to the console, at most one line
38 will be returned.
39 In any event the number of bytes read is returned.
40 A return value of
41 0 is conventionally interpreted as end of file.
42 .PP
43 .I Readn
44 is just like read, but does successive
45 .I read
46 calls until
47 .I nbytes
48 have been read, or a read system call
49 returns a non-positive count.
50 .PP
51 .I Write
52 writes
53 .I nbytes
54 bytes of data starting at
55 .I buf
56 to the file associated with
57 .I fd
58 at the file offset.
59 The offset is advanced by the number of bytes written.
60 The number of characters actually written is returned.
61 It should be regarded as an error
62 if this is not the same as requested.
63 .PP
64 .I Pread
65 and
66 .I Pwrite
67 equivalent to a
68 .MR seek (3)
69 to
70 .I offset
71 followed by a
72 .I read
73 or
74 .IR write .
75 By combining the operations in a single atomic call, they more closely
76 match the 9P protocol
77 (see
78 .IR intro (9p))
79 and, more important,
80 permit multiprocess programs to execute multiple concurrent
81 read and write operations on the same file descriptor
82 without interference.
83 .SH SOURCE
84 .B \*9/src/lib9/readn.c
85 .SH SEE ALSO
86 .MR intro (3) ,
87 .IR open (3), 
88 .MR dup (3) ,
89 .MR pipe (3)
90 .SH DIAGNOSTICS
91 These functions set
92 .IR errstr .