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