Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
STAT(9P)							      STAT(9P)

       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 convert between di-
       rectory entries and a C structure called	a Dir.

       The  mode  contains  permission	bits as	described in intro(9P) and the
       following: 0x80000000 (DMDIR, this file	is  a  directory),  0x40000000
       (DMAPPEND, 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.   Ex-
       clusive	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	Plan 9's 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  di-
       rectory;	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  de-
       cide  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(9P) for	more information about permissions, users, and
       groups).	 None of the other data	can be altered by a wstat and attempts
       to  change them will trigger an error.  In particular, it is illegal to
       attempt to change the owner of a	file.  (These conditions  may  be  re-
       laxed  when  establishing  the initial state of a file server; see Plan
       9's 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(9P)).

       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 fsdirfstat and fsdirstat (see

       Wstat messages are generated by fsdirfwstat and fsdirwstat.

       To make the contents of a directory, such as returned by	read(9P), 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.



Want to link to this manual page? Use this URL:

home | help