gh-83714: Use statx on Linux 4.11 and later in os.stat

Doc/library/os.rst

@@ -3224,6 +3224,9 @@ features:
 
  .. versionchanged:: 3.12
  ``st_birthtime`` is now available on Windows.
+ .. versionchanged:: next
+ ``st_birthtime`` is now present on Linux. The value will be ``0.0``
+ on kernel versions < 4.11 or if not supported by the filesystem.
 
  .. attribute:: st_birthtime_ns
 
@@ -3232,6 +3235,9 @@ features:
  :exc:`AttributeError`.
 
  .. versionadded:: 3.12
+ .. versionchanged:: next
+ ``st_birthtime_ns`` is now present on Linux. The value will be ``0``
+ on kernel versions < 4.11 or if not supported by the filesystem.
 
  .. note::
 
@@ -3364,6 +3370,140 @@ features:
 
  Added the :attr:`st_birthtime` member on Windows.
 
+ .. versionchanged:: next
+ Added the :attr:`st_birthtime` and :attr:`st_birthtime_ns` members on
+ Linux.
+
+
+.. function:: statx(path, mask, *, dir_fd=None, follow_symlinks=True, sync=None)
+
+ Get the status of a file or file descriptor by performing a :c:func:`!statx`
+ system call on the given path. *path* may be specified as either a string or
+ bytes -- directly or indirectly through the :class:`PathLike` interface --
+ or as an open file descriptor. *mask* is a combination of the module-level
+ :const:`STATX_* <STATX_TYPE>` constants specifying the information to
+ retrieve. Returns a :class:`statx_result` object whose
+ :attr:`~os.statx_result.stx_mask` attribute specifies the information
+ actually retrieved (which may differ from *mask*).
+
+ The optional parameter *sync* controls the freshness of the returned
+ information. ``sync=True`` requests that the kernel return up-to-date
+ information, even when doing so is expensive (for example, requiring a
+ round trip to the server for a file on a network filesystem).
+ ``sync=False`` requests that the kernel return cached information if
+ available. ``sync=None`` expresses no preference, in which case the kernel
+ will return information as fresh as :func:`~os.stat` does.
+
+ This function supports :ref:`specifying a file descriptor <path_fd>`,
+ :ref:`paths relative to directory descriptors <dir_fd>`, and
+ :ref:`not following symlinks <follow_symlinks>`.
+
+ .. seealso:: The :manpage:`statx(2)` man page.
+
+ .. availability:: Linux >= 4.11 with glibc >= 2.28.
+
+ .. versionadded:: next
+
+
+.. class:: statx_result
+
+ Object whose attributes correspond roughly to the members of the
+ :c:struct:`!statx` structure. It is used for the result of :func:`os.statx`.
+ :class:`!statx_result` has all of the attributes of :class:`stat_result`
+ available on Linux, but is not a subclass of :class:`stat_result` nor a
+ tuple. :class:`!statx_result` has the following additional attributes:
+
+ .. attribute:: stx_mask
+
+ Bitmask of :const:`STATX_* <STATX_TYPE>` constants specifying the
+ information retrieved, which may differ from what was requested depending
+ on the filesystem, filesystem type, and kernel version. All attributes
+ of this class are accessible regardless of the value of
+ :attr:`!stx_mask`, and they may have useful fictitious values. For
+ example, for a file on a network filesystem, :const:`STATX_UID` and
+ :const:`STATX_GID` may be unset because file ownership on the server is
+ based on an external user database, but :attr:`!st_uid` and
+ :attr:`!st_gid` may contain the IDs of the local user who controls the
+ mount.
+
+ .. attribute:: stx_attributes_mask
+
+ Bitmask of :const:`!STATX_ATTR_* <stat.STATX_ATTR_COMPRESSED>` constants
+ specifying the attributes bits supported for this file.
+
+ .. attribute:: stx_attributes
+
+ Bitmask of :const:`!STATX_ATTR_* <stat.STATX_ATTR_COMPRESSED>` constants
+ specifying the attributes of this file.
+
+ .. attribute:: stx_mnt_id
+
+ Mount ID.
+
+ .. attribute:: stx_dio_mem_align
+
+ Direct I/O memory buffer alignment requirement.
+
+ .. attribute:: stx_dio_offset_align
+
+ Direct I/O file offset alignment requirement.
+
+ .. attribute:: stx_subvol
+
+ Subvolume ID.
+
+ .. attribute:: stx_atomic_write_unit_min
+
+ Minimum size for direct I/O with torn-write protection.
+
+ .. attribute:: stx_atomic_write_unit_max
+
+ Maximum size for direct I/O with torn-write protection.
+
+ .. attribute:: stx_atomic_write_segments_max
+
+ Maximum iovecs for direct I/O with torn-write protection.
+
+ .. attribute:: stx_dio_read_offset_align
+
+ Direct I/O file offset alignment requirement for reads.
+
+ .. attribute:: stx_atomic_write_unit_max_opt
+
+ Maximum optimized size for direct I/O with torn-write protection.
+
+ .. seealso:: The :manpage:`statx(2)` man page.
+
+ .. availability:: Linux >= 4.11 with glibc >= 2.28.
+
+ .. versionadded:: next
+
+.. data:: STATX_TYPE
+ STATX_MODE
+ STATX_NLINK
+ STATX_UID
+ STATX_GID
+ STATX_ATIME
+ STATX_MTIME
+ STATX_CTIME
+ STATX_INO
+ STATX_SIZE
+ STATX_BLOCKS
+ STATX_BASIC_STATS
+ STATX_BTIME
+ STATX_MNT_ID
+ STATX_DIOALIGN
+ STATX_MNT_ID_UNIQUE
+ STATX_SUBVOL
+ STATX_WRITE_ATOMIC
+ STATX_DIO_READ_ALIGN
+
+ Bitflags for use as the *mask* parameter to :func:`os.statx`.
+
+ .. availability:: Linux >= 4.11 with glibc >= 2.28.
+
+ .. versionadded:: next
+
 
 .. function:: statvfs(path)
 

