1 .TH READ 9P 
2 .SH NAME
3 read, write \- transfer data from and to a file
4 .SH SYNOPSIS
5 .ta \w'\fLTwrite 'u
6 .IR size [4]
7 .B Tread
8 .IR tag [2]
9 .IR fid [4]
10 .IR offset [8]
11 .IR count [4]
12 .br
13 .IR size [4]
14 .B Rread
15 .IR tag [2]
16 .IR count [4]
17 .IR data [ count ]
18 .PP
19 .IR size [4]
20 .B Twrite
21 .IR tag [2]
22 .IR fid [4]
23 .IR offset [8]
24 .IR count [4]
25 .IR data [ count ]
26 .br
27 .IR size [4]
28 .B Rwrite
29 .IR tag [2]
30 .IR count [4]
31 .SH DESCRIPTION
32 The
33 .B read
34 request
35 asks for
36 .I count
37 bytes of data
38 from the file identified by 
39 .IR fid ,
40 which must be opened for reading,
41 starting 
42 .I offset
43 bytes after the beginning of the file.
44 The bytes are returned with the
45 .B read
46 reply message.
47 .PP
48 The
49 .I count
50 field in the reply indicates the number of bytes returned.
51 This may be less than the requested amount.
52 If the
53 .I offset
54 field is greater than or equal to the number of bytes in the file,
55 a count of zero will be returned.
56 .PP
57 For directories,
58 .B read
59 returns an integral number of
60 directory entries exactly as in
61 .B stat
62 (see
63 .IR stat (9P)),
64 one for each member of the directory.
65 The
66 .B read
67 request message must have
68 .B offset
69 equal to zero or the value of
70 .B offset
71 in the previous
72 .B read
73 on the directory, plus the number of bytes
74 returned in the previous
75 .BR read .
76 In other words, seeking other than to the beginning
77 is illegal in a directory.
78 .PP
79 The
80 .B write
81 request asks that
82 .I count
83 bytes of data be recorded in the file identified by
84 .IR fid ,
85 which must be opened for writing, starting
86 .I offset
87 bytes after the beginning of the file.
88 If the file is append-only,
89 the data will be placed at the end of the file regardless of
90 .IR offset .
91 Directories may not be written.
92 .PP
93 The 
94 .B write
95 reply records the number of bytes actually written.
96 It is usually an error
97 if this is not the same as requested.
98 .PP
99 Because 9P implementations may limit the size of individual
100 messages,
101 more than one message may be produced by a single
102 .I read
103 or
104 .I write
105 call.
106 The
107 .I iounit
108 field returned by
109 .IR open (9P),
110 if non-zero, reports the maximum size that is guaranteed
111 to be transferred atomically.
112 .SH ENTRY POINTS
113 .I Fsread
114 and
115 .I fswrite
116 (see
117 .MR 9pclient (3) )
118 generate the corresponding messages.
119 Because they take an offset parameter, the
120 .I fspread
121 and
122 .I fspwrite
123 calls correspond more directly to the 9P messages.
124 Although
125 .I fsseek
126 affects the offset, it does not generate a message.