stat man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

STAT(5)								       STAT(5)

       stat, wstat - inquire or change file attributes

       size[4] Tstat tag[2] fid[4]
       size[4] Rstat tag[2] stat[n]

       size[4] Twstat tag[2] fid[4] stat[n]
       size[4] Rwstat tag[2]

       The  stat  transaction  inquires about the file identified by fid.  The
       reply will contain a machine-independent directory  entry,  stat,  laid
       out as follows:

	      total byte count of the following data

	      for kernel use

       dev[4] for kernel use

	      the  type	 of  the  file (directory, etc.), represented as a bit
	      vector corresponding to the high 8 bits of the file's mode word.

	      version number for given path

	      the file server's unique identification for the file

	      permissions and flags

	      last access time

	      last modification time

	      length of file in bytes

       name[ s ]
	      file name; must be / if the file is the root  directory  of  the

       uid[ s ]
	      owner name

       gid[ s ]
	      group name

       muid[ s ]
	      name of the user who last modified the file

       Integers in this encoding are in little-endian order (least significant
       byte first).  The convM2D and convD2M routines (see  fcall(2))  convert
       between directory entries and a C structure called a Dir.

       The mode contains permission bits as described in intro(5) and the fol‐
       lowing: 0x80000000 (DMDIR, this file is a directory), 0x40000000 (DMAP‐
       PEND,  append  only),  0x20000000  (DMEXCL,  exclusive use), 0x04000000
       (DMTMP, temporary); these are echoed in Qid.type.   Writes  to  append-
       only  files  always place their data at the end of the file; the offset
       in the write message is ignored, as is  the  OTRUNC  bit	 in  an	 open.
       Exclusive  use  files  may  be  open  for I/O by only one fid at a time
       across all clients of the server.  If a second open  is	attempted,  it
       draws  an  error.   Servers  may	 implement a timeout on the lock on an
       exclusive use file: if the fid holding the file open  has  been	unused
       for an extended period (of order at least minutes), it is reasonable to
       break the lock and deny the initial fid further I/O.   Temporary	 files
       are not included in nightly archives (see fossil(4)).

       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  (except  when  later changed by wstat).  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, cre‐
       ate, 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  muid  field names the user whose actions most recently changed the
       mtime of the file.

       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 length can be changed (affecting the actual  length  of  the
       file)  by  anyone with write permission on the file.  It is an error to
       attempt to set the length of a  directory  to  a	 non-zero  value,  and
       servers	may  decide  to	 reject length changes for other reasons.  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 and
       users(6) for users and groups).	None of the other data can be  altered
       by  a wstat and attempts to change them will trigger an error.  In par‐
       ticular, it is illegal to attempt  to  change  the  owner  of  a	 file.
       (These conditions may be relaxed when establishing the initial state of
       a file server; see fsconfig(8).)

       Either all the changes in wstat request happen, or none of  them	 does:
       if the request succeeds, all changes were made; if it fails, none were.

       A wstat request can avoid modifying some properties of the file by pro‐
       viding explicit ``don't touch'' values in the stat data that  is	 sent:
       zero-length  strings  for text values and the maximum unsigned value of
       appropriate size for integral values.  As a special case,  if  all  the
       elements of the directory entry in a Twstat message are ``don't touch''
       values, the server may interpret it as a request to guarantee that  the
       contents	 of the associated file are committed to stable storage before
       the Rwstat message is returned.	(Consider the message to mean,	``make
       the state of the file exactly what it claims to be.'')

       A read of a directory yields an integral number of directory entries in
       the machine independent encoding given above (see read(5)).

       Note that since the stat information is sent as	a  9P  variable-length
       datum, it is limited to a maximum of 65535 bytes.

       Stat messages are generated by fstat and stat.

       Wstat messages are generated by fwstat and wstat.

       To  make the contents of a directory, such as returned by read(5), easy
       to parse, each directory entry begins with a size field.	  For  consis‐
       tency,  the  entries  in	 Twstat	 and Rstat messages also contain their
       size, which means the size appears twice.  For example, the Rstat  mes‐
       sage  is	 formatted  as	``(4+1+2+2+n)[4]  Rstat	 tag[2]	 n[2] (n-2)[2]
       type[2] dev[4]...,'' where n is the value returned by convD2M.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net