Doc/library/stat.rst

@@ -493,3 +493,22 @@ constants, but are not an exhaustive list.
  IO_REPARSE_TAG_APPEXECLINK
 
  .. versionadded:: 3.8
+
+On Linux, the following file attribute constants are available for use when
+testing bits in the :attr:`~os.statx_result.stx_attributes` and
+:attr:`~os.statx_result.stx_attributes_mask` members returned by
+:func:`os.statx`. See the :manpage:`statx(2)` man page for more detail on the
+meaning of these constants.
+
+.. data:: STATX_ATTR_COMPRESSED
+ STATX_ATTR_IMMUTABLE
+ STATX_ATTR_APPEND
+ STATX_ATTR_NODUMP
+ STATX_ATTR_ENCRYPTED
+ STATX_ATTR_AUTOMOUNT
+ STATX_ATTR_MOUNT_ROOT
+ STATX_ATTR_VERITY
+ STATX_ATTR_DAX
+ STATX_ATTR_WRITE_ATOMIC
+
+ .. versionadded:: next

Include/internal/pycore_global_strings.h

@@ -587,6 +587,7 @@ struct _Py_global_strings {
  STRUCT_FOR_ID(loop)
  STRUCT_FOR_ID(manual_reset)
  STRUCT_FOR_ID(mapping)
+ STRUCT_FOR_ID(mask)
  STRUCT_FOR_ID(match)
  STRUCT_FOR_ID(max_length)
  STRUCT_FOR_ID(maxdigits)
@@ -778,6 +779,7 @@ struct _Py_global_strings {
  STRUCT_FOR_ID(sub_key)
  STRUCT_FOR_ID(subcalls)
  STRUCT_FOR_ID(symmetric_difference_update)
+ STRUCT_FOR_ID(sync)
  STRUCT_FOR_ID(tabsize)
  STRUCT_FOR_ID(tag)
  STRUCT_FOR_ID(target)

Lib/os.py

@@ -131,6 +131,8 @@ def _add(str, fn):
  _add("HAVE_UNLINKAT", "unlink")
  _add("HAVE_UNLINKAT", "rmdir")
  _add("HAVE_UTIMENSAT", "utime")
+ if _exists("statx"):
+ _set.add(statx)
  supports_dir_fd = _set
 
  _set = set()
@@ -152,6 +154,8 @@ def _add(str, fn):
  _add("HAVE_FPATHCONF", "pathconf")
  if _exists("statvfs") and _exists("fstatvfs"): # mac os x10.3
  _add("HAVE_FSTATVFS", "statvfs")
+ if _exists("statx"):
+ _set.add(statx)
  supports_fd = _set
 
  _set = set()
@@ -190,6 +194,8 @@ def _add(str, fn):
  _add("HAVE_FSTATAT", "stat")
  _add("HAVE_UTIMENSAT", "utime")
  _add("MS_WINDOWS", "stat")
+ if _exists("statx"):
+ _set.add(statx)
  supports_follow_symlinks = _set
 
  del _set

Lib/stat.py

@@ -200,6 +200,21 @@ def filemode(mode):
 FILE_ATTRIBUTE_VIRTUAL = 65536
 
 
+# Linux STATX_ATTR constants for interpreting os.statx()'s
+# "stx_attributes" and "stx_attributes_mask" members
+
+STATX_ATTR_COMPRESSED = 0x00000004
+STATX_ATTR_IMMUTABLE = 0x00000010
+STATX_ATTR_APPEND = 0x00000020
+STATX_ATTR_NODUMP = 0x00000040
+STATX_ATTR_ENCRYPTED = 0x00000800
+STATX_ATTR_AUTOMOUNT = 0x00001000
+STATX_ATTR_MOUNT_ROOT = 0x00002000
+STATX_ATTR_VERITY = 0x00100000
+STATX_ATTR_DAX = 0x00200000
+STATX_ATTR_WRITE_ATOMIC = 0x00400000
+
+
 # If available, use C implementation
 try:
  from _stat import *