man2/statx.2

   1 .\" Copyright (c) 2017 David Howells <dhowells@redhat.com>
   2 .\"
   3 .\" Derived from the stat.2 manual page:
   4 .\"   Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   5 .\"   Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
   6 .\"   and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   7 .\"
   8 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   9 .\"
  10 .TH STATX 2 2021-08-27 "Linux" "Linux Programmer's Manual"
  11 .SH NAME
  12 statx \- get file status (extended)
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
  19 .B #include <sys/stat.h>
  20 .PP
  21 .BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags ,
  22 .BI "          unsigned int " mask ", struct statx *restrict " statxbuf );
  23 .fi
  24 .SH DESCRIPTION
  25 This function returns information about a file, storing it in the buffer
  26 pointed to by
  27 .IR statxbuf .
  28 The returned buffer is a structure of the following type:
  29 .PP
  30 .in +4n
  31 .EX
  32 struct statx {
  33     __u32 stx_mask;        /* Mask of bits indicating
  34                               filled fields */
  35     __u32 stx_blksize;     /* Block size for filesystem I/O */
  36     __u64 stx_attributes;  /* Extra file attribute indicators */
  37     __u32 stx_nlink;       /* Number of hard links */
  38     __u32 stx_uid;         /* User ID of owner */
  39     __u32 stx_gid;         /* Group ID of owner */
  40     __u16 stx_mode;        /* File type and mode */
  41     __u64 stx_ino;         /* Inode number */
  42     __u64 stx_size;        /* Total size in bytes */
  43     __u64 stx_blocks;      /* Number of 512B blocks allocated */
  44     __u64 stx_attributes_mask;
  45                            /* Mask to show what\(aqs supported
  46                               in stx_attributes */
  47
  48     /* The following fields are file timestamps */
  49     struct statx_timestamp stx_atime;  /* Last access */
  50     struct statx_timestamp stx_btime;  /* Creation */
  51     struct statx_timestamp stx_ctime;  /* Last status change */
  52     struct statx_timestamp stx_mtime;  /* Last modification */
  53
  54     /* If this file represents a device, then the next two
  55        fields contain the ID of the device */
  56     __u32 stx_rdev_major;  /* Major ID */
  57     __u32 stx_rdev_minor;  /* Minor ID */
  58
  59     /* The next two fields contain the ID of the device
  60        containing the filesystem where the file resides */
  61     __u32 stx_dev_major;   /* Major ID */
  62     __u32 stx_dev_minor;   /* Minor ID */
  63     __u64 stx_mnt_id;      /* Mount ID */
  64 };
  65 .EE
  66 .in
  67 .PP
  68 The file timestamps are structures of the following type:
  69 .PP
  70 .in +4n
  71 .EX
  72 struct statx_timestamp {
  73     __s64 tv_sec;    /* Seconds since the Epoch (UNIX time) */
  74     __u32 tv_nsec;   /* Nanoseconds since tv_sec */
  75 };
  76 .EE
  77 .in
  78 .PP
  79 (Note that reserved space and padding is omitted.)
  80 .SS
  81 Invoking \fBstatx\fR():
  82 To access a file's status, no permissions are required on the file itself,
  83 but in the case of
  84 .BR statx ()
  85 with a pathname,
  86 execute (search) permission is required on all of the directories in
  87 .I pathname
  88 that lead to the file.
  89 .PP
  90 .BR statx ()
  91 uses
  92 .IR pathname ,
  93 .IR dirfd ,
  94 and
  95 .I flags
  96 to identify the target file in one of the following ways:
  97 .TP
  98 An absolute pathname
  99 If
 100 .I pathname
 101 begins with a slash,
 102 then it is an absolute pathname that identifies the target file.
 103 In this case,
 104 .I dirfd
 105 is ignored.
 106 .TP
 107 A relative pathname
 108 If
 109 .I pathname
 110 is a string that begins with a character other than a slash and
 111 .I dirfd
 112 is
 113 .BR AT_FDCWD ,
 114 then
 115 .I pathname
 116 is a relative pathname that is interpreted relative to the process's
 117 current working directory.
 118 .TP
 119 A directory-relative pathname
 120 If
 121 .I pathname
 122 is a string that begins with a character other than a slash and
 123 .I dirfd
 124 is a file descriptor that refers to a directory, then
 125 .I pathname
 126 is a relative pathname that is interpreted relative to the directory
 127 referred to by
 128 .IR dirfd .
 129 (See
 130 .BR openat (2)
 131 for an explanation of why this is useful.)
 132 .TP
 133 By file descriptor
 134 If
 135 .I pathname
 136 is an empty string and the
 137 .B AT_EMPTY_PATH
 138 flag is specified in
 139 .I flags
 140 (see below),
 141 then the target file is the one referred to by the file descriptor
 142 .IR dirfd .
 143 .PP
 144 .I flags
 145 can be used to influence a pathname-based lookup.
 146 A value for
 147 .I flags
 148 is constructed by ORing together zero or more of the following constants:
 149 .TP
 150 .B AT_EMPTY_PATH
 151 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 152 If
 153 .I pathname
 154 is an empty string, operate on the file referred to by
 155 .I dirfd
 156 (which may have been obtained using the
 157 .BR open (2)
 158 .B O_PATH
 159 flag).
 160 In this case,
 161 .I dirfd
 162 can refer to any type of file, not just a directory.
 163 .IP
 164 If
 165 .I dirfd
 166 is
 167 .BR AT_FDCWD ,
 168 the call operates on the current working directory.
 169 .IP
 170 This flag is Linux-specific; define
 171 .B _GNU_SOURCE
 172 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
 173 to obtain its definition.
 174 .TP
 175 .B AT_NO_AUTOMOUNT
 176 Don't automount the terminal ("basename") component of
 177 .I pathname
 178 if it is a directory that is an automount point.
 179 This allows the caller to gather attributes of an automount point
 180 (rather than the location it would mount).
 181 This flag has no effect if the mount point has already been mounted over.
 182 .IP
 183 The
 184 .B AT_NO_AUTOMOUNT
 185 flag can be used in tools that scan directories
 186 to prevent mass-automounting of a directory of automount points.
 187 .IP
 188 All of
 189 .BR stat (2),
 190 .BR lstat (2),
 191 and
 192 .BR fstatat (2)
 193 act as though
 194 .B AT_NO_AUTOMOUNT
 195 was set.
 196 .IP
 197 This flag is Linux-specific; define
 198 .B _GNU_SOURCE
 199 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
 200 to obtain its definition.
 201 .TP
 202 .B AT_SYMLINK_NOFOLLOW
 203 If
 204 .I pathname
 205 is a symbolic link, do not dereference it:
 206 instead return information about the link itself, like
 207 .BR lstat (2).
 208 .PP
 209 .I flags
 210 can also be used to control what sort of synchronization the kernel will do
 211 when querying a file on a remote filesystem.
 212 This is done by ORing in one of the following values:
 213 .TP
 214 .B AT_STATX_SYNC_AS_STAT
 215 Do whatever
 216 .BR stat (2)
 217 does.
 218 This is the default and is very much filesystem-specific.
 219 .TP
 220 .B AT_STATX_FORCE_SYNC
 221 Force the attributes to be synchronized with the server.
 222 This may require that
 223 a network filesystem perform a data writeback to get the timestamps correct.
 224 .TP
 225 .B AT_STATX_DONT_SYNC
 226 Don't synchronize anything, but rather just take whatever
 227 the system has cached if possible.
 228 This may mean that the information returned is approximate, but,
 229 on a network filesystem, it may not involve a round trip to the server - even
 230 if no lease is held.
 231 .PP
 232 The
 233 .I mask
 234 argument to
 235 .BR statx ()
 236 is used to tell the kernel which fields the caller is interested in.
 237 .I mask
 238 is an ORed combination of the following constants:
 239 .PP
 240 .in +4n
 241 .TS
 242 lB l.
 243 STATX_TYPE      Want stx_mode & S_IFMT
 244 STATX_MODE      Want stx_mode & \(tiS_IFMT
 245 STATX_NLINK     Want stx_nlink
 246 STATX_UID       Want stx_uid
 247 STATX_GID       Want stx_gid
 248 STATX_ATIME     Want stx_atime
 249 STATX_MTIME     Want stx_mtime
 250 STATX_CTIME     Want stx_ctime
 251 STATX_INO       Want stx_ino
 252 STATX_SIZE      Want stx_size
 253 STATX_BLOCKS    Want stx_blocks
 254 STATX_BASIC_STATS       [All of the above]
 255 STATX_BTIME     Want stx_btime
 256 STATX_MNT_ID    Want stx_mnt_id (since Linux 5.8)
 257 STATX_ALL       [All currently available fields]
 258 .TE
 259 .in
 260 .PP
 261 Note that, in general, the kernel does
 262 .I not
 263 reject values in
 264 .I mask
 265 other than the above.
 266 (For an exception, see
 267 .B EINVAL
 268 in errors.)
 269 Instead, it simply informs the caller which values are supported
 270 by this kernel and filesystem via the
 271 .I statx.stx_mask
 272 field.
 273 Therefore,
 274 .I "do not"
 275 simply set
 276 .I mask
 277 to
 278 .B UINT_MAX
 279 (all bits set),
 280 as one or more bits may, in the future, be used to specify an
 281 extension to the buffer.
 282 .SS
 283 The returned information
 284 The status information for the target file is returned in the
 285 .I statx
 286 structure pointed to by
 287 .IR statxbuf .
 288 Included in this is
 289 .I stx_mask
 290 which indicates what other information has been returned.
 291 .I stx_mask
 292 has the same format as the
 293 .I mask
 294 argument and bits are set in it to indicate
 295 which fields have been filled in.
 296 .PP
 297 It should be noted that the kernel may return fields that weren't
 298 requested and may fail to return fields that were requested,
 299 depending on what the backing filesystem supports.
 300 (Fields that are given values despite being unrequested can just be ignored.)
 301 In either case,
 302 .I stx_mask
 303 will not be equal
 304 .IR mask .
 305 .PP
 306 If a filesystem does not support a field or if it has
 307 an unrepresentable value (for instance, a file with an exotic type),
 308 then the mask bit corresponding to that field will be cleared in
 309 .I stx_mask
 310 even if the user asked for it and a dummy value will be filled in for
 311 compatibility purposes if one is available (e.g., a dummy UID and GID may be
 312 specified to mount under some circumstances).
 313 .PP
 314 A filesystem may also fill in fields that the caller didn't ask for if it has
 315 values for them available and the information is available at no extra cost.
 316 If this happens, the corresponding bits will be set in
 317 .IR stx_mask .
 318 .PP
 319 .\" Background: inode attributes are modified with i_mutex held, but
 320 .\" read by stat() without taking the mutex.
 321 .IR Note :
 322 for performance and simplicity reasons, different fields in the
 323 .I statx
 324 structure may contain state information from different moments
 325 during the execution of the system call.
 326 For example, if
 327 .I stx_mode
 328 or
 329 .I stx_uid
 330 is changed by another process by calling
 331 .BR chmod (2)
 332 or
 333 .BR chown (2),
 334 .BR stat ()
 335 might return the old
 336 .I stx_mode
 337 together with the new
 338 .IR stx_uid ,
 339 or the old
 340 .I stx_uid
 341 together with the new
 342 .IR stx_mode .
 343 .PP
 344 Apart from
 345 .I stx_mask
 346 (which is described above), the fields in the
 347 .I statx
 348 structure are:
 349 .TP
 350 .I stx_blksize
 351 The "preferred" block size for efficient filesystem I/O.
 352 (Writing to a file in
 353 smaller chunks may cause an inefficient read-modify-rewrite.)
 354 .TP
 355 .I stx_attributes
 356 Further status information about the file (see below for more information).
 357 .TP
 358 .I stx_nlink
 359 The number of hard links on a file.
 360 .TP
 361 .I stx_uid
 362 This field contains the user ID of the owner of the file.
 363 .TP
 364 .I stx_gid
 365 This field contains the ID of the group owner of the file.
 366 .TP
 367 .I stx_mode
 368 The file type and mode.
 369 See
 370 .BR inode (7)
 371 for details.
 372 .TP
 373 .I stx_ino
 374 The inode number of the file.
 375 .TP
 376 .I stx_size
 377 The size of the file (if it is a regular file or a symbolic link) in bytes.
 378 The size of a symbolic link is the length of the pathname it contains,
 379 without a terminating null byte.
 380 .TP
 381 .I stx_blocks
 382 The number of blocks allocated to the file on the medium, in 512-byte units.
 383 (This may be smaller than
 384 .IR stx_size /512
 385 when the file has holes.)
 386 .TP
 387 .I stx_attributes_mask
 388 A mask indicating which bits in
 389 .I stx_attributes
 390 are supported by the VFS and the filesystem.
 391 .TP
 392 .I stx_atime
 393 The file's last access timestamp.
 394 .TP
 395 .I stx_btime
 396 The file's creation timestamp.
 397 .TP
 398 .I stx_ctime
 399 The file's last status change timestamp.
 400 .TP
 401 .I stx_mtime
 402 The file's last modification timestamp.
 403 .TP
 404 .IR stx_dev_major " and "  stx_dev_minor
 405 The device on which this file (inode) resides.
 406 .TP
 407 .IR stx_rdev_major " and "  stx_rdev_minor
 408 The device that this file (inode) represents if the file is of block or
 409 character device type.
 410 .TP
 411 .I stx_mnt_id
 412 .\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60
 413 The mount ID of the mount containing the file.
 414 This is the same number reported by
 415 .BR name_to_handle_at (2)
 416 and corresponds to the number in the first field in one of the records in
 417 .IR /proc/self/mountinfo .
 418 .PP
 419 For further information on the above fields, see
 420 .BR inode (7).
 421 .\"
 422 .SS File attributes
 423 The
 424 .I stx_attributes
 425 field contains a set of ORed flags that indicate additional attributes
 426 of the file.
 427 Note that any attribute that is not indicated as supported by
 428 .I stx_attributes_mask
 429 has no usable value here.
 430 The bits in
 431 .I stx_attributes_mask
 432 correspond bit-by-bit to
 433 .IR stx_attributes .
 434 .PP
 435 The flags are as follows:
 436 .TP
 437 .B STATX_ATTR_COMPRESSED
 438 The file is compressed by the filesystem and may take extra resources
 439 to access.
 440 .TP
 441 .B STATX_ATTR_IMMUTABLE
 442 The file cannot be modified: it cannot be deleted or renamed,
 443 no hard links can be created to this file and no data can be written to it.
 444 See
 445 .BR chattr (1).
 446 .TP
 447 .B STATX_ATTR_APPEND
 448 The file can only be opened in append mode for writing.
 449 Random access writing
 450 is not permitted.
 451 See
 452 .BR chattr (1).
 453 .TP
 454 .B STATX_ATTR_NODUMP
 455 File is not a candidate for backup when a backup program such as
 456 .BR dump (8)
 457 is run.
 458 See
 459 .BR chattr (1).
 460 .TP
 461 .B STATX_ATTR_ENCRYPTED
 462 A key is required for the file to be encrypted by the filesystem.
 463 .TP
 464 .BR STATX_ATTR_VERITY " (since Linux 5.5)"
 465 .\" commit 3ad2522c64cff1f5aebb987b00683268f0cc7c29
 466 The file has fs-verity enabled.
 467 It cannot be written to, and all reads from it will be verified
 468 against a cryptographic hash that covers the
 469 entire file (e.g., via a Merkle tree).
 470 .TP
 471 .BR STATX_ATTR_DAX " (since Linux 5.8)"
 472 The file is in the DAX (cpu direct access) state.
 473 DAX state attempts to
 474 minimize software cache effects for both I/O and memory mappings of this file.
 475 It requires a file system which has been configured to support DAX.
 476 .IP
 477 DAX generally assumes all accesses are via CPU load / store instructions
 478 which can minimize overhead for small accesses,
 479 but may adversely affect CPU utilization for large transfers.
 480 .IP
 481 File I/O is done directly to/from user-space buffers and memory mapped I/O may
 482 be performed with direct memory mappings that bypass the kernel page cache.
 483 .IP
 484 While the DAX property tends to result in data being transferred synchronously,
 485 it does not give the same guarantees as the
 486 .B O_SYNC
 487 flag (see
 488 .BR open (2)),
 489 where data and the necessary metadata are transferred together.
 490 .IP
 491 A DAX file may support being mapped with the
 492 .B MAP_SYNC
 493 flag, which enables a
 494 program to use CPU cache flush instructions to persist CPU store operations
 495 without an explicit
 496 .BR fsync (2).
 497 See
 498 .BR mmap (2)
 499 for more information.
 500 .SH RETURN VALUE
 501 On success, zero is returned.
 502 On error, \-1 is returned, and
 503 .I errno
 504 is set to indicate the error.
 505 .SH ERRORS
 506 .TP
 507 .B EACCES
 508 Search permission is denied for one of the directories
 509 in the path prefix of
 510 .IR pathname .
 511 (See also
 512 .BR path_resolution (7).)
 513 .TP
 514 .B EBADF
 515 .I pathname
 516 is relative but
 517 .I dirfd
 518 is neither
 519 .B AT_FDCWD
 520 nor a valid file descriptor.
 521 .TP
 522 .B EFAULT
 523 .I pathname
 524 or
 525 .I statxbuf
 526 is NULL or points to a location outside the process's
 527 accessible address space.
 528 .TP
 529 .B EINVAL
 530 Invalid flag specified in
 531 .IR flags .
 532 .TP
 533 .B EINVAL
 534 Reserved flag specified in
 535 .IR mask .
 536 (Currently, there is one such flag, designated by the constant
 537 .BR STATX__RESERVED ,
 538 with the value 0x80000000U.)
 539 .TP
 540 .B ELOOP
 541 Too many symbolic links encountered while traversing the pathname.
 542 .TP
 543 .B ENAMETOOLONG
 544 .I pathname
 545 is too long.
 546 .TP
 547 .B ENOENT
 548 A component of
 549 .I pathname
 550 does not exist, or
 551 .I pathname
 552 is an empty string and
 553 .B AT_EMPTY_PATH
 554 was not specified in
 555 .IR flags .
 556 .TP
 557 .B ENOMEM
 558 Out of memory (i.e., kernel memory).
 559 .TP
 560 .B ENOTDIR
 561 A component of the path prefix of
 562 .I pathname
 563 is not a directory or
 564 .I pathname
 565 is relative and
 566 .I dirfd
 567 is a file descriptor referring to a file other than a directory.
 568 .SH VERSIONS
 569 .BR statx ()
 570 was added to Linux in kernel 4.11; library support was added in glibc 2.28.
 571 .SH CONFORMING TO
 572 .BR statx ()
 573 is Linux-specific.
 574 .SH SEE ALSO
 575 .BR ls (1),
 576 .BR stat (1),
 577 .BR access (2),
 578 .BR chmod (2),
 579 .BR chown (2),
 580 .BR name_to_handle_at (2),
 581 .BR readlink (2),
 582 .BR stat (2),
 583 .BR utime (2),
 584 .BR proc (5),
 585 .BR capabilities (7),
 586 .BR inode (7),
 587 .BR symlink (7)