244 lines
13 KiB
HTML
244 lines
13 KiB
HTML
<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>
|