1
0

stat 6.1 KB

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