1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
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>
|