| blob | 7fe8baffc184098767f94e93d3d3fa6ac7c7cf77 |
1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
2 .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
3 .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Modified by Michael Haardt <michael@moria.de>
8 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
9 .\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org>
10 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
11 .\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk>
12 .\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
13 .\" Modified 1999-07-06 by aeb & Albert Cahalan
14 .\" Modified 2000-01-07 by aeb
15 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
16 .\" 2007-06-08 mtk: Added example program
17 .\" 2007-07-05 mtk: Added details on underlying system call interfaces
18 .\"
19 .TH STAT 2 2021-08-27 "Linux" "Linux Programmer's Manual"
20 .SH NAME
21 stat, fstat, lstat, fstatat \- get file status
22 .SH LIBRARY
23 Standard C library
24 .RI ( libc ", " \-lc )
25 .SH SYNOPSIS
26 .nf
27 .B #include <sys/stat.h>
28 .PP
29 .BI "int stat(const char *restrict " pathname ,
30 .BI " struct stat *restrict " statbuf );
31 .BI "int fstat(int " fd ", struct stat *" statbuf );
32 .BI "int lstat(const char *restrict " pathname ,
33 .BI " struct stat *restrict " statbuf );
34 .PP
35 .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
36 .B #include <sys/stat.h>
37 .PP
38 .BI "int fstatat(int " dirfd ", const char *restrict " pathname ,
39 .BI " struct stat *restrict " statbuf ", int " flags );
40 .fi
41 .PP
42 .RS -4
43 Feature Test Macro Requirements for glibc (see
44 .BR feature_test_macros (7)):
45 .RE
46 .PP
47 .BR lstat ():
48 .nf
49 /* Since glibc 2.20 */ _DEFAULT_SOURCE
50 || _XOPEN_SOURCE >= 500
51 .\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
52 || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
53 || /* Glibc 2.19 and earlier */ _BSD_SOURCE
54 .fi
55 .PP
56 .BR fstatat ():
57 .nf
58 Since glibc 2.10:
59 _POSIX_C_SOURCE >= 200809L
60 Before glibc 2.10:
61 _ATFILE_SOURCE
62 .fi
63 .SH DESCRIPTION
64 These functions return information about a file, in the buffer pointed to by
65 .IR statbuf .
66 No permissions are required on the file itself, but\(emin the case of
67 .BR stat (),
68 .BR fstatat (),
69 and
70 .BR lstat ()\(emexecute
71 (search) permission is required on all of the directories in
72 .I pathname
73 that lead to the file.
74 .PP
75 .BR stat ()
76 and
77 .BR fstatat ()
78 retrieve information about the file pointed to by
79 .IR pathname ;
80 the differences for
81 .BR fstatat ()
82 are described below.
83 .PP
84 .BR lstat ()
85 is identical to
86 .BR stat (),
87 except that if
88 .I pathname
89 is a symbolic link, then it returns information about the link itself,
90 not the file that the link refers to.
91 .PP
92 .BR fstat ()
93 is identical to
94 .BR stat (),
95 except that the file about which information is to be retrieved
96 is specified by the file descriptor
97 .IR fd .
98 .\"
99 .SS The stat structure
100 All of these system calls return a
101 .I stat
102 structure (see
103 .BR stat (3type)).
104 .PP
105 .\" Background: inode attributes are modified with i_mutex held, but
106 .\" read by stat() without taking the mutex.
107 .IR Note :
108 for performance and simplicity reasons, different fields in the
109 .I stat
110 structure may contain state information from different moments
111 during the execution of the system call.
112 For example, if
113 .I st_mode
114 or
115 .I st_uid
116 is changed by another process by calling
117 .BR chmod (2)
118 or
119 .BR chown (2),
120 .BR stat ()
121 might return the old
122 .I st_mode
123 together with the new
124 .IR st_uid ,
125 or the old
126 .I st_uid
127 together with the new
128 .IR st_mode .
129 .SS fstatat()
130 The
131 .BR fstatat ()
132 system call is a more general interface for accessing file information
133 which can still provide exactly the behavior of each of
134 .BR stat (),
135 .BR lstat (),
136 and
137 .BR fstat ().
138 .PP
139 If the pathname given in
140 .I pathname
141 is relative, then it is interpreted relative to the directory
142 referred to by the file descriptor
143 .I dirfd
144 (rather than relative to the current working directory of
145 the calling process, as is done by
146 .BR stat ()
147 and
148 .BR lstat ()
149 for a relative pathname).
150 .PP
151 If
152 .I pathname
153 is relative and
154 .I dirfd
155 is the special value
156 .BR AT_FDCWD ,
157 then
158 .I pathname
159 is interpreted relative to the current working
160 directory of the calling process (like
161 .BR stat ()
162 and
163 .BR lstat ()).
164 .PP
165 If
166 .I pathname
167 is absolute, then
168 .I dirfd
169 is ignored.
170 .PP
171 .I flags
172 can either be 0, or include one or more of the following flags ORed:
173 .TP
174 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
175 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
176 If
177 .I pathname
178 is an empty string, operate on the file referred to by
179 .I dirfd
180 (which may have been obtained using the
181 .BR open (2)
182 .B O_PATH
183 flag).
184 In this case,
185 .I dirfd
186 can refer to any type of file, not just a directory, and
187 the behavior of
188 .BR fstatat ()
189 is similar to that of
190 .BR fstat ().
191 If
192 .I dirfd
193 is
194 .BR AT_FDCWD ,
195 the call operates on the current working directory.
196 This flag is Linux-specific; define
197 .B _GNU_SOURCE
198 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
199 to obtain its definition.
200 .TP
201 .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
202 Don't automount the terminal ("basename") component of
203 .I pathname.
204 Since Linux 3.1 this flag is ignored.
205 Since Linux 4.11 this flag is implied.
206 .TP
207 .B AT_SYMLINK_NOFOLLOW
208 If
209 .I pathname
210 is a symbolic link, do not dereference it:
211 instead return information about the link itself, like
212 .BR lstat ().
213 (By default,
214 .BR fstatat ()
215 dereferences symbolic links, like
216 .BR stat ().)
217 .PP
218 See
219 .BR openat (2)
220 for an explanation of the need for
221 .BR fstatat ().
222 .SH RETURN VALUE
223 On success, zero is returned.
224 On error, \-1 is returned, and
225 .I errno
226 is set to indicate the error.
227 .SH ERRORS
228 .TP
229 .B EACCES
230 Search permission is denied for one of the directories
231 in the path prefix of
232 .IR pathname .
233 (See also
234 .BR path_resolution (7).)
235 .TP
236 .B EBADF
237 .I fd
238 is not a valid open file descriptor.
239 .TP
240 .B EBADF
241 .RB ( fstatat ())
242 .I pathname
243 is relative but
244 .I dirfd
245 is neither
246 .B AT_FDCWD
247 nor a valid file descriptor.
248 .TP
249 .B EFAULT
250 Bad address.
251 .TP
252 .B EINVAL
253 .RB ( fstatat ())
254 Invalid flag specified in
255 .IR flags .
256 .TP
257 .B ELOOP
258 Too many symbolic links encountered while traversing the path.
259 .TP
260 .B ENAMETOOLONG
261 .I pathname
262 is too long.
263 .TP
264 .B ENOENT
265 A component of
266 .I pathname
267 does not exist or is a dangling symbolic link.
268 .TP
269 .B ENOENT
270 .I pathname
271 is an empty string and
272 .B AT_EMPTY_PATH
273 was not specified in
274 .IR flags .
275 .TP
276 .B ENOMEM
277 Out of memory (i.e., kernel memory).
278 .TP
279 .B ENOTDIR
280 A component of the path prefix of
281 .I pathname
282 is not a directory.
283 .TP
284 .B ENOTDIR
285 .RB ( fstatat ())
286 .I pathname
287 is relative and
288 .I dirfd
289 is a file descriptor referring to a file other than a directory.
290 .TP
291 .B EOVERFLOW
292 .I pathname
293 or
294 .I fd
295 refers to a file whose size, inode number,
296 or number of blocks cannot be represented in, respectively, the types
297 .IR off_t ,
298 .IR ino_t ,
299 or
300 .IR blkcnt_t .
301 This error can occur when, for example,
302 an application compiled on a 32-bit platform without
303 .I \-D_FILE_OFFSET_BITS=64
304 calls
305 .BR stat ()
306 on a file whose size exceeds
307 .I (1<<31)\-1
308 bytes.
309 .SH VERSIONS
310 .BR fstatat ()
311 was added to Linux in kernel 2.6.16;
312 library support was added to glibc in version 2.4.
313 .SH STANDARDS
314 .BR stat (),
315 .BR fstat (),
316 .BR lstat ():
317 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
318 .\" SVr4 documents additional
319 .\" .BR fstat ()
320 .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
321 .\" documents additional
322 .\" .BR stat ()
323 .\" and
324 .\" .BR lstat ()
325 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
326 .PP
327 .BR fstatat ():
328 POSIX.1-2008.
329 .PP
330 According to POSIX.1-2001,
331 .BR lstat ()
332 on a symbolic link need return valid information only in the
333 .I st_size
334 field and the file type of the
335 .I st_mode
336 field of the
337 .I stat
338 structure.
339 POSIX.1-2008 tightens the specification, requiring
340 .BR lstat ()
341 to return valid information in all fields except the mode bits in
342 .IR st_mode .
343 .PP
344 Use of the
345 .I st_blocks
346 and
347 .I st_blksize
348 fields may be less portable.
349 (They were introduced in BSD.
350 The interpretation differs between systems,
351 and possibly on a single system when NFS mounts are involved.)
352 .SH NOTES
353 .SS C library/kernel differences
354 Over time, increases in the size of the
355 .I stat
356 structure have led to three successive versions of
357 .BR stat ():
358 .IR sys_stat ()
359 (slot
360 .IR __NR_oldstat ),
361 .IR sys_newstat ()
362 (slot
363 .IR __NR_stat ),
364 and
365 .I sys_stat64()
366 (slot
367 .IR __NR_stat64 )
368 on 32-bit platforms such as i386.
369 The first two versions were already present in Linux 1.0
370 (albeit with different names);
371 .\" See include/asm-i386/stat.h in the Linux 2.4 source code for the
372 .\" various versions of the structure definitions
373 the last was added in Linux 2.4.
374 Similar remarks apply for
375 .BR fstat ()
376 and
377 .BR lstat ().
378 .PP
379 The kernel-internal versions of the
380 .I stat
381 structure dealt with by the different versions are, respectively:
382 .TP
383 .I __old_kernel_stat
384 The original structure, with rather narrow fields, and no padding.
385 .TP
386 .I stat
387 Larger
388 .I st_ino
389 field and padding added to various parts of the structure to
390 allow for future expansion.
391 .TP
392 .I stat64
393 Even larger
394 .I st_ino
395 field,
396 larger
397 .I st_uid
398 and
399 .I st_gid
400 fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits,
401 and various other enlarged fields and further padding in the structure.
402 (Various padding bytes were eventually consumed in Linux 2.6,
403 with the advent of 32-bit device IDs and nanosecond components
404 for the timestamp fields.)
405 .PP
406 The glibc
407 .BR stat ()
408 wrapper function hides these details from applications,
409 invoking the most recent version of the system call provided by the kernel,
410 and repacking the returned information if required for old binaries.
411 .\"
412 .\" A note from Andries Brouwer, July 2007
413 .\"
414 .\" > Is the story not rather more complicated for some calls like
415 .\" > stat(2)?
416 .\"
417 .\" Yes and no, mostly no. See /usr/include/sys/stat.h .
418 .\"
419 .\" The idea is here not so much that syscalls change, but that
420 .\" the definitions of struct stat and of the types dev_t and mode_t change.
421 .\" This means that libc (even if it does not call the kernel
422 .\" but only calls some internal function) must know what the
423 .\" format of dev_t or of struct stat is.
424 .\" The communication between the application and libc goes via
425 .\" the include file <sys/stat.h> that defines a _STAT_VER and
426 .\" _MKNOD_VER describing the layout of the data that user space
427 .\" uses. Each (almost each) occurrence of stat() is replaced by
428 .\" an occurrence of xstat() where the first parameter of xstat()
429 .\" is this version number _STAT_VER.
430 .\"
431 .\" Now, also the definitions used by the kernel change.
432 .\" But glibc copes with this in the standard way, and the
433 .\" struct stat as returned by the kernel is repacked into
434 .\" the struct stat as expected by the application.
435 .\" Thus, _STAT_VER and this setup cater for the application-libc
436 .\" interface, rather than the libc-kernel interface.
437 .\"
438 .\" (Note that the details depend on gcc being used as c compiler.)
439 .PP
440 On modern 64-bit systems, life is simpler: there is a single
441 .BR stat ()
442 system call and the kernel deals with a
443 .I stat
444 structure that contains fields of a sufficient size.
445 .PP
446 The underlying system call employed by the glibc
447 .BR fstatat ()
448 wrapper function is actually called
449 .BR fstatat64 ()
450 or, on some architectures,
451 .\" strace(1) shows the name "newfstatat" on x86-64
452 .BR newfstatat ().
453 .SH EXAMPLES
454 The following program calls
455 .BR lstat ()
456 and displays selected fields in the returned
457 .I stat
458 structure.
459 .PP
460 .\" SRC BEGIN (stat.c)
461 .EX
462 #include <stdint.h>
463 #include <stdio.h>
464 #include <stdlib.h>
465 #include <sys/stat.h>
466 #include <sys/sysmacros.h>
467 #include <time.h>
469 int
470 main(int argc, char *argv[])
471 {
472 struct stat sb;
474 if (argc != 2) {
475 fprintf(stderr, "Usage: %s <pathname>\en", argv[0]);
476 exit(EXIT_FAILURE);
477 }
479 if (lstat(argv[1], &sb) == \-1) {
480 perror("lstat");
481 exit(EXIT_FAILURE);
482 }
484 printf("ID of containing device: [%jx,%jx]\en",
485 (uintmax_t) major(sb.st_dev),
486 (uintmax_t) minor(sb.st_dev));
488 printf("File type: ");
490 switch (sb.st_mode & S_IFMT) {
491 case S_IFBLK: printf("block device\en"); break;
492 case S_IFCHR: printf("character device\en"); break;
493 case S_IFDIR: printf("directory\en"); break;
494 case S_IFIFO: printf("FIFO/pipe\en"); break;
495 case S_IFLNK: printf("symlink\en"); break;
496 case S_IFREG: printf("regular file\en"); break;
497 case S_IFSOCK: printf("socket\en"); break;
498 default: printf("unknown?\en"); break;
499 }
501 printf("I\-node number: %ju\en", (uintmax_t) sb.st_ino);
503 printf("Mode: %jo (octal)\en",
504 (uintmax_t) sb.st_mode);
506 printf("Link count: %ju\en", (uintmax_t) sb.st_nlink);
507 printf("Ownership: UID=%ju GID=%ju\en",
508 (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);
510 printf("Preferred I/O block size: %jd bytes\en",
511 (intmax_t) sb.st_blksize);
512 printf("File size: %jd bytes\en",
513 (intmax_t) sb.st_size);
514 printf("Blocks allocated: %jd\en",
515 (intmax_t) sb.st_blocks);
517 printf("Last status change: %s", ctime(&sb.st_ctime));
518 printf("Last file access: %s", ctime(&sb.st_atime));
519 printf("Last file modification: %s", ctime(&sb.st_mtime));
521 exit(EXIT_SUCCESS);
522 }
523 .EE
524 .\" SRC END
525 .SH SEE ALSO
526 .BR ls (1),
527 .BR stat (1),
528 .BR access (2),
529 .BR chmod (2),
530 .BR chown (2),
531 .BR readlink (2),
532 .BR statx (2),
533 .BR utime (2),
534 .BR stat (3type),
535 .BR capabilities (7),
536 .BR inode (7),
537 .BR symlink (7)