| blob | ff1db973189c9b7a1b24ae81097f5d7166fadf6d |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH STAT 2 "Oct 10, 2007"
8 .SH NAME
9 stat, lstat, fstat, fstatat \- get file status
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <fcntl.h>
14 #include <sys/types.h>
15 #include <sys/stat.h>
17 \fBint\fR \fBstat\fR(\fBconst char *restrict\fR \fIpath\fR, \fBstruct stat *restrict\fR \fIbuf\fR);
18 .fi
20 .LP
21 .nf
22 \fBint\fR \fBlstat\fR(\fBconst char *restrict\fR \fIpath\fR, \fBstruct stat *restrict\fR \fIbuf\fR);
23 .fi
25 .LP
26 .nf
27 \fBint\fR \fBfstat\fR(\fBint\fR \fIfildes\fR, \fBstruct stat *\fR\fIbuf\fR);
28 .fi
30 .LP
31 .nf
32 \fBint\fR \fBfstatat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR, \fBstruct stat *\fR\fIbuf\fR,
33 \fBint\fR \fIflag\fR);
34 .fi
36 .SH DESCRIPTION
37 .sp
38 .LP
39 The \fBstat()\fR function obtains information about the file pointed to by
40 \fIpath\fR. Read, write, or execute permission of the named file is not
41 required, but all directories listed in the path name leading to the file must
42 be searchable.
43 .sp
44 .LP
45 The \fBlstat()\fR function obtains file attributes similar to \fBstat()\fR,
46 except when the named file is a symbolic link; in that case \fBlstat()\fR
47 returns information about the link, while \fBstat()\fR returns information
48 about the file the link references.
49 .sp
50 .LP
51 The \fBfstat()\fR function obtains information about an open file known by the
52 file descriptor \fIfildes\fR, obtained from a successful \fBopen\fR(2),
53 \fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2), or \fBpipe\fR(2) function. If
54 \fIfildes\fR references a shared memory object, the system updates in the
55 \fBstat\fR structure pointed to by the \fIbuf\fR argument only the
56 \fBst_uid\fR, \fBst_gid\fR, \fBst_size\fR, and \fBst_mode\fR fields, and only
57 the \fBS_IRUSR\fR, \fBS_IWUSR\fR, \fBS_IRGRP\fR, \fBS_IWGRP\fR, \fBS_IROTH\fR,
58 and \fBS_IWOTH\fR file permission bits need be valid. The system can update
59 other fields and flags. The \fBfstat()\fR function updates any pending
60 time-related fields before writing to the \fBstat\fR structure.
61 .sp
62 .LP
63 The \fBfstatat()\fR function obtains file attributes similar to the
64 \fBstat()\fR, \fBlstat()\fR, and \fBfstat()\fR functions. If the \fIpath\fR
65 argument is a relative path, it is resolved relative to the \fIfildes\fR
66 argument rather than the current working directory. If \fIpath\fR is absolute,
67 the \fIfildes\fR argument is unused. If the \fIfildes\fR argument has the
68 special value \fBAT_FDCWD\fR, relative paths are resolved from the current
69 working directory. If \fBAT_SYMLINK_NOFOLLOW\fR is set in the \fIflag\fR
70 argument, the function behaves like \fBlstat()\fR and does not automatically
71 follow symbolic links. See \fBfsattr\fR(5). If \fB_ATTR_TRIGGER\fR is set in
72 the \fIflag\fR argument and the vnode is a trigger mount point, the mount is
73 performed and the function returns the attributes of the root of the mounted
74 filesystem.
75 .sp
76 .LP
77 The \fIbuf\fR argument is a pointer to a \fBstat\fR structure into which
78 information is placed concerning the file. A \fBstat\fR structure includes the
79 following members:
80 .sp
81 .in +2
82 .nf
83 mode_t st_mode; /* File mode (see mknod(2)) */
84 ino_t st_ino; /* Inode number */
85 dev_t st_dev; /* ID of device containing */
86 /* a directory entry for this file */
87 dev_t st_rdev; /* ID of device */
88 /* This entry is defined only for */
89 /* char special or block special files */
90 nlink_t st_nlink; /* Number of links */
91 uid_t st_uid; /* User ID of the file's owner */
92 gid_t st_gid; /* Group ID of the file's group */
93 off_t st_size; /* File size in bytes */
94 time_t st_atime; /* Time of last access */
95 time_t st_mtime; /* Time of last data modification */
96 time_t st_ctime; /* Time of last file status change */
97 /* Times measured in seconds since */
98 /* 00:00:00 UTC, Jan. 1, 1970 */
99 long st_blksize; /* Preferred I/O block size */
100 blkcnt_t st_blocks; /* Number of 512 byte blocks allocated*/
101 char st_fstype[_ST_FSTYPSZ];
102 /* Null-terminated type of filesystem */
103 .fi
104 .in -2
106 .sp
107 .LP
108 Descriptions of structure members are as follows:
109 .sp
110 .ne 2
111 .na
112 \fB\fBst_mode\fR\fR
113 .ad
114 .RS 14n
115 The mode of the file as described for the \fBmknod()\fR function. In addition
116 to the modes described on the \fBmknod\fR(2) manual page, the mode of a file
117 can also be \fBS_IFSOCK\fR if the file is a socket, \fBS_IFDOOR\fR if the file
118 is a door, \fBS_IFPORT\fR if the file is an event port, or \fBS_IFLNK\fR if the
119 file is a symbolic link. \fBS_IFLNK\fR can be returned either by \fBlstat()\fR
120 or by \fBfstat()\fR when the \fBAT_SYMLINK_NOFOLLOW\fR flag is set.
121 .RE
123 .sp
124 .ne 2
125 .na
126 \fB\fBst_ino\fR\fR
127 .ad
128 .RS 14n
129 This field uniquely identifies the file in a given file system. The pair
130 \fBst_ino\fR and \fBst_dev\fR uniquely identifies regular files.
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fB\fBst_dev\fR\fR
137 .ad
138 .RS 14n
139 This field uniquely identifies the file system that contains the file. Its
140 value may be used as input to the \fBustat()\fR function to determine more
141 information about this file system. No other meaning is associated with this
142 value.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBst_rdev\fR\fR
149 .ad
150 .RS 14n
151 This field should be used only by administrative commands. It is valid only for
152 block special or character special files and only has meaning on the system
153 where the file was configured.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBst_nlink\fR\fR
160 .ad
161 .RS 14n
162 This field should be used only by administrative commands.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fBst_uid\fR\fR
169 .ad
170 .RS 14n
171 The user \fBID\fR of the file's owner.
172 .RE
174 .sp
175 .ne 2
176 .na
177 \fB\fBst_gid\fR\fR
178 .ad
179 .RS 14n
180 The group \fBID\fR of the file's group.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fBst_size\fR\fR
187 .ad
188 .RS 14n
189 For regular files, this is the address of the end of the file. For block
190 special or character special, this is not defined. See also \fBpipe\fR(2).
191 .RE
193 .sp
194 .ne 2
195 .na
196 \fB\fBst_atime\fR\fR
197 .ad
198 .RS 14n
199 Time when file data was last accessed. Some of the functions that change this
200 member are: \fBcreat()\fR, \fBmknod()\fR, \fBpipe()\fR, \fButime\fR(2), and
201 \fBread\fR(2).
202 .RE
204 .sp
205 .ne 2
206 .na
207 \fB\fBst_mtime\fR\fR
208 .ad
209 .RS 14n
210 Time when data was last modified. Some of the functions that change this member
211 are: \fBcreat()\fR, \fBmknod()\fR, \fBpipe()\fR, \fButime()\fR, and
212 \fBwrite\fR(2).
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fBst_ctime\fR\fR
219 .ad
220 .RS 14n
221 Time when file status was last changed. Some of the functions that change this
222 member are: \fBchmod\fR(2), \fBchown\fR(2), \fBcreat\fR(2), \fBlink\fR(2),
223 \fBmknod\fR(2), \fBpipe\fR(2), \fBrename\fR(2), \fBunlink\fR(2),
224 \fButime\fR(2), and \fBwrite\fR(2).
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fBst_blksize\fR\fR
231 .ad
232 .RS 14n
233 A hint as to the "best" unit size for I/O operations. This field is not defined
234 for block special or character special files.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fBst_blocks\fR\fR
241 .ad
242 .RS 14n
243 The total number of physical blocks of size 512 bytes actually allocated on
244 disk. This field is not defined for block special or character special files.
245 .RE
247 .sp
248 .ne 2
249 .na
250 \fB\fBst_fstype\fR\fR
251 .ad
252 .RS 14n
253 A null-teminated string that uniquely identifies the type of the filesystem
254 that contains the file.
255 .RE
257 .SH RETURN VALUES
258 .sp
259 .LP
260 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
261 returned and \fBerrno\fR is set to indicate the error.
262 .SH ERRORS
263 .sp
264 .LP
265 The \fBstat()\fR, \fBfstat()\fR, \fBlstat()\fR, and \fBfstatat()\fR functions
266 will fail if:
267 .sp
268 .ne 2
269 .na
270 \fB\fBEIO\fR\fR
271 .ad
272 .RS 13n
273 An error occurred while reading from the file system.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fBEOVERFLOW\fR\fR
280 .ad
281 .RS 13n
282 The file size in bytes or the number of blocks allocated to the file or the
283 file serial number cannot be represented correctly in the structure pointed to
284 by \fIbuf\fR.
285 .RE
287 .sp
288 .LP
289 The \fBstat()\fR, \fBlstat()\fR, and \fBfstatat()\fR functions will fail if:
290 .sp
291 .ne 2
292 .na
293 \fB\fBEACCES\fR\fR
294 .ad
295 .RS 16n
296 Search permission is denied for a component of the path prefix.
297 .RE
299 .sp
300 .ne 2
301 .na
302 \fB\fBEFAULT\fR\fR
303 .ad
304 .RS 16n
305 The \fIbuf\fR or \fIpath\fR argument points to an illegal address.
306 .RE
308 .sp
309 .ne 2
310 .na
311 \fB\fBEINTR\fR\fR
312 .ad
313 .RS 16n
314 A signal was caught during the execution of the \fBstat()\fR or \fBlstat()\fR
315 function.
316 .RE
318 .sp
319 .ne 2
320 .na
321 \fB\fBELOOP\fR\fR
322 .ad
323 .RS 16n
324 A loop exists in symbolic links encountered during the resolution of the
325 \fIpath\fR argument.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fBENAMETOOLONG\fR\fR
332 .ad
333 .RS 16n
334 The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR}, or the length
335 of a \fIpath\fR component exceeds {\fBNAME_MAX\fR} while \fB_POSIX_NO_TRUNC\fR
336 is in effect.
337 .RE
339 .sp
340 .ne 2
341 .na
342 \fB\fBENOENT\fR\fR
343 .ad
344 .RS 16n
345 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
346 empty string.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fBENOLINK\fR\fR
353 .ad
354 .RS 16n
355 The \fIpath\fR argument points to a remote machine and the link to that machine
356 is no longer active.
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBENOTDIR\fR\fR
363 .ad
364 .RS 16n
365 A component of the path prefix is not a directory, or the \fIfildes\fR argument
366 does not refer to a valid directory when given a non-null relative path.
367 .RE
369 .sp
370 .LP
371 The \fBfstat()\fR and \fBfstatat()\fR functions will fail if:
372 .sp
373 .ne 2
374 .na
375 \fB\fBEBADF\fR\fR
376 .ad
377 .RS 11n
378 The \fIfildes\fR argument is not a valid open file descriptor. The \fIfildes\fR
379 argument to \fBfstatat()\fR can also have the valid value of \fBAT_FDCWD\fR.
380 .RE
382 .sp
383 .ne 2
384 .na
385 \fB\fBEFAULT\fR\fR
386 .ad
387 .RS 11n
388 The \fIbuf\fR argument points to an illegal address.
389 .RE
391 .sp
392 .ne 2
393 .na
394 \fB\fBEINTR\fR\fR
395 .ad
396 .RS 11n
397 A signal was caught during the execution of the \fBfstat()\fR function.
398 .RE
400 .sp
401 .ne 2
402 .na
403 \fB\fBENOLINK\fR\fR
404 .ad
405 .RS 11n
406 The \fIfildes\fR argument points to a remote machine and the link to that
407 machine is no longer active.
408 .RE
410 .sp
411 .LP
412 The \fBstat()\fR, \fBfstat()\fR, and \fBlstat()\fR functions may fail if:
413 .sp
414 .ne 2
415 .na
416 \fB\fBEOVERFLOW\fR\fR
417 .ad
418 .RS 13n
419 One of the members is too large to store in the \fBstat\fR structure pointed to
420 by \fIbuf\fR.
421 .RE
423 .sp
424 .LP
425 The \fBstat()\fR and \fBlstat()\fR functions may fail if:
426 .sp
427 .ne 2
428 .na
429 \fB\fBELOOP\fR\fR
430 .ad
431 .RS 16n
432 More than {\fBSYMLOOP_MAX\fR} symbolic links were encountered during the
433 resolution of the \fIpath\fR argument.
434 .RE
436 .sp
437 .ne 2
438 .na
439 \fB\fBENAMETOOLONG\fR\fR
440 .ad
441 .RS 16n
442 As a result of encountering a symbolic link in resolution of the\fIpath\fR
443 argument, the length of the substituted pathname strings exceeds
444 {\fBPATH_MAX\fR}.
445 .RE
447 .sp
448 .LP
449 The \fBstat()\fR and \fBfstatat()\fR functions may fail if:
450 .sp
451 .ne 2
452 .na
453 \fB\fBENXIO\fR\fR
454 .ad
455 .RS 9n
456 The \fIpath\fR argument names a character or block device special file and the
457 corresponding I/O device has been retired by the fault management framework.
458 .RE
460 .SH EXAMPLES
461 .LP
462 \fBExample 1 \fRUse \fBstat()\fR to obtain file status information.
463 .sp
464 .LP
465 The following example shows how to obtain file status information for a file
466 named \fB/home/cnd/mod1\fR. The structure variable buffer is defined for the
467 \fBstat\fR structure.
469 .sp
470 .in +2
471 .nf
472 #include <sys/types.h>
473 #include <sys/stat.h>
474 #include <fcntl.h>
475 struct stat buffer;
476 int status;
477 \&...
478 status = stat("/home/cnd/mod1", &buffer);
479 .fi
480 .in -2
482 .LP
483 \fBExample 2 \fRUse \fBstat()\fR to get directory information.
484 .sp
485 .LP
486 The following example fragment gets status information for each entry in a
487 directory. The call to the \fBstat()\fR function stores file information in the
488 \fBstat\fR structure pointed to by \fIstatbuf\fR. The lines that follow the
489 \fBstat()\fR call format the fields in the \fBstat\fR structure for
490 presentation to the user of the program.
492 .sp
493 .in +2
494 .nf
495 #include <sys/types.h>
496 #include <sys/stat.h>
497 #include <dirent.h>
498 #include <pwd.h>
499 #include <grp.h>
500 #include <time.h>
501 #include <locale.h>
502 #include <langinfo.h>
503 #include <stdio.h>
504 #include <stdint.h>
505 struct dirent *dp;
506 struct stat statbuf;
507 struct passwd *pwd;
508 struct group *grp;
509 struct tm *tm;
510 char datestring[256];
511 \&...
512 /* Loop through directory entries */
513 while ((dp = readdir(dir)) != NULL) {
514 /* Get entry's information. */
515 if (stat(dp->d_name, &statbuf) == -1)
516 continue;
518 /* Print out type, permissions, and number of links. */
519 printf("%10.10s", sperm (statbuf.st_mode));
520 printf("%4d", statbuf.st_nlink);
522 /* Print out owners name if it is found using getpwuid(). */
523 if ((pwd = getpwuid(statbuf.st_uid)) != NULL)
524 printf(" %-8.8s", pwd->pw_name);
525 else
526 printf(" %-8d", statbuf.st_uid);
528 /* Print out group name if it's found using getgrgid(). */
529 if ((grp = getgrgid(statbuf.st_gid)) != NULL)
530 printf(" %-8.8s", grp->gr_name);
531 else
532 printf(" %-8d", statbuf.st_gid);
534 /* Print size of file. */
535 printf(" %9jd", (intmax_t)statbuf.st_size);
536 tm = localtime(&statbuf.st_mtime);
538 /* Get localized date string. */
539 strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm);
541 printf(" %s %s\en", datestring, dp->d_name);
542 }
543 .fi
544 .in -2
546 .LP
547 \fBExample 3 \fRUse \fBfstat()\fR to obtain file status information.
548 .sp
549 .LP
550 The following example shows how to obtain file status information for a file
551 named \fB/home/cnd/mod1\fR. The structure variable buffer is defined for the
552 \fBstat\fR structure. The \fB/home/cnd/mod1 file\fR is opened with read/write
553 privileges and is passed to the open file descriptor \fIfildes\fR.
555 .sp
556 .in +2
557 .nf
558 #include <sys/types.h>
559 #include <sys/stat.h>
560 #include <fcntl.h>
561 struct stat buffer;
562 int status;
563 \&...
564 fildes = open("/home/cnd/mod1", O_RDWR);
565 status = fstat(fildes, &buffer);
566 .fi
567 .in -2
569 .LP
570 \fBExample 4 \fRUse \fBlstat()\fR to obtain symbolic link status information.
571 .sp
572 .LP
573 The following example shows how to obtain status information for a symbolic
574 link named \fB/modules/pass1\fR. The structure variable buffer is defined for
575 the \fBstat\fR structure. If the \fIpath\fR argument specified the filename for
576 the file pointed to by the symbolic link (\fB/home/cnd/mod1\fR), the results of
577 calling the function would be the same as those returned by a call to the
578 \fBstat()\fR function.
580 .sp
581 .in +2
582 .nf
583 #include <sys/stat.h>
584 struct stat buffer;
585 int status;
586 \&...
587 status = lstat("/modules/pass1", &buffer);
588 .fi
589 .in -2
591 .SH USAGE
592 .sp
593 .LP
594 If \fBchmod()\fR or \fBfchmod()\fR is used to change the file group owner
595 permissions on a file with non-trivial ACL entries, only the ACL mask is set to
596 the new permissions and the group owner permission bits in the file's mode
597 field (defined in \fBmknod\fR(2)) are unchanged. A non-trivial ACL entry is
598 one whose meaning cannot be represented in the file's mode field alone. The new
599 ACL mask permissions might change the effective permissions for additional
600 users and groups that have ACL entries on the file.
601 .sp
602 .LP
603 The \fBstat()\fR, \fBfstat()\fR, and \fBlstat()\fR functions have transitional
604 interfaces for 64-bit file offsets. See \fBlf64\fR(5).
605 .SH ATTRIBUTES
606 .sp
607 .LP
608 See \fBattributes\fR(5) for descriptions of the following attributes:
609 .sp
611 .sp
612 .TS
613 box;
614 c | c
615 l | l .
616 ATTRIBUTE TYPE ATTRIBUTE VALUE
617 _
618 Interface Stability Committed
619 _
620 MT-Level Async-Signal-Safe
621 _
622 Standard See below.
623 .TE
625 .sp
626 .LP
627 For \fBstat()\fR, \fBfstat()\fR, and \fBlstat()\fR, see \fBstandards\fR(5).
628 .SH SEE ALSO
629 .sp
630 .LP
631 \fBaccess\fR(2), \fBchmod\fR(2), \fBchown\fR(2), \fBcreat\fR(2), \fBlink\fR(2),
632 \fBmknod\fR(2), \fBpipe\fR(2), \fBread\fR(2), \fBtime\fR(2), \fBunlink\fR(2),
633 \fButime\fR(2), \fBwrite\fR(2), \fBfattach\fR(3C), \fBstat.h\fR(3HEAD),
634 \fBattributes\fR(5), \fBfsattr\fR(5), \fBlf64\fR(5), \fBstandards\fR(5)