STAT(5) STAT(5)
NAME
stat, wstat - inquire or change file attributes
SYNOPSIS
Tstat tag[2] fid[2]
Rstat tag[2] fid[2] stat[116]
Twstat tag[2] fid[2] stat[116]
Rwstat tag[2] fid[2]
DESCRIPTION
The stat transaction inquires about the file identified by
fid. The reply will contain a 116-byte (DIRLEN in <libc.h>)
machine-independent directory entry laid out as follows:
file name
owner name
group name
the file server's identification for the file
version number for given path
permissions and flags
last access time
last modification time
length of file in bytes
for kernel use
for kernel use
Integers in this encoding are in little-endian order (least
significant byte first). The convM2D and convD2M routines
(see fcall(2)) convert between directory entries and C
structs.
This encoding may be turned into a machine dependent Dir
structure (see stat(2)) using routines defined in fcall(2).
The mode contains permission bits as described in intro(5)
and the following: 0x80000000 (this file is a directory),
0x40000000 (append only), 0x20000000 (exclusive use).
Writes to append-only files always place their data at the
end of the file; the offset in the read or 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 reason-
able to break the lock and deny the initial fid further I/O.
The two time fields are measured in seconds since the epoch
(Jan 1 00:00 1970 local time). The mtime field reflects the
Page 1 Plan 9 (printed 12/26/24)
STAT(5) STAT(5)
time of the last change of content. 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. Simi-
larly, the atime field records the last read of the con-
tents; 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 length records the number of bytes in the file. Direc-
tories and most files representing devices have a conven-
tional length of 0.
The stat request requires no special permissions.
The wstat request can change some of the file status infor-
mation. The name can be changed by anyone with write per-
mission in the parent directory; it is an error to change
the name to that of an existing file. The 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 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(5) for more
information about permissions and users(6) for users and
groups). None of the other data can be altered by a wstat.
In particular, there is no way to change the owner of a
file.
A read of a directory yields an integral number of directory
entries in the machine independent encoding given above (see
read(5)).
ENTRY POINTS
Stat messages are generated by fstat and stat.
Wstat messages are generated by fwstat and wstat.
Page 2 Plan 9 (printed 12/26/24)