Debian Codegraph @

upstream/fedora-44/man2/stat.2

raw
1 .\" Copyright (c) 1992 Drew Eckhardt ([email protected]), March 28, 1992
2 .\" Parts Copyright (c) 1995 Nicolai Langfeldt ([email protected]), 1/1/95
3 .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Modified by Michael Haardt <[email protected]>
8 .\" Modified 1993-07-24 by Rik Faith <[email protected]>
9 .\" Modified 1995-05-18 by Todd Larason <[email protected]>
10 .\" Modified 1997-01-31 by Eric S. Raymond <[email protected]>
11 .\" Modified 1995-01-09 by Richard Kettlewell <[email protected]>
12 .\" Modified 1998-05-13 by Michael Haardt <[email protected]>
13 .\" Modified 1999-07-06 by aeb & Albert Cahalan
14 .\" Modified 2000-01-07 by aeb
15 .\" Modified 2004-06-23 by Michael Kerrisk <[email protected]>
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 2025-01-09 "Linux man-pages 6.13"
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 .P
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 .P
35 .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
36 .B #include <sys/stat.h>
37 .P
38 .BI "int fstatat(int " dirfd ", const char *restrict " pathname ,
39 .BI " struct stat *restrict " statbuf ", int " flags );
40 .fi
41 .P
42 .RS -4
43 Feature Test Macro Requirements for glibc (see
44 .BR feature_test_macros (7)):
45 .RE
46 .P
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 .P
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\[em]in the case of
67 .BR stat (),
68 .BR fstatat (),
69 and
70 .BR lstat ()\[em]execute
71 (search) permission is required on all of the directories in
72 .I pathname
73 that lead to the file.
74 .P
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 .P
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 .P
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 .P
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 .P
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 .P
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 .P
165 If
166 .I pathname
167 is absolute, then
168 .I dirfd
169 is ignored.
170 .P
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
179 (or NULL, since Linux 6.11)
180 operate on the file referred to by
181 .I dirfd
182 (which may have been obtained using the
183 .BR open (2)
184 .B O_PATH
185 flag).
186 In this case,
187 .I dirfd
188 can refer to any type of file, not just a directory, and
189 the behavior of
190 .BR fstatat ()
191 is similar to that of
192 .BR fstat ().
193 If
194 .I dirfd
195 is
196 .BR AT_FDCWD ,
197 the call operates on the current working directory.
198 This flag is Linux-specific; define
199 .B _GNU_SOURCE
200 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
201 to obtain its definition.
202 .TP
203 .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
204 Don't automount the terminal ("basename") component of
205 .I pathname.
206 Since Linux 3.1 this flag is ignored.
207 Since Linux 4.11 this flag is implied.
208 .TP
209 .B AT_SYMLINK_NOFOLLOW
210 If
211 .I pathname
212 is a symbolic link, do not dereference it:
213 instead return information about the link itself, like
214 .BR lstat ().
215 (By default,
216 .BR fstatat ()
217 dereferences symbolic links, like
218 .BR stat ().)
219 .P
220 See
221 .BR openat (2)
222 for an explanation of the need for
223 .BR fstatat ().
224 .SH RETURN VALUE
225 On success, zero is returned.
226 On error, \-1 is returned, and
227 .I errno
228 is set to indicate the error.
229 .SH ERRORS
230 .TP
231 .B EACCES
232 Search permission is denied for one of the directories
233 in the path prefix of
234 .IR pathname .
235 (See also
236 .BR path_resolution (7).)
237 .TP
238 .B EBADF
239 .I fd
240 is not a valid open file descriptor.
241 .TP
242 .B EBADF
243 .RB ( fstatat ())
244 .I pathname
245 is relative but
246 .I dirfd
247 is neither
248 .B AT_FDCWD
249 nor a valid file descriptor.
250 .TP
251 .B EFAULT
252 Bad address.
253 .TP
254 .B EINVAL
255 .RB ( fstatat ())
256 Invalid flag specified in
257 .IR flags .
258 .TP
259 .B ELOOP
260 Too many symbolic links encountered while traversing the path.
261 .TP
262 .B ENAMETOOLONG
263 .I pathname
264 is too long.
265 .TP
266 .B ENOENT
267 A component of
268 .I pathname
269 does not exist or is a dangling symbolic link.
270 .TP
271 .B ENOENT
272 .I pathname
273 is an empty string and
274 .B AT_EMPTY_PATH
275 was not specified in
276 .IR flags .
277 .TP
278 .B ENOMEM
279 Out of memory (i.e., kernel memory).
280 .TP
281 .B ENOTDIR
282 A component of the path prefix of
283 .I pathname
284 is not a directory.
285 .TP
286 .B ENOTDIR
287 .RB ( fstatat ())
288 .I pathname
289 is relative and
290 .I dirfd
291 is a file descriptor referring to a file other than a directory.
292 .TP
293 .B EOVERFLOW
294 .I pathname
295 or
296 .I fd
297 refers to a file whose size, inode number,
298 or number of blocks cannot be represented in, respectively, the types
299 .IR off_t ,
300 .IR ino_t ,
301 or
302 .IR blkcnt_t .
303 This error can occur when, for example,
304 an application compiled on a 32-bit platform without
305 .I \-D_FILE_OFFSET_BITS=64
306 calls
307 .BR stat ()
308 on a file whose size exceeds
309 .I (1<<31)\-1
310 bytes.
311 .SH STANDARDS
312 POSIX.1-2008.
313 .SH HISTORY
314 .TP
315 .BR stat ()
316 .TQ
317 .BR fstat ()
318 .TQ
319 .BR lstat ()
320 SVr4, 4.3BSD, POSIX.1-2001.
321 .\" SVr4 documents additional
322 .\" .BR fstat ()
323 .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
324 .\" documents additional
325 .\" .BR stat ()
326 .\" and
327 .\" .BR lstat ()
328 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
329 .TP
330 .BR fstatat ()
331 POSIX.1-2008.
332 Linux 2.6.16,
333 glibc 2.4.
334 .P
335 According to POSIX.1-2001,
336 .BR lstat ()
337 on a symbolic link need return valid information only in the
338 .I st_size
339 field and the file type of the
340 .I st_mode
341 field of the
342 .I stat
343 structure.
344 POSIX.1-2008 tightens the specification, requiring
345 .BR lstat ()
346 to return valid information in all fields except the mode bits in
347 .IR st_mode .
348 .P
349 Use of the
350 .I st_blocks
351 and
352 .I st_blksize
353 fields may be less portable.
354 (They were introduced in BSD.
355 The interpretation differs between systems,
356 and possibly on a single system when NFS mounts are involved.)
357 .SS C library/kernel differences
358 Over time, increases in the size of the
359 .I stat
360 structure have led to three successive versions of
361 .BR stat ():
362 .IR sys_stat ()
363 (slot
364 .IR __NR_oldstat ),
365 .IR sys_newstat ()
366 (slot
367 .IR __NR_stat ),
368 and
369 .I sys_stat64()
370 (slot
371 .IR __NR_stat64 )
372 on 32-bit platforms such as i386.
373 The first two versions were already present in Linux 1.0
374 (albeit with different names);
375 .\" See include/asm-i386/stat.h in the Linux 2.4 source code for the
376 .\" various versions of the structure definitions
377 the last was added in Linux 2.4.
378 Similar remarks apply for
379 .BR fstat ()
380 and
381 .BR lstat ().
382 .P
383 The kernel-internal versions of the
384 .I stat
385 structure dealt with by the different versions are, respectively:
386 .TP
387 .I __old_kernel_stat
388 The original structure, with rather narrow fields, and no padding.
389 .TP
390 .I stat
391 Larger
392 .I st_ino
393 field and padding added to various parts of the structure to
394 allow for future expansion.
395 .TP
396 .I stat64
397 Even larger
398 .I st_ino
399 field,
400 larger
401 .I st_uid
402 and
403 .I st_gid
404 fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits,
405 and various other enlarged fields and further padding in the structure.
406 (Various padding bytes were eventually consumed in Linux 2.6,
407 with the advent of 32-bit device IDs and nanosecond components
408 for the timestamp fields.)
409 .P
410 The glibc
411 .BR stat ()
412 wrapper function hides these details from applications,
413 invoking the most recent version of the system call provided by the kernel,
414 and repacking the returned information if required for old binaries.
415 .\"
416 .\" A note from Andries Brouwer, July 2007
417 .\"
418 .\" > Is the story not rather more complicated for some calls like
419 .\" > stat(2)?
420 .\"
421 .\" Yes and no, mostly no. See /usr/include/sys/stat.h .
422 .\"
423 .\" The idea is here not so much that syscalls change, but that
424 .\" the definitions of struct stat and of the types dev_t and mode_t change.
425 .\" This means that libc (even if it does not call the kernel
426 .\" but only calls some internal function) must know what the
427 .\" format of dev_t or of struct stat is.
428 .\" The communication between the application and libc goes via
429 .\" the include file <sys/stat.h> that defines a _STAT_VER and
430 .\" _MKNOD_VER describing the layout of the data that user space
431 .\" uses. Each (almost each) occurrence of stat() is replaced by
432 .\" an occurrence of xstat() where the first parameter of xstat()
433 .\" is this version number _STAT_VER.
434 .\"
435 .\" Now, also the definitions used by the kernel change.
436 .\" But glibc copes with this in the standard way, and the
437 .\" struct stat as returned by the kernel is repacked into
438 .\" the struct stat as expected by the application.
439 .\" Thus, _STAT_VER and this setup cater for the application-libc
440 .\" interface, rather than the libc-kernel interface.
441 .\"
442 .\" (Note that the details depend on gcc being used as c compiler.)
443 .P
444 On modern 64-bit systems, life is simpler: there is a single
445 .BR stat ()
446 system call and the kernel deals with a
447 .I stat
448 structure that contains fields of a sufficient size.
449 .P
450 The underlying system call employed by the glibc
451 .BR fstatat ()
452 wrapper function is actually called
453 .BR fstatat64 ()
454 or, on some architectures,
455 .\" strace(1) shows the name "newfstatat" on x86-64
456 .BR newfstatat ().
457 .SH EXAMPLES
458 The following program calls
459 .BR lstat ()
460 and displays selected fields in the returned
461 .I stat
462 structure.
463 .P
464 .\" SRC BEGIN (stat.c)
465 .EX
466 #include <stdint.h>
467 #include <stdio.h>
468 #include <stdlib.h>
469 #include <sys/stat.h>
470 #include <sys/sysmacros.h>
471 #include <time.h>
472 \&
473 int
474 main(int argc, char *argv[])
475 {
476 struct stat sb;
477 \&
478 if (argc != 2) {
479 fprintf(stderr, "Usage: %s <pathname>\[rs]n", argv[0]);
480 exit(EXIT_FAILURE);
481 }
482 \&
483 if (lstat(argv[1], &sb) == \-1) {
484 perror("lstat");
485 exit(EXIT_FAILURE);
486 }
487 \&
488 printf("ID of containing device: [%x,%x]\[rs]n",
489 major(sb.st_dev),
490 minor(sb.st_dev));
491 \&
492 printf("File type: ");
493 \&
494 switch (sb.st_mode & S_IFMT) {
495 case S_IFBLK: printf("block device\[rs]n"); break;
496 case S_IFCHR: printf("character device\[rs]n"); break;
497 case S_IFDIR: printf("directory\[rs]n"); break;
498 case S_IFIFO: printf("FIFO/pipe\[rs]n"); break;
499 case S_IFLNK: printf("symlink\[rs]n"); break;
500 case S_IFREG: printf("regular file\[rs]n"); break;
501 case S_IFSOCK: printf("socket\[rs]n"); break;
502 default: printf("unknown?\[rs]n"); break;
503 }
504 \&
505 printf("I\-node number: %ju\[rs]n", (uintmax_t) sb.st_ino);
506 \&
507 printf("Mode: %jo (octal)\[rs]n",
508 (uintmax_t) sb.st_mode);
509 \&
510 printf("Link count: %ju\[rs]n", (uintmax_t) sb.st_nlink);
511 printf("Ownership: UID=%ju GID=%ju\[rs]n",
512 (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);
513 \&
514 printf("Preferred I/O block size: %jd bytes\[rs]n",
515 (intmax_t) sb.st_blksize);
516 printf("File size: %jd bytes\[rs]n",
517 (intmax_t) sb.st_size);
518 printf("Blocks allocated: %jd\[rs]n",
519 (intmax_t) sb.st_blocks);
520 \&
521 printf("Last status change: %s", ctime(&sb.st_ctime));
522 printf("Last file access: %s", ctime(&sb.st_atime));
523 printf("Last file modification: %s", ctime(&sb.st_mtime));
524 \&
525 exit(EXIT_SUCCESS);
526 }
527 .EE
528 .\" SRC END
529 .SH SEE ALSO
530 .BR ls (1),
531 .BR stat (1),
532 .BR access (2),
533 .BR chmod (2),
534 .BR chown (2),
535 .BR readlink (2),
536 .BR statx (2),
537 .BR utime (2),
538 .BR stat (3type),
539 .BR capabilities (7),
540 .BR inode (7),
541 .BR symlink (7)