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 <lib9.h>) machine-independent directory entry laid out as follows:

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

­uid[28] owner name

­gid[28] group name

­qid.path[4] the file server’s identification for the file

­qid.vers[4] version number for given path

­mode[4] permissions and flags

­atime[4] last access time

­mtime[4] last modification time

­length[8] length of file in bytes

­type[2] for kernel use

­dev[2] for kernel use

Integers in this encoding are in little-endian order (least significant byte first).  The ­convM2D and ­convD2M routines (see styx(10.2)) convert between directory entries and C structs. 

This encoding may be turned into a machine dependent ­Dir structure (see <lib9.h>) using routines defined in styx(10.2).

The ­mode contains permission bits as described in intro(5) and ­16r80000000 if this file is a directory. 

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.  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 ­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 ­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(5) for more information about permissions). 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 the ­fstat and ­stat calls (see sys-stat(2)).

­Wstat messages are generated by the ­fwstat and ­wstat calls (see sys-stat(2)).

SEE ALSO

sys-stat(2), intro(5), read(5), intro(10), styx(10.2)

Plan 9  —  June 29, 2000