man2/stat.2

   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 man-pages (unreleased)" "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>
 468
 469 int
 470 main(int argc, char *argv[])
 471 {
 472     struct stat sb;
 473
 474     if (argc != 2) {
 475         fprintf(stderr, "Usage: %s <pathname>\en", argv[0]);
 476         exit(EXIT_FAILURE);
 477     }
 478
 479     if (lstat(argv[1], &sb) == \-1) {
 480         perror("lstat");
 481         exit(EXIT_FAILURE);
 482     }
 483
 484     printf("ID of containing device:  [%jx,%jx]\en",
 485            (uintmax_t) major(sb.st_dev),
 486            (uintmax_t) minor(sb.st_dev));
 487
 488     printf("File type:                ");
 489
 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     }
 500
 501     printf("I\-node number:            %ju\en", (uintmax_t) sb.st_ino);
 502
 503     printf("Mode:                     %jo (octal)\en",
 504            (uintmax_t) sb.st_mode);
 505
 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);
 509
 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);
 516
 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));
 520
 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)