SYS-STAT(2) SYS-STAT(2)
NAME
fstat, fwstat, stat, wstat - get and put file status
SYNOPSIS
include "sys.m";
sys := load Sys Sys->PATH;
fstat: fn(fd: ref FD): (int, Dir);
fwstat: fn(fd: ref FD; d: Dir): int;
stat: fn(name: string): (int, Dir);
wstat: fn(name: string, d: Dir): int;
DESCRIPTION
Given a file's name, or an open file descriptor fd, these
routines retrieve or modify file status information. Stat
and fstat retrieve information about name or fd into the Dir
member of the return tuple. The int member will be zero for
success and -1 for failure. wstat and fwstat write informa-
tion back, thus changing file attributes according to d.
Both functions return zero for success and -1 for failure.
File status is recorded as a Dir type:
Qid: adt
{
path: int;
vers: int;
};
Dir: adt
{
name: string;
uid: string;
gid: string;
qid: Qid;
mode: int;
atime: int;
mtime: int;
length: int;
dtype: int;
dev: int;
};
If the file resides on permanent storage and is not a direc-
tory, the length returned by stat is the number of bytes in
the file. For directories, the length returned is zero.
Some devices report a length that is the number of bytes
that may be read from the device without blocking.
Page 1 Plan 9 (printed 4/19/24)
SYS-STAT(2) SYS-STAT(2)
Each file is the responsibility of some server: it could be
a file server, a kernel device, or a user process. Dtype
identifies the server type, and dev says which of a group of
servers of the same type is the one responsible for this
file. Qid is a type containing path and vers members, each
an integer: path is guaranteed to be unique among all path
names currently on the file server, and vers changes each
time the file is modified. Thus, if two files have the same
dtype, dev, and qid, they are the same file.
The bits in mode are defined by
16r80000000 #directory (Sys->CHDIR)
8r400 #read permission by owner
8r200 #write permission by owner
8r100 #execute permission (search on directory) by owner
8r070 #read, write, execute (search) by group
8r007 #read, write, execute (search) by others
There is a Sys constant defined for the directory bit:
Sys->CHDIR.
The two time fields are measured in seconds since the epoch
(Jan 1 00:00 1970 GMT). Mtime is the time of the last
change of content. Similarly, atime is set whenever the
contents are accessed; also, it is set whenever mtime is
set.
Uid and gid are the names of the owner and group (of owners)
of the file. When an initial attachment is made to a
server, the user string in the process group is communicated
to the server. Thus, the server knows, for any given file
access, whether the accessing process is the owner of, or in
the group of, the file. This selects which sets of three
bits in mode is used to check permissions.
Only some of the fields may be changed by wstat calls. The
name can be changed by anyone with write permission in the
parent directory. The mode and mtime can be changed by the
owner or the group leader of the file's current group. The
gid can be changed by the owner if he or she is a member of
the new group. The gid can be changed by the group leader
of the file's current group if he or she is the leader of
the new group.
FAT file system (Windows9x and Windows/NT)
The values of uid and gid are Everyone.
Files and directories always have read and execute permis-
sion, which cannot be changed. Files without write permis-
sion cannot be removed.
Page 2 Plan 9 (printed 4/19/24)
SYS-STAT(2) SYS-STAT(2)
NTFS file system (Windows/NT)
Permissions for read, write and execute operates as
described in the main section above.
Emu(1) attempts to maintain a limited but consistent map
between Inferno and NT worlds, specifically between Inferno
names and NT security IDs. Special NT group Everyone repre-
sents `other' for file permissions. The Inferno uid is the
file owner under NT; the Inferno gid reported is the first
user in the file's ACL that is neither the owner nor
Everyone; failing that, the gid is the file's owner.
SEE ALSO
sys-intro(2), sys-dirread(2), sys-open(2)
Page 3 Plan 9 (printed 4/19/24)