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