1 .TH STAT 9P 
2 .SH NAME
3 stat, wstat \- inquire or change file attributes
4 .SH SYNOPSIS
5 .ta \w'\fLTwstat 'u
6 .IR size [4]
7 .B Tstat
8 .IR tag [2]
9 .IR fid [4]
10 .br
11 .IR size [4]
12 .B Rstat
13 .IR tag [2]
14 .IR stat [ n ]
15 .PP
16 .IR size [4]
17 .B Twstat
18 .IR tag [2]
19 .IR fid [4]
20 .IR stat [ n ]
21 .br
22 .IR size [4]
23 .B Rwstat
24 .IR tag [2]
25 .SH DESCRIPTION
26 The
27 .B stat
28 transaction inquires about the file
29 identified by
30 .IR fid .
31 The reply will contain a
32 machine-independent
33 .I directory
34 .IR entry ,
35 .IR stat ,
36 laid out as follows:
37 .TP
38 .I size\f1[2]\fP
39 total byte count of the following data
40 .TP
41 .I type\f1[2]\fP
42 for kernel use
43 .TP
44 .I dev\f1[4]\fP
45 for kernel use
46 .TP
47 .I qid.type\f1[1]\fP
48 the type of the file (directory, etc.), represented as a bit vector
49 corresponding to the high 8 bits of the file's mode word.
50 .TP
51 .I qid.vers\f1[4]\fP
52 version number for given path
53 .TP
54 .I qid.path\f1[8]\fP
55 the file server's unique identification for the file
56 .TP
57 .I mode\f1[4]\fP
58 permissions and flags
59 .TP
60 .I atime\f1[4]\fP
61 last access time
62 .TP
63 .I mtime\f1[4]\fP
64 last modification time
65 .TP
66 .I length\f1[8]\fP
67 length of file in bytes
68 .TP
69 .I name\f1[ s ]\fP
70 file name; must be
71 .B /
72 if the file is the root directory of the server
73 .TP
74 .I uid\f1[ s ]\fP
75 owner name
76 .TP
77 .I gid\f1[ s ]\fP
78 group name
79 .TP
80 .I muid\f1[ s ]\fP
81 name of the user who last modified the file
82 .PD
83 .PP
84 Integers in this encoding are in little-endian order (least
85 significant byte first).
86 The
87 .I convM2D
88 and
89 .I convD2M
90 routines (see
91 .MR fcall (3) )
92 convert between directory entries and a C structure called a
93 .BR Dir .
94 .PP
95 The
96 .I mode
97 contains permission bits as described in
98 .IR intro (9P)
99 and the following:
100 .B 0x80000000
101 .RB ( DMDIR ,
102 this file is a directory),
103 .B 0x40000000
104 .RB ( DMAPPEND ,
105 append only),
106 .B 0x20000000
107 .RB ( DMEXCL ,
108 exclusive use),
109 .B 0x04000000
110 .RB ( DMTMP ,
111 temporary);
112 these are echoed in
113 .BR Qid.type .
114 Writes to append-only files always place their data at the
115 end of the file; the
116 .I offset
117 in the
118 .B write
119 message is ignored, as is the
120 .B OTRUNC
121 bit in an open.
122 Exclusive use files may be open for I/O by only one fid at a time
123 across all clients of the server.  If a second open is attempted,
124 it draws an error.  Servers may implement a timeout on the lock
125 on an exclusive use file: if the fid holding the file open has
126 been unused for an extended period (of order at least minutes),
127 it is reasonable to break the lock and deny the initial fid
128 further I/O.
129 Temporary files are not included in nightly archives
130 (see Plan 9's \fIfossil\fR(4)).
131 .PP
132 The two time fields are measured in seconds since the epoch
133 (Jan 1 00:00 1970 GMT).
134 The
135 .I mtime
136 field reflects the time of the last change of content (except when later changed by
137 .BR wstat ).
138 For a plain file,
139 .I mtime
140 is the time of the most recent
141 .BR create ,
142 .B open
143 with truncation,
144 or
145 .BR write ;
146 for a directory it is the time of the most recent
147 .BR remove ,
148 .BR create ,
149 or
150 .B wstat
151 of a file in the directory.
152 Similarly, the
153 .I atime
154 field records the last
155 .B read
156 of the contents;
157 also it is set whenever
158 .I mtime
159 is set.
160 In addition, for a directory, it is set by
161 an
162 .BR attach ,
163 .BR walk ,
164 or
165 .BR create ,
166 all whether successful or not.
167 .PP
168 The
169 .I muid
170 field names the user whose actions most recently changed the
171 .I mtime
172 of the file.
173 .PP
174 The
175 .I length
176 records the number of bytes in the file.
177 Directories and most files representing devices have a conventional
178 length of 0.
179 .PP
180 The
181 .B stat
182 request requires no special permissions.
183 .PP
184 The
185 .B wstat
186 request can change some of the file status information.
187 The
188 .I name
189 can be changed by anyone with write permission in the parent directory;
190 it is an error to change the name to that of an existing file.
191 The
192 .I length
193 can be changed (affecting the actual length of the file) by anyone with
194 write permission on the file.
195 It is an error to attempt to set the length of a directory to a non-zero value,
196 and servers may decide to reject length changes for other reasons.
197 The
198 .I mode
199 and
200 .I mtime
201 can be changed by the owner of the file or the group leader of the file's current
202 group.
203 The directory bit cannot be changed by a
204 .BR wstat ;
205 the other defined permission and mode bits can.
206 The
207 .I gid
208 can be changed: by the owner if also a member of the new group; or
209 by the group leader of the file's current group
210 if also leader of the new group
211 (see
212 .IR intro (9P)
213 for more information about permissions, users, and groups).
214 None of the other data can be altered by a
215 .B wstat
216 and attempts to change them will trigger an error.
217 In particular,
218 it is illegal to attempt to change the owner of a file.
219 (These conditions may be
220 relaxed when establishing the initial state of a file server; see
221 Plan 9's \fIfsconfig\fR(8).)
222 .PP
223 Either all the changes in
224 .B wstat
225 request happen, or none of them does: if the request succeeds,
226 all changes were made; if it fails, none were.
227 .PP
228 A
229 .B wstat
230 request can avoid modifying some properties of the file
231 by providing explicit ``don't touch'' values in the
232 .B stat
233 data that is sent: zero-length strings for text values and
234 the maximum unsigned value of appropriate size
235 for integral values.
236 As a special case, if
237 .I all
238 the elements of the directory entry in a
239 .B Twstat
240 message are ``don't touch'' values, the server may interpret it
241 as a request to guarantee that the contents of the associated
242 file are committed to stable storage before the
243 .B Rwstat
244 message is returned.
245 (Consider the message to mean, ``make the state of the file
246 exactly what it claims to be.'')
247 .PP
248 A
249 .I read
250 of a directory yields an integral number of directory entries in
251 the machine independent encoding given above
252 (see
253 .IR read (9P)).
254 .PP
255 Note that since the
256 .B stat
257 information is sent as a 9P variable-length datum, it is limited to a maximum of
258 65535 bytes.
259 .SH ENTRY POINTS
260 .B Stat
261 messages are generated by
262 .I fsdirfstat
263 and
264 .IR fsdirstat
265 (see
266 .MR 9pclient (3) ).
267 .PP
268 .B Wstat
269 messages are generated by
270 .I fsdirfwstat
271 and
272 .IR fsdirwstat .
273 .SH BUGS
274 To make the contents of a directory, such as returned by
275 .IR read (9P),
276 easy to parse, each
277 directory entry begins with a size field.
278 For consistency, the entries in
279 .B Twstat
280 and
281 .B Rstat
282 messages also contain
283 their size, which means the size appears twice.
284 For example, the
285 .B Rstat
286 message is formatted as
287 .RI ``(4+1+2+2+ n )[4]
288 .B Rstat
289 .IR tag [2]
290 .IR n [2]
291 .RI ( n -2)[2]
292 .IR type [2]
293 .IR dev [4]...,''
294 where 
295 .I n
296 is the value returned by
297 .BR convD2M .