= fstat, fwstat, stat, wstat: get and put file status     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;     nulldir: con Dir(special don't care values);    zerodir: con Dir(all elements set to zero); Given  a  file's  name,  or an open file descriptor fd, theseroutines retrieve or modify file  status  information.   Statand  fstat retrieve information about name or fd into the Dirmember of the return tuple.  The int member will be zero  forsuccess  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:   big;     # unique id for file on server    vers:   int;     # write version number    qtype:  int;     # file type (see below)}; Dir: adt{    name:   string;  # last element of path    uid:    string;  # owner name    gid:    string;  # group name    muid:   string;  # last modifier name    qid:    Qid;     # unique id from server    mode:   int;     # permissions    atime:  int;     # last read time    mtime:  int;     # last write time    length: big;     # file length    dtype:  int;     # server type    dev:    int;     # server subtype}; If  the file resides on permanent storage and is not a direc‐tory, the length field returned in Dir by stat is the  numberof  bytes  in the file.  For directories, the length returnedis zero.  Some devices, in particular files that are  streamssuch  as  pipes and network connections, report a length thatis the number of bytes that may be read from the device with‐out blocking. Each file is the responsibility of some server: it could be afile server, a kernel device, or a user process.  Dtype iden‐tifies  the  server  type,  and  dev says which of a group ofservers of the same type is  the  one  responsible  for  thisfile.  Qid is a type containing path, vers and qtype members,each an integer: path is guaranteed to be  unique  among  allpath  names  currently  on the file server; vers changes eachtime the file is modified; and qtype gives the file's charac‐teristics  (eg,  directory  or  file).   The  path is 64 bits(big), and the vers is 32 bits (int).   Thus,  if  two  fileshave  the  same  dtype, dev, and qid, they are the same file.(Except when checking that the contents are the same, as in afile  cache,  the  version  is often considered irrelevant inthat comparison.)  The bits in qtype are defined by        16r80 # directory (Sys->QTDIR)       16r40 # append-only (Sys->QTAPPEND)       16r20 # exclusive-use (Sys->QTEXCL)       16r08 # authentication file (Sys->QTAUTH)       16r00 # any other file (Sys->QTFILE) (They are the top 8 bits of Dir.mode for the  file,  as  dis‐cussed   below.)    Sys   defines  constants  for  the  bits:Sys->QTDIR, Sys->QTAPPEND, and so on, as  shown  above.   Thevalue  Sys->QTFILE  is not a particular bit; it is defined tobe zero, to allow a symbolic name to be  used  when  creatingQid values for ordinary files. The bits in mode are defined by        16r80000000 #directory (Sys->DMDIR)       16r40000000 #append-only (Sys->DMAPPEND)       16r20000000 #exclusive-use (Sys->DMEXCL)       16r08000000 #authentication file (Sys->DMAUTH)             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  are  constants defined in Sys for the first four bits:Sys->DMDIR, Sys->DMAPPEND and Sys->DMEXCL for  normal  files,and  Sys->DMAUTH  only  for  the  special authentication fileopened by sys-fauth(2). The two time fields are measured in seconds since  the  epoch(Jan 1 00:00 1970 GMT).  Mtime is the time of the last changeof content.  Similarly, atime is set  whenever  the  contentsare 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; muid is the name of the user that last  modifiedthe  file  (setting  mtime).  Groups are also users, but eachserver is free to associate a list of  users  with  any  username  g,  and  that  list is the set of users in the group g.When an initial attachment is made  to  a  server,  the  userstring  in  the  process group is communicated to the server.Thus, the server knows, for any given  file  access,  whetherthe  accessing  process  is the owner of, or in the group of,the file.  This selects which sets of three bits in  mode  isused to check permissions. Only  some  of the fields may be changed by wstat calls.  Thename can be changed by anyone with write  permission  in  theparent  directory.   The mode and mtime can be changed by theowner or the group leader of the file's current  group.   Thegid  can  be changed by the owner if he or she is a member ofthe new group.  The gid can be changed by the group leader ofthe  file's  current  group if he or she is the leader of thenew group.  The length can be changed by  anyone  with  writepermission,  provided  the  operation  is  implemented by theserver.  (See intro(5) and stat(5) for more information aboutpermissions,  and  users(6)  for  how  to configure users andgroups when using kfs(4)). Special values in the fields of the Dir passed to wstat indi‐cate  that  the  field  is  not intended to be changed by thecall.  The values are the maximum unsigned integer of  appro‐priate  size  for  integral values (usually ~0, but beware ofconversions and size mismatches when  comparing  values)  andthe  empty  or  nil  string  for string values.  The constantnulldir in Sys has all  its  elements  initialised  to  these``don't  care''  values.   Thus  one may change the mode, forexample, by assigning sys->nulldir to initialize a Dir,  thensetting  the  mode, and then doing wstat; it is not necessaryto use stat to retrieve the initial values first. The constant zerodir has  all  its  elements  initialised  tozero.   It can be used to initialise a Dir structure, for usewith styx(2) or styxservers-nametree(2), for instance. == see ALSOsys-intro(2), sys-dirread(2), sys-open(2)