Debian Codegraph @

upstream/debian-unstable/man2/stat.2

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