1 cfa37a7b 2004-04-10 devnull .TH STAT 3
3 cfa37a7b 2004-04-10 devnull stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, nulldir \- get and put file status
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
10 cfa37a7b 2004-04-10 devnull int stat(char *name, uchar *edir, int nedir)
13 cfa37a7b 2004-04-10 devnull int fstat(int fd, uchar *edir, int nedir)
16 cfa37a7b 2004-04-10 devnull int wstat(char *name, uchar *edir, int nedir)
19 cfa37a7b 2004-04-10 devnull int fwstat(int fd, uchar *edir, int nedir)
22 cfa37a7b 2004-04-10 devnull Dir* dirstat(char *name)
25 cfa37a7b 2004-04-10 devnull Dir* dirfstat(int fd)
28 cfa37a7b 2004-04-10 devnull int dirwstat(char *name, Dir *dir)
31 cfa37a7b 2004-04-10 devnull int dirfwstat(int fd, Dir *dir)
34 cfa37a7b 2004-04-10 devnull void nulldir(Dir *d)
35 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
36 cfa37a7b 2004-04-10 devnull Given a file's
37 cfa37a7b 2004-04-10 devnull .IR name ,
38 cfa37a7b 2004-04-10 devnull or an open file descriptor
40 cfa37a7b 2004-04-10 devnull these routines retrieve or modify file status information.
41 cfa37a7b 2004-04-10 devnull .IR Stat ,
42 cfa37a7b 2004-04-10 devnull .IR fstat ,
43 cfa37a7b 2004-04-10 devnull .IR wstat ,
45 cfa37a7b 2004-04-10 devnull .I fwstat
46 cfa37a7b 2004-04-10 devnull are the system calls; they deal with machine-independent
47 cfa37a7b 2004-04-10 devnull .IR "directory entries" .
48 cfa37a7b 2004-04-10 devnull Their format is defined by
49 058b0118 2005-01-03 devnull .IR stat (9p).
53 cfa37a7b 2004-04-10 devnull retrieve information about
58 cfa37a7b 2004-04-10 devnull .IR edir ,
59 cfa37a7b 2004-04-10 devnull a buffer of length
60 cfa37a7b 2004-04-10 devnull .IR nedir ,
61 cfa37a7b 2004-04-10 devnull defined in
62 cfa37a7b 2004-04-10 devnull .BR <libc.h> .
65 cfa37a7b 2004-04-10 devnull .I fwstat
66 cfa37a7b 2004-04-10 devnull write information back, thus changing file attributes according to the contents of
67 cfa37a7b 2004-04-10 devnull .IR edir .
68 cfa37a7b 2004-04-10 devnull The data returned from the kernel includes its leading 16-bit length field
69 cfa37a7b 2004-04-10 devnull as described in
70 058b0118 2005-01-03 devnull .IR intro (9p).
71 cfa37a7b 2004-04-10 devnull For symmetry, this field must also be present when passing data to the kernel in a call to
74 cfa37a7b 2004-04-10 devnull .IR fwstat ,
75 cfa37a7b 2004-04-10 devnull but its value is ignored.
77 cfa37a7b 2004-04-10 devnull .IR Dirstat ,
78 cfa37a7b 2004-04-10 devnull .IR dirfstat ,
79 cfa37a7b 2004-04-10 devnull .IR dirwstat ,
81 cfa37a7b 2004-04-10 devnull .I dirfwstat
82 cfa37a7b 2004-04-10 devnull are similar to their counterparts, except that they
83 cfa37a7b 2004-04-10 devnull operate on
85 cfa37a7b 2004-04-10 devnull structures:
88 cfa37a7b 2004-04-10 devnull .ta 6n +\w'ulong 'u +\w'mtime; 'u
90 cfa37a7b 2004-04-10 devnull struct Dir {
91 cfa37a7b 2004-04-10 devnull /* system-modified data */
92 cfa37a7b 2004-04-10 devnull uint type; /* server type */
93 cfa37a7b 2004-04-10 devnull uint dev; /* server subtype */
94 cfa37a7b 2004-04-10 devnull /* file data */
95 cfa37a7b 2004-04-10 devnull Qid qid; /* unique id from server */
96 cfa37a7b 2004-04-10 devnull ulong mode; /* permissions */
97 cfa37a7b 2004-04-10 devnull ulong atime; /* last read time */
98 cfa37a7b 2004-04-10 devnull ulong mtime; /* last write time */
99 cfa37a7b 2004-04-10 devnull vlong length; /* file length: see <u.h> */
100 cfa37a7b 2004-04-10 devnull char *name; /* last element of path */
101 cfa37a7b 2004-04-10 devnull char *uid; /* owner name */
102 cfa37a7b 2004-04-10 devnull char *gid; /* group name */
103 cfa37a7b 2004-04-10 devnull char *muid; /* last modifier name */
107 cfa37a7b 2004-04-10 devnull The returned structure is allocated by
108 d32deab1 2020-08-16 rsc .MR malloc (3) ;
109 cfa37a7b 2004-04-10 devnull freeing it also frees the associated strings.
111 cfa37a7b 2004-04-10 devnull This structure and
114 cfa37a7b 2004-04-10 devnull structure
115 cfa37a7b 2004-04-10 devnull are defined in
116 cfa37a7b 2004-04-10 devnull .BR <libc.h> .
117 cfa37a7b 2004-04-10 devnull If the file resides on permanent storage and is not a directory,
118 cfa37a7b 2004-04-10 devnull the length returned by
120 cfa37a7b 2004-04-10 devnull is the number of bytes in the file.
121 cfa37a7b 2004-04-10 devnull For directories, the length returned is zero.
122 cfa37a7b 2004-04-10 devnull For files that are streams (e.g., pipes and network connections),
123 cfa37a7b 2004-04-10 devnull the length is the number of bytes that can be read without blocking.
125 cfa37a7b 2004-04-10 devnull Each file is the responsibility of some
126 cfa37a7b 2004-04-10 devnull .IR server :
127 cfa37a7b 2004-04-10 devnull it could be a file server, a kernel device, or a user process.
129 cfa37a7b 2004-04-10 devnull identifies the server type, and
131 cfa37a7b 2004-04-10 devnull says which of a group of servers of the same type is the one
132 cfa37a7b 2004-04-10 devnull responsible for this file.
134 cfa37a7b 2004-04-10 devnull is a structure containing
140 cfa37a7b 2004-04-10 devnull is guaranteed to be
141 cfa37a7b 2004-04-10 devnull unique among all path names currently on the file server, and
143 cfa37a7b 2004-04-10 devnull changes each time the file is modified.
149 cfa37a7b 2004-04-10 devnull (64 bits,
150 cfa37a7b 2004-04-10 devnull .BR vlong )
154 cfa37a7b 2004-04-10 devnull .B unsigned long
155 cfa37a7b 2004-04-10 devnull (32 bits,
156 cfa37a7b 2004-04-10 devnull .BR ulong ).
157 cfa37a7b 2004-04-10 devnull Thus, if two files have the same
158 cfa37a7b 2004-04-10 devnull .BR type ,
159 cfa37a7b 2004-04-10 devnull .BR dev ,
162 cfa37a7b 2004-04-10 devnull they are the same file.
164 cfa37a7b 2004-04-10 devnull The bits in
166 cfa37a7b 2004-04-10 devnull are defined by
168 cfa37a7b 2004-04-10 devnull .ta 6n +\w'\fL0x80000000 'u
170 cfa37a7b 2004-04-10 devnull \fL 0x80000000\fP directory
171 cfa37a7b 2004-04-10 devnull \fL 0x40000000\fP append only
172 cfa37a7b 2004-04-10 devnull \fL 0x20000000\fP exclusive use (locked)
173 8bf462f3 2022-05-11 crossd \fL 0x00800000\fP Unix device file
174 8bf462f3 2022-05-11 crossd \fL 0x02000000\fP symbolic link
175 17ddbe11 2005-02-08 devnull \fL 0x00200000\fP named pipe
176 17ddbe11 2005-02-08 devnull \fL 0x00100000\fP socket
178 cfa37a7b 2004-04-10 devnull \fL 0400\fP read permission by owner
179 cfa37a7b 2004-04-10 devnull \fL 0200\fP write permission by owner
180 cfa37a7b 2004-04-10 devnull \fL 0100\fP execute permission (search on directory) by owner
181 cfa37a7b 2004-04-10 devnull \fL 0070\fP read, write, execute (search) by group
182 cfa37a7b 2004-04-10 devnull \fL 0007\fP read, write, execute (search) by others
185 cfa37a7b 2004-04-10 devnull There are constants defined in
186 cfa37a7b 2004-04-10 devnull .B <libc.h>
187 cfa37a7b 2004-04-10 devnull for these bits:
188 cfa37a7b 2004-04-10 devnull .BR DMDIR ,
189 cfa37a7b 2004-04-10 devnull .BR DMAPPEND ,
191 cfa37a7b 2004-04-10 devnull .B DMEXCL
192 cfa37a7b 2004-04-10 devnull for the first three; and
193 cfa37a7b 2004-04-10 devnull .BR DMREAD ,
194 cfa37a7b 2004-04-10 devnull .BR DMWRITE ,
196 cfa37a7b 2004-04-10 devnull .B DMEXEC
197 cfa37a7b 2004-04-10 devnull for the read, write, and execute bits for others.
199 cfa37a7b 2004-04-10 devnull The two time fields are measured in seconds since the epoch
200 cfa37a7b 2004-04-10 devnull (Jan 1 00:00 1970 GMT).
201 cfa37a7b 2004-04-10 devnull .B Mtime
202 cfa37a7b 2004-04-10 devnull is the time of the last change of content.
203 cfa37a7b 2004-04-10 devnull Similarly,
204 cfa37a7b 2004-04-10 devnull .B atime
205 cfa37a7b 2004-04-10 devnull is set whenever the contents are accessed;
206 cfa37a7b 2004-04-10 devnull also, it is set whenever
207 cfa37a7b 2004-04-10 devnull .B mtime
213 cfa37a7b 2004-04-10 devnull are the names of the owner and group of the file;
215 cfa37a7b 2004-04-10 devnull is the name of the user that last modified the file (setting
216 cfa37a7b 2004-04-10 devnull .BR mtime ).
217 cfa37a7b 2004-04-10 devnull Groups are also users, but each server is free to associate
218 cfa37a7b 2004-04-10 devnull a list of users with any user name
220 cfa37a7b 2004-04-10 devnull and that list is the
221 cfa37a7b 2004-04-10 devnull set of users in the group
223 cfa37a7b 2004-04-10 devnull When an initial attachment is made to a server,
224 cfa37a7b 2004-04-10 devnull the user string in the process group is communicated to the server.
225 cfa37a7b 2004-04-10 devnull Thus, the server knows, for any given file access, whether the accessing
226 cfa37a7b 2004-04-10 devnull process is the owner of, or in the group of, the file.
227 cfa37a7b 2004-04-10 devnull This selects which sets of three bits in
229 cfa37a7b 2004-04-10 devnull is used to check permissions.
231 cfa37a7b 2004-04-10 devnull Only some of the fields may be changed with the
232 cfa37a7b 2004-04-10 devnull .I wstat
236 cfa37a7b 2004-04-10 devnull can be changed by anyone with write permission in the parent directory.
240 cfa37a7b 2004-04-10 devnull .B mtime
241 cfa37a7b 2004-04-10 devnull can be changed by the owner or the group leader of the file's current
245 cfa37a7b 2004-04-10 devnull can be changed: by the owner if also a member of the new group; or
246 cfa37a7b 2004-04-10 devnull by the group leader of the file's current group
247 cfa37a7b 2004-04-10 devnull if also leader of the new group
249 058b0118 2005-01-03 devnull .IR intro (9p)
250 058b0118 2005-01-03 devnull for more information about permissions, users, and groups).
252 cfa37a7b 2004-04-10 devnull .B length
253 cfa37a7b 2004-04-10 devnull can be changed by anyone with write permission, provided the operation
254 cfa37a7b 2004-04-10 devnull is implemented by the server.
256 058b0118 2005-01-03 devnull .IR intro (9p)
257 058b0118 2005-01-03 devnull for permission, user, and group information).
259 cfa37a7b 2004-04-10 devnull Special values in the fields of the
261 cfa37a7b 2004-04-10 devnull passed to
262 cfa37a7b 2004-04-10 devnull .I wstat
263 cfa37a7b 2004-04-10 devnull indicate that the field is not intended to be changed by the call.
264 cfa37a7b 2004-04-10 devnull The values are the maximum unsigned integer of appropriate size
265 cfa37a7b 2004-04-10 devnull for integral values (usually
266 cfa37a7b 2004-04-10 devnull .BR ~0 ,
267 cfa37a7b 2004-04-10 devnull but beware of conversions and size mismatches
268 cfa37a7b 2004-04-10 devnull when comparing values) and the empty or nil string for string values.
269 cfa37a7b 2004-04-10 devnull The routine
270 cfa37a7b 2004-04-10 devnull .I nulldir
271 cfa37a7b 2004-04-10 devnull initializes all the elements of
273 cfa37a7b 2004-04-10 devnull to these ``don't care'' values.
274 cfa37a7b 2004-04-10 devnull Thus one may change the mode, for example, by using
275 cfa37a7b 2004-04-10 devnull .I nulldir
276 cfa37a7b 2004-04-10 devnull to initialize a
277 cfa37a7b 2004-04-10 devnull .BR Dir ,
278 cfa37a7b 2004-04-10 devnull then setting the mode, and then doing
279 cfa37a7b 2004-04-10 devnull .IR wstat ;
280 cfa37a7b 2004-04-10 devnull it is not necessary to use
282 cfa37a7b 2004-04-10 devnull to retrieve the initial values first.
283 cfa37a7b 2004-04-10 devnull .SH SOURCE
284 c3674de4 2005-01-11 devnull .B \*9/src/lib9/dirstat.c
285 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
286 d32deab1 2020-08-16 rsc .MR intro (3) ,
287 d32deab1 2020-08-16 rsc .MR fcall (3) ,
288 d32deab1 2020-08-16 rsc .MR dirread (3) ,
289 058b0118 2005-01-03 devnull .IR stat (9p)
290 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
293 cfa37a7b 2004-04-10 devnull functions return a pointer to the data for a successful call, or
295 cfa37a7b 2004-04-10 devnull on error.
296 cfa37a7b 2004-04-10 devnull The others
297 cfa37a7b 2004-04-10 devnull return the number of bytes copied on success, or \-1 on error.
299 cfa37a7b 2004-04-10 devnull .IR errstr .
301 cfa37a7b 2004-04-10 devnull If the buffer for
304 cfa37a7b 2004-04-10 devnull .I fstat
305 cfa37a7b 2004-04-10 devnull is too short for the returned data, the return value will be
306 cfa37a7b 2004-04-10 devnull .B BIT16SZ
308 d32deab1 2020-08-16 rsc .MR fcall (3) )
309 cfa37a7b 2004-04-10 devnull and the two bytes
310 cfa37a7b 2004-04-10 devnull returned will contain the initial count field of the
311 cfa37a7b 2004-04-10 devnull returned data;
312 cfa37a7b 2004-04-10 devnull retrying with
313 cfa37a7b 2004-04-10 devnull .B nedir
314 cfa37a7b 2004-04-10 devnull equal to
315 cfa37a7b 2004-04-10 devnull that value plus
316 cfa37a7b 2004-04-10 devnull .B BIT16SZ
317 cfa37a7b 2004-04-10 devnull (for the count itself) should succeed.
