sys/man/5/stat

   1 .TH STAT 5
   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 .IR fcall (2))
  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 (5)
  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 .PP
 131 The two time fields are measured in seconds since the epoch
 132 (Jan 1 00:00 1970 GMT).
 133 The
 134 .I mtime
 135 field reflects the time of the last change of content (except when later changed by
 136 .BR wstat ).
 137 For a plain file,
 138 .I mtime
 139 is the time of the most recent
 140 .BR create ,
 141 .B open
 142 with truncation,
 143 or
 144 .BR write ;
 145 for a directory it is the time of the most recent
 146 .BR remove ,
 147 .BR create ,
 148 or
 149 .B wstat
 150 of a file in the directory.
 151 Similarly, the
 152 .I atime
 153 field records the last
 154 .B read
 155 of the contents;
 156 also it is set whenever
 157 .I mtime
 158 is set.
 159 In addition, for a directory, it is set by
 160 an
 161 .BR attach ,
 162 .BR walk ,
 163 or
 164 .BR create ,
 165 all whether successful or not.
 166 .PP
 167 The
 168 .I muid
 169 field names the user whose actions most recently changed the
 170 .I mtime
 171 of the file.
 172 .PP
 173 The
 174 .I length
 175 records the number of bytes in the file.
 176 Directories and most files representing devices have a conventional
 177 length of 0.
 178 .PP
 179 The
 180 .B stat
 181 request requires no special permissions.
 182 .PP
 183 The
 184 .B wstat
 185 request can change some of the file status information.
 186 The
 187 .I name
 188 can be changed by anyone with write permission in the parent directory;
 189 it is an error to change the name to that of an existing file.
 190 The
 191 .I length
 192 can be changed (affecting the actual length of the file) by anyone with
 193 write permission on the file.
 194 It is an error to attempt to set the length of a directory to a non-zero value,
 195 and servers may decide to reject length changes for other reasons.
 196 The
 197 .I mode
 198 and
 199 .I mtime
 200 can be changed by the owner of the file or the group leader of the file's current
 201 group.
 202 The directory bit cannot be changed by a
 203 .BR wstat ;
 204 the other defined permission and mode bits can.
 205 The
 206 .I gid
 207 can be changed: by the owner if also a member of the new group; or
 208 by the group leader of the file's current group
 209 if also leader of the new group
 210 (see
 211 .IR intro (5)
 212 for more information about permissions and
 213 .IR users (6)
 214 for users and groups).
 215 None of the other data can be altered by a
 216 .B wstat
 217 and attempts to change them will trigger an error.
 218 In particular,
 219 it is illegal to attempt to change the owner of a file.
 220 (These conditions may be
 221 relaxed when establishing the initial state of a file server; see
 222 .IR fsconfig (8).)
 223 .PP
 224 Either all the changes in
 225 .B wstat
 226 request happen, or none of them does: if the request succeeds,
 227 all changes were made; if it fails, none were.
 228 .PP
 229 A
 230 .B wstat
 231 request can avoid modifying some properties of the file
 232 by providing explicit ``don't touch'' values in the
 233 .B stat
 234 data that is sent: zero-length strings for text values and
 235 the maximum unsigned value of appropriate size
 236 for integral values.
 237 As a special case, if
 238 .I all
 239 the elements of the directory entry in a
 240 .B Twstat
 241 message are ``don't touch'' values, the server may interpret it
 242 as a request to guarantee that the contents of the associated
 243 file are committed to stable storage before the
 244 .B Rwstat
 245 message is returned.
 246 (Consider the message to mean, ``make the state of the file
 247 exactly what it claims to be.'')
 248 .PP
 249 A
 250 .I read
 251 of a directory yields an integral number of directory entries in
 252 the machine independent encoding given above
 253 (see
 254 .IR read (5)).
 255 .PP
 256 Note that since the
 257 .B stat
 258 information is sent as a 9P variable-length datum, it is limited to a maximum of
 259 65535 bytes.
 260 .SH ENTRY POINTS
 261 .B Stat
 262 messages are generated by
 263 .I fstat
 264 and
 265 .IR stat .
 266 .PP
 267 .B Wstat
 268 messages are generated by
 269 .I fwstat
 270 and
 271 .IR wstat .
 272 .SH BUGS
 273 To make the contents of a directory, such as returned by
 274 .IR read (5),
 275 easy to parse, each
 276 directory entry begins with a size field.
 277 For consistency, the entries in
 278 .B Twstat
 279 and
 280 .B Rstat
 281 messages also contain
 282 their size, which means the size appears twice.
 283 For example, the
 284 .B Rstat
 285 message is formatted as
 286 .RI ``(4+1+2+2+ n )[4]
 287 .B Rstat
 288 .IR tag [2]
 289 .IR n [2]
 290 .RI ( n -2)[2]
 291 .IR type [2]
 292 .IR dev [4]...,''
 293 where
 294 .I n
 295 is the value returned by
 296 .BR convD2M .