stat.9p (6382B)
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 .