diff options
Diffstat (limited to 'man/man3/stat.html')
| -rw-r--r-- | man/man3/stat.html | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/man/man3/stat.html b/man/man3/stat.html new file mode 100644 index 00000000..fb79a647 --- /dev/null +++ b/man/man3/stat.html @@ -0,0 +1,244 @@ +<head> +<title>stat(3) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>STAT(3)</b><td align=right><b>STAT(3)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, + nulldir – get and put file status<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#include <u.h><br> + #include <libc.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int stat(char *name, uchar *edir, int nedir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fstat(int fd, uchar *edir, int nedir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int wstat(char *name, uchar *edir, int nedir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fwstat(int fd, uchar *edir, int nedir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Dir* dirstat(char *name) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Dir* dirfstat(int fd) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int dirwstat(char *name, Dir *dir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int dirfwstat(int fd, Dir *dir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>void nulldir(Dir *d)<br> + </font></tt> +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Given a file’s <i>name</i>, or an open file descriptor <i>fd</i>, these routines + retrieve or modify file status information. <i>Stat</i>, <i>fstat</i>, <i>wstat</i>, + and <i>fwstat</i> are the system calls; they deal with machine-independent + <i>directory entries</i>. Their format is defined by <i>stat</i>(9p). <i>Stat</i> and + <i>fstat</i> retrieve information about <i>name</i> or <i>fd</i> into <i>edir</i>, a buffer + of length <i>nedir</i>, defined in <tt><font size=+1><libc.h></font></tt>. <i>Wstat</i> and <i>fwstat</i> write information + back, thus changing file attributes according to the contents + of <i>edir</i>. The data returned from the kernel includes its leading + 16-bit length field as described in <i>intro</i>(9p). For symmetry, this + field must also be present when passing data to the + kernel in a call to <i>wstat</i> and <i>fwstat</i>, but its value is ignored. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Dirstat</i>, <i>dirfstat</i>, <i>dirwstat</i>, and <i>dirfwstat</i> are similar to their + counterparts, except that they operate on <i>Dir</i> structures:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>typedef<br> + struct Dir {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + /* system−modified data */<br> + uint type; /* server type */<br> + uint dev; /* server subtype */<br> + /* file data */<br> + Qid qid; /* unique id from server */<br> + ulong mode; /* permissions */<br> + ulong atime; /* last read time */<br> + ulong mtime; /* last write time */<br> + vlong length; /* file length: see <u.h> */<br> + char *name; /* last element of path */<br> + char *uid; /* owner name */<br> + char *gid; /* group name */<br> + char *muid; /* last modifier name */<br> + + </table> + } Dir;<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + The returned structure is allocated by <a href="../man3/malloc.html"><i>malloc</i>(3)</a>; freeing it also + frees the associated strings. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + This structure and the <tt><font size=+1>Qid</font></tt> structure are defined in <tt><font size=+1><libc.h></font></tt>. If + the file resides on permanent storage and is not a directory, + the length returned by <i>stat</i> 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. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Each file is the responsibility of some <i>server</i>: it could be a + file server, a kernel device, or a user process. <tt><font size=+1>Type</font></tt> identifies + the server type, and <tt><font size=+1>dev</font></tt> says which of a group of servers of the + same type is the one responsible for this file. <tt><font size=+1>Qid</font></tt> is a structure + containing <tt><font size=+1>path</font></tt> and <tt><font size=+1>vers</font></tt> fields: <tt><font size=+1>path</font></tt> is guaranteed to be + unique among all path names currently on the file server, and + <tt><font size=+1>vers</font></tt> changes each time the file is modified. The <tt><font size=+1>path</font></tt> is a <tt><font size=+1>long + long</font></tt> (64 bits, <tt><font size=+1>vlong</font></tt>) and the <tt><font size=+1>vers</font></tt> is an <tt><font size=+1>unsigned long</font></tt> (32 bits, + <tt><font size=+1>ulong</font></tt>). Thus, if two files have the same <tt><font size=+1>type</font></tt>, <tt><font size=+1>dev</font></tt>, and <tt><font size=+1>qid</font></tt> they + are the same file. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The bits in <tt><font size=+1>mode</font></tt> are defined by + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>0x80000000 </font></tt> directory<br> + <tt><font size=+1>0x40000000 </font></tt> append only<br> + <tt><font size=+1>0x20000000 </font></tt> exclusive use (locked)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>0400 </font></tt> read permission by owner<br> + <tt><font size=+1>0200 </font></tt> write permission by owner<br> + <tt><font size=+1>0100 </font></tt> execute permission (search on directory) by owner<br> + <tt><font size=+1>0070 </font></tt> read, write, execute (search) by group<br> + <tt><font size=+1>0007 </font></tt> read, write, execute (search) by others<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + + </table> + + </table> + There are constants defined in <tt><font size=+1><libc.h></font></tt> for these bits: <tt><font size=+1>DMDIR</font></tt>, <tt><font size=+1>DMAPPEND</font></tt>, + and <tt><font size=+1>DMEXCL</font></tt> for the first three; and <tt><font size=+1>DMREAD</font></tt>, <tt><font size=+1>DMWRITE</font></tt>, and <tt><font size=+1>DMEXEC</font></tt> + for the read, write, and execute bits for others. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The two time fields are measured in seconds since the epoch (Jan + 1 00:00 1970 GMT). <tt><font size=+1>Mtime</font></tt> is the time of the last change of content. + Similarly, <tt><font size=+1>atime</font></tt> is set whenever the contents are accessed; also, + it is set whenever <tt><font size=+1>mtime</font></tt> is set. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>Uid</font></tt> and <tt><font size=+1>gid</font></tt> are the names of the owner and group of the file; + <tt><font size=+1>muid</font></tt> is the name of the user that last modified the file (setting + <tt><font size=+1>mtime</font></tt>). Groups are also users, but each server is free to associate + a list of users with any user name <i>g</i>, and that list is the set + of users in the group <i>g</i>. When an initial attachment is made to + a + server, the user string in the process group is communicated to + the server. Thus, the server knows, for any given file access, + whether the accessing process is the owner of, or in the group + of, the file. This selects which sets of three bits in <tt><font size=+1>mode</font></tt> is + used to check permissions. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Only some of the fields may be changed with the <i>wstat</i> calls. The + <tt><font size=+1>name</font></tt> can be changed by anyone with write permission in the parent + directory. The <tt><font size=+1>mode</font></tt> and <tt><font size=+1>mtime</font></tt> can be changed by the owner or the + group leader of the file’s current group. The <i>gid</i> 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 <i>intro</i>(9p) for more information about + permissions, users, and groups). The <tt><font size=+1>length</font></tt> can be changed by + anyone with write permission, provided the operation is implemented + by the server. (See <i>intro</i>(9p) for permission, user, + and group information). + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Special values in the fields of the <tt><font size=+1>Dir</font></tt> passed to <i>wstat</i> indicate + that the field is not intended to be changed by the call. The + values are the maximum unsigned integer of appropriate size for + integral values (usually <tt><font size=+1>~0</font></tt>, but beware of conversions and size + mismatches when comparing values) and the empty or nil string + for string values. The routine <i>nulldir</i> initializes all the elements + of <i>d</i> to these “don’t care” values. Thus one may change the mode, + for example, by using <i>nulldir</i> to initialize a <tt><font size=+1>Dir</font></tt>, then setting + the mode, and then doing <i>wstat</i>; it is not necessary to use <i>stat</i> + to retrieve the initial values first. + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/lib9/dirstat.c<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man3/intro.html"><i>intro</i>(3)</a>, <a href="../man3/fcall.html"><i>fcall</i>(3)</a>, <a href="../man3/dirread.html"><i>dirread</i>(3)</a>, <i>stat</i>(9p)<br> + +</table> +<p><font size=+1><b>DIAGNOSTICS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The <i>dir</i> functions return a pointer to the data for a successful + call, or <tt><font size=+1>nil</font></tt> on error. The others return the number of bytes copied + on success, or –1 on error. All set <i>errstr</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + If the buffer for <i>stat</i> or <i>fstat</i> is too short for the returned + data, the return value will be <tt><font size=+1>BIT16SZ</font></tt> (see <a href="../man3/fcall.html"><i>fcall</i>(3)</a>) and the + two bytes returned will contain the initial count field of the + returned data; retrying with <tt><font size=+1>nedir</font></tt> equal to that value plus <tt><font size=+1>BIT16SZ</font></tt> + (for the count itself) should succeed.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |