stat

STAT(9P)                                                              STAT(9P)



NAME
       stat, wstat - inquire or change file attributes

SYNOPSIS
       size[4] Tstat tag[2] fid[4]
       size[4] Rstat tag[2] stat[n]

       size[4] Twstat tag[2] fid[4] stat[n]
       size[4] Rwstat tag[2]

DESCRIPTION
       The stat transaction inquires about the file identified by fid.  The
       reply will contain a machine-independent directory entry, stat, laid
       out as follows:

       size[2]
              total byte count of the following data

       type[2]
              for kernel use

       dev[4] for kernel use

       qid.type[1]
              the type of the file (directory, etc.), represented as a bit
              vector corresponding to the high 8 bits of the file's mode word.

       qid.vers[4]
              version number for given path

       qid.path[8]
              the file server's unique identification for the file

       mode[4]
              permissions and flags

       atime[4]
              last access time

       mtime[4]
              last modification time

       length[8]
              length of file in bytes

       name[ s ]
              file name; must be / if the file is the root directory of the
              server

       uid[ s ]
              owner name

       gid[ s ]
              group name

       muid[ s ]
              name of the user who last modified the file

       Integers in this encoding are in little-endian order (least significant
       byte first).  The convM2D and convD2M routines (see fcall(3)) convert
       between directory entries and a C structure called a Dir.

       The mode contains permission bits as described in intro(9P) and the
       following: 0x80000000 (DMDIR, this file is a directory), 0x40000000
       (DMAPPEND, append only), 0x20000000 (DMEXCL, exclusive use), 0x04000000
       (DMTMP, temporary); these are echoed in Qid.type.  Writes to append-
       only files always place their data at the end of the file; the offset
       in the write message is ignored, as is the OTRUNC 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 fossil(4)).

       The two time fields are measured in seconds since the epoch (Jan 1
       00:00 1970 GMT).  The mtime field reflects the time of the last change
       of content (except when later changed by wstat).  For a plain file,
       mtime is the time of the most recent create, open with truncation, or
       write; for a directory it is the time of the most recent remove,
       create, or wstat of a file in the directory.  Similarly, the atime
       field records the last read of the contents; also it is set whenever
       mtime is set.  In addition, for a directory, it is set by an attach,
       walk, or create, all whether successful or not.

       The muid field names the user whose actions most recently changed the
       mtime of the file.

       The length records the number of bytes in the file.  Directories and
       most files representing devices have a conventional length of 0.

       The stat request requires no special permissions.

       The wstat request can change some of the file status information.  The
       name 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 length 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
       mode and mtime 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 wstat; the other defined permission and mode bits can.
       The gid 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 intro(9P) for more information about permissions,
       users, and groups).  None of the other data can be altered by a wstat
       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 fsconfig(8).)

       Either all the changes in wstat request happen, or none of them does:
       if the request succeeds, all changes were made; if it fails, none were.

       A wstat request can avoid modifying some properties of the file by
       providing explicit ``don't touch'' values in the stat 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
       all the elements of the directory entry in a Twstat 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 Rwstat message is returned.  (Consider the message
       to mean, ``make the state of the file exactly what it claims to be.'')

       A read of a directory yields an integral number of directory entries in
       the machine independent encoding given above (see read(9P)).

       Note that since the stat information is sent as a 9P variable-length
       datum, it is limited to a maximum of 65535 bytes.

ENTRY POINTS
       Stat messages are generated by fsdirfstat and fsdirstat (see
       9pclient(3)).

       Wstat messages are generated by fsdirfwstat and fsdirwstat.

BUGS
       To make the contents of a directory, such as returned by read(9P), easy
       to parse, each directory entry begins with a size field.  For
       consistency, the entries in Twstat and Rstat messages also contain
       their size, which means the size appears twice.  For example, the Rstat
       message is formatted as ``(4+1+2+2+n)[4] Rstat tag[2] n[2] (n-2)[2]
       type[2] dev[4]...,'' where n is the value returned by convD2M.



                                                                      STAT(9P)