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