.TH STAT 5 
.SH NAME
stat, wstat \- inquire or change file attributes
.SH SYNOPSIS
.ta \w'\fLTwstat 'u
.B
Tstat	
.IR tag [2]
.IR fid [2]
.br
.B
Rstat	
.IR tag [2]
.IR fid [2]
.IR stat [116]
.PP
.B
Twstat	
.IR tag [2]
.IR fid [2]
.IR stat [116]
.br
.B
Rwstat	
.IR tag [2]
.IR fid [2]
.SH DESCRIPTION
The
.B stat
transaction inquires about the file
identified by
.IR fid .
The reply will contain a 116-byte
.RB ( DIRLEN
in
.BR <libc.h> )
machine-independent
.I
directory entry
laid out as follows:
.TP 15n
.IR name [28]
file name
.PD 0
.TP
.IR uid [28]
owner name
.TP
.IR gid [28]
group name
.TP
.IR qid.path [4]
the file server's identification for the file
.TP
.IR qid.vers [4]
version number for given path
.TP
.IR mode [4]
permissions and flags
.TP
.IR atime [4]
last access time
.TP
.IR mtime [4]
last modification time
.TP
.IR length [8]
length of file in bytes
.TP
.IR type [2]
for kernel use
.TP
.IR dev [2]
for kernel use
.PD
.PP
Integers in this encoding are in little-endian order (least
significant byte first).
The
.I convM2D
and
.I convD2M
routines (see
.IR fcall (2))
convert between directory entries and C
.BR structs .
.PP
This encoding may be turned into
a machine dependent
.I Dir
structure (see
.IR stat (2))
using routines defined in
.IR fcall (2).
.PP
The
.I mode
contains permission bits as described in
.IR intro (5)
and the following:
.B 0x80000000
(this file is a directory),
.B 0x40000000
(append only),
.B 0x20000000
(exclusive use).
Writes to append-only files always place their data at the
end of the file; the
.I offset
in the
.B read
or
.B write
message is ignored.
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.
.PP
The two time fields are measured in seconds since the epoch
(Jan 1 00:00 1970 local time).
The
.I mtime
field reflects the time of the last change of content.
For a plain file,
.I mtime
is the time of the most recent
.BR create ,
.B open
with truncation,
or
.BR write ;
for a directory it is the time of the most recent
.BR remove ,
.BR create ,
or
.B wstat
of a file in the directory.
Similarly, the
.I atime
field records the last
.B read
of the contents;
also it is set whenever
.I mtime
is set.
In addition, for a directory, it is set by
an
.BR attach ,
.BR walk ,
or
.BR create ,
all whether successful or not.
.PP
The
.I length
records the number of bytes in the file.
Directories and most files representing devices have a conventional
length of 0.
.PP
The
.B stat
request requires no special permissions.
.PP
The
.B wstat
request can change some of the file status information.
The
.I 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
.I mode
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
.BR wstat ;
the other defined permission and mode bits can.
The
.I 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
.IR intro (5)
for more information about permissions and
.IR users (6)
for users and groups).
None of the other data can be altered by a
.BR wstat .
In particular, there is no way to change the owner of a file.
.PP
A
.I read
of a directory yields an integral number of directory entries in
the machine independent encoding given above
(see
.IR read (5)).
.SH ENTRY POINTS
.B Stat
messages are generated by
.I fstat
and
.I stat.
.PP
.B Wstat
messages are generated by
.I fwstat
and
.I wstat.