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