| <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> |
