stat(9P) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man9/stat.html | 258 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 man/man9/stat.html (limited to 'man/man9/stat.html') diff --git a/man/man9/stat.html b/man/man9/stat.html new file mode 100644 index 00000000..eb5c9c4a --- /dev/null +++ b/man/man9/stat.html @@ -0,0 +1,258 @@ + +stat(9P) - Plan 9 from User Space + + + + +

STAT(9P) STAT(9P) +

+
+

NAME
+ +
+ + stat, wstat – inquire or change file attributes
+ +
+

SYNOPSIS
+ +
+ + 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]
+ +
+

DESCRIPTION
+ +
+ + The stat transaction inquires about the file identified by fid. + The reply will contain a machine-independent directory entry, + stat, laid out as follows:
+ size[2]total byte count of the following data
+ type[2]
+ +
+ + for kernel use
+ +
+ dev[4]for kernel use
+ qid.type[1]
+ +
+ + the type of the file (directory, etc.), represented as a bit vector + corresponding to the high 8 bits of the file’s mode word.
+ +
+ qid.vers[4]
+ +
+ + version number for given path
+ +
+ qid.path[8]
+ +
+ + the file server’s unique identification for the file
+ +
+ mode[4]
+ +
+ + permissions and flags
+ +
+ atime[4]
+ +
+ + last access time
+ +
+ mtime[4]
+ +
+ + last modification time
+ +
+ length[8]
+ +
+ + length of file in bytes
+ +
+ name[ s ]
+ +
+ + file name; must be / if the file is the root directory of the + server
+ +
+ 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(3)) convert + between directory 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. 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 + 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, create, 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(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 relaxed 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 providing 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.
+ +
+

ENTRY POINTS
+ +
+ + Stat messages are generated by fsdirfstat and fsdirstat (see 9pclient(3)). + +
+ + Wstat messages are generated by fsdirfwstat and fsdirwstat.
+ +
+

BUGS
+ +
+ + 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 consistency, the entries in Twstat and Rstat messages also + contain their size, which means the size appears twice. For example, + the Rstat message 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.
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3