STAT(2)                                                   STAT(2)

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

     SYNOPSIS
          #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)

     DESCRIPTION
          Given a file's name, or an open file descriptor fd, these
          routines retrieve or modify file status information.  Stat,
          fstat, wstat, and fwstat 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,
          defined 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 counterparts, except that they operate on Dir struc-
          tures:

               typedef
               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 */

     Page 1                       Plan 9             (printed 1/31/23)

     STAT(2)                                                   STAT(2)

               } Dir;

          This structure, the Qid structure, NAMELEN, and DIRLEN are
          defined in <libc.h>.  For historical reasons, the Length
          structure, defined in </$objtype/u.h>, is a structure with a
          single vlong element, length.  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 connections), the length is the
          number of bytes that can be read without blocking.

          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, CHAPPEND, 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 pro-
          cess group is communicated to the server.  Thus, the server
          knows, for any given file access, whether the accessing

     Page 2                       Plan 9             (printed 1/31/23)

     STAT(2)                                                   STAT(2)

          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).

     SOURCE
          /sys/src/libc/9syscall  for the non-dir routines
          /sys/src/libc/9sys      for the routines prefixed `dir'

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

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

     Page 3                       Plan 9             (printed 1/31/23)