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