term% ls -F
term% cat index.txt
STAT(2)                       System Calls Manual                      STAT(2)

       stat,  fstat,  wstat,  fwstat, dirstat, dirfstat, dirwstat, dirfwstat -
       get and put file status

       #include <u.h>
       #include <libc.h>

       int stat(char *name, char *edir)

       int fstat(int fd, char *edir)

       int wstat(char *name, char *edir)

       int fwstat(int fd, char *edir)

       int dirstat(char *name, Dir *dir)

       int dirfstat(int fd, Dir *dir)

       int dirwstat(char *name, Dir *dir)

       int dirfwstat(int fd, Dir *dir)

       Given a file's name, or an open file descriptor fd, these routines  re‐
       trieve  or modify file status information.  Stat, fstat, wstat, and fw‐
       stat are the system calls; they deal with machine-independent directory
       entries.   Their format is defined by stat(5).  Stat and fstat retrieve
       information about name or fd into edir, a buffer of length DIRLEN,  de‐
       fined  in  <libc.h>.   Wstat  and  fwstat  write information back, thus
       changing file attributes according to edir.

       Dirstat, dirfstat, dirwstat, and dirfwstat are the same as their  coun‐
       terparts, except that they operate on Dir structures:

              struct Dir {
                    char    name[NAMELEN];   /* last element of path */
                    char    uid[NAMELEN];    /* owner name */
                    char    gid[NAMELEN];    /* group name */
                    Qid     qid;             /* unique id from server */
                    long    mode;            /* permissions */
                    long    atime;           /* last read time */
                    long    mtime;           /* last write time */
                    Length;                  /* file length: see <u.h> */
                    ushort  type;            /* server type */
                    ushort  dev;             /* server subtype */
              } Dir;

       This  structure,  the Qid structure, NAMELEN, and DIRLEN are defined in
       <libc.h>.  The Length structure is defined in </$objtype/u.h>.   Length
       is  an  unnamed  structure (see 2c(1)), which means that its fields are
       directly accessible; if the length is known to fit in a long, then  use
       length  as  a field name to retrieve it.  If the file resides on perma‐
       nent storage and is not a directory, the length returned by stat is the
       number  of  bytes in the file.  For directories, the length returned is
       zero.  For files that are streams  (e.g.,  pipes  and  network  connec‐
       tions),  the  length  is  the  number of bytes that can be read without

       Each file is the responsibility of some server:  it  could  be  a  file
       server, a kernel device, or a user process.  Type 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 structure containing path and
       vers fields, each an unsigned long: 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 type,
       dev, and qid they are the same file.

       The bits in mode are defined by

             0x80000000   directory
             0x40000000   append only
             0x20000000   exclusive use (locked)

                   0400   read permission by owner
                   0200   write permission by owner
                   0100   execute permission (search on directory) by owner
                   0070   read, write, execute (search) by group
                   0007   read, write, execute (search) by others

       There  are  constants  defined in <libc.h> for these bits: CHDIR, CHAP‐
       PEND, and CHEXCL for the first three; and CHREAD, CHWRITE,  and  CHEXEC
       for the read, write, and execute bits for others.

       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 the  file.   Groups
       are  also  users,  but each server is free to associate a list of users
       with any user name g, and that list is the set of users in the group g.
       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 with the 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.  (See intro(5) for permission information, and users(6) for
       user and group information).

              for the non-dir routines

              for the routines prefixed dir

       intro(2), fcall(2), dirread(2), stat(5)

       All these functions return 0 on success, -1 on error, and set errstr.