Skip to content

Commit 1f0a688

Browse files
vstinnervstinner
committed
Document all statx_result members
Rename stx_birthtime to stx_btime, and rename stx_birthtime_ns to stx_btime_ns.
1 parent 55db458 commit 1f0a688

File tree

3 files changed

+165
-64
lines changed

3 files changed

+165
-64
lines changed

‎Doc/library/os.rst‎

Lines changed: 159 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -3416,128 +3416,230 @@ features:
34163416
:class:`!statx_result` is not a subclass of :class:`~stat_result` and cannot
34173417
be used as a tuple.
34183418

3419-
:class:`!statx_result` has the following additional attributes:
3419+
:class:`!statx_result` has the following attributes:
34203420

34213421
.. attribute:: stx_mask
34223422

34233423
Bitmask of :const:`STATX_* <STATX_TYPE>` constants specifying the
34243424
information retrieved, which may differ from what was requested.
34253425

3426-
.. attribute:: stx_attributes_mask
3426+
.. attribute:: stx_atime
34273427

3428-
Bitmask of :const:`STATX_ATTR_* <stat.STATX_ATTR_COMPRESSED>` constants
3429-
specifying the attributes bits supported for this file.
3428+
Time of most recent access expressed in seconds.
3429+
3430+
Equal to ``None`` if :data:`STATX_ATIME` is missing from
3431+
:attr:`~statx_result.stx_mask`.
3432+
3433+
.. attribute:: stx_atime_ns
3434+
3435+
Time of most recent access expressed in nanoseconds as an integer.
3436+
3437+
Equal to ``None`` if :data:`STATX_ATIME` is missing from
3438+
:attr:`~statx_result.stx_mask`.
3439+
3440+
.. attribute:: stx_atomic_write_segments_max
3441+
3442+
Maximum iovecs for direct I/O with torn-write protection.
3443+
3444+
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3445+
:attr:`~statx_result.stx_mask`.
3446+
3447+
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3448+
userspace API headers >= 6.11.
3449+
3450+
.. attribute:: stx_atomic_write_unit_min
3451+
3452+
Minimum size for direct I/O with torn-write protection.
3453+
3454+
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3455+
:attr:`~statx_result.stx_mask`.
3456+
3457+
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3458+
userspace API headers >= 6.11.
3459+
3460+
.. attribute:: stx_atomic_write_unit_max
3461+
3462+
Maximum size for direct I/O with torn-write protection.
3463+
3464+
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3465+
:attr:`~statx_result.stx_mask`.
3466+
3467+
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3468+
userspace API headers >= 6.11.
3469+
3470+
.. attribute:: stx_atomic_write_unit_max_opt
3471+
3472+
Maximum optimized size for direct I/O with torn-write protection.
3473+
3474+
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3475+
:attr:`~statx_result.stx_mask`.
3476+
3477+
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3478+
userspace API headers >= 6.16.
34303479

34313480
.. attribute:: stx_attributes
34323481

34333482
Bitmask of :const:`STATX_ATTR_* <stat.STATX_ATTR_COMPRESSED>` constants
34343483
specifying the attributes of this file.
34353484

3436-
.. attribute:: stx_dev_major
3485+
.. attribute:: stx_attributes_mask
34373486

3438-
Major number of the device on which this file resides.
3487+
A mask indicating which bits in :attr:`stx_attributes` are supported by
3488+
the VFS and the filesystem.
34393489

3440-
.. attribute:: stx_dev_minor
3490+
.. attribute:: stx_blksize
34413491

3442-
Minor number of the device on which this file resides.
3492+
"Preferred" blocksize for efficient file system I/O. Writing to a file in
3493+
smaller chunks may cause an inefficient read-modify-rewrite.
34433494

3444-
.. attribute:: stx_rdev_major
3495+
.. attribute:: stx_blocks
34453496

3446-
Major number of the device this file represents.
3497+
Number of 512-byte blocks allocated for file.
3498+
This may be smaller than :attr:`stx_size`/512 when the file has holes.
34473499

3448-
.. attribute:: stx_rdev_minor
3500+
.. attribute:: stx_btime
34493501

3450-
Minor number of the device this file represents.
3502+
Time of file creation expressed in seconds.
34513503

3452-
.. attribute:: stx_mnt_id
3504+
Equal to ``None`` if :data:`STATX_BTIME` is missing from
3505+
:attr:`~statx_result.stx_mask`.
34533506

3454-
Mount identifier.
3507+
.. attribute:: stx_btime_ns
34553508

3456-
Equal to ``None`` if :data:`STATX_MNT_ID` is missing from
3457-
:attr:`~os.statx_result.stx_mask`.
3509+
Time of file creation expressed in nanoseconds as an integer.
34583510

3459-
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3460-
userspace API headers >= 5.8.
3511+
Equal to ``None`` if :data:`STATX_BTIME` is missing from
3512+
:attr:`~statx_result.stx_mask`.
34613513

3462-
.. attribute:: stx_dio_mem_align
3514+
.. attribute:: stx_ctime
34633515

3464-
Direct I/O memory buffer alignment requirement.
3516+
Time of most recent metadata change expressed in seconds.
34653517

3466-
Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
3467-
:attr:`~os.statx_result.stx_mask`.
3518+
Equal to ``None`` if :data:`STATX_CTIME` is missing from
3519+
:attr:`~statx_result.stx_mask`.
34683520

3469-
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3470-
userspace API headers >= 6.1.
3521+
.. attribute:: stx_ctime_ns
3522+
3523+
Time of most recent metadata change expressed in nanoseconds as an
3524+
integer.
3525+
3526+
Equal to ``None`` if :data:`STATX_CTIME` is missing from
3527+
:attr:`~statx_result.stx_mask`.
3528+
3529+
.. attribute:: stx_dev
3530+
3531+
Identifier of the device on which this file resides.
3532+
3533+
.. attribute:: stx_dev_major
3534+
3535+
Major number of the device on which this file resides.
3536+
3537+
.. attribute:: stx_dev_minor
3538+
3539+
Minor number of the device on which this file resides.
34713540

34723541
.. attribute:: stx_dio_offset_align
34733542

34743543
Direct I/O file offset alignment requirement.
34753544

34763545
Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
3477-
:attr:`~os.statx_result.stx_mask`.
3546+
:attr:`~statx_result.stx_mask`.
34783547

34793548
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
34803549
userspace API headers >= 6.1.
34813550

3482-
.. attribute:: stx_subvol
3551+
.. attribute:: stx_dio_mem_align
34833552

3484-
Subvolume identifier.
3553+
Direct I/O memory buffer alignment requirement.
34853554

3486-
Equal to ``None`` if :data:`STATX_SUBVOL` is missing from
3487-
:attr:`~os.statx_result.stx_mask`.
3555+
Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
3556+
:attr:`~statx_result.stx_mask`.
34883557

34893558
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3490-
userspace API headers >= 6.10.
3559+
userspace API headers >= 6.1.
34913560

3492-
.. attribute:: stx_atomic_write_unit_min
3561+
.. attribute:: stx_dio_read_offset_align
34933562

3494-
Minimum size for direct I/O with torn-write protection.
3563+
Direct I/O file offset alignment requirement for reads.
34953564

3496-
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3497-
:attr:`~os.statx_result.stx_mask`.
3565+
Equal to ``None`` if :data:`STATX_DIO_READ_ALIGN` is missing from
3566+
:attr:`~statx_result.stx_mask`.
34983567

34993568
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3500-
userspace API headers >= 6.11.
3569+
userspace API headers >= 6.14.
35013570

3502-
.. attribute:: stx_atomic_write_unit_max
3571+
.. attribute:: stx_gid
35033572

3504-
Maximum size for direct I/O with torn-write protection.
3573+
Group identifier of the file owner.
35053574

3506-
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3507-
:attr:`~os.statx_result.stx_mask`.
3575+
.. attribute:: stx_ino
35083576

3509-
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3510-
userspace API headers >= 6.11.
3577+
The inode number.
35113578

3512-
.. attribute:: stx_atomic_write_unit_max_opt
3579+
.. attribute:: stx_mnt_id
35133580

3514-
Maximum optimized size for direct I/O with torn-write protection.
3581+
Mount identifier.
35153582

3516-
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3517-
:attr:`~os.statx_result.stx_mask`.
3583+
Equal to ``None`` if :data:`STATX_MNT_ID` is missing from
3584+
:attr:`~statx_result.stx_mask`.
35183585

35193586
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3520-
userspace API headers >= 6.16.
3587+
userspace API headers >= 5.8.
35213588

3522-
.. attribute:: stx_atomic_write_segments_max
3589+
.. attribute:: stx_mode
35233590

3524-
Maximum iovecs for direct I/O with torn-write protection.
3591+
File mode: file type and file mode bits (permissions).
35253592

3526-
Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
3527-
:attr:`~os.statx_result.stx_mask`.
3593+
.. attribute:: stx_mtime
35283594

3529-
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3530-
userspace API headers >= 6.11.
3595+
Time of most recent content modification expressed in seconds.
35313596

3532-
.. attribute:: stx_dio_read_offset_align
3597+
Equal to ``None`` if :data:`STATX_MTIME` is missing from
3598+
:attr:`~statx_result.stx_mask`.
35333599

3534-
Direct I/O file offset alignment requirement for reads.
3600+
.. attribute:: stx_mtime_ns
35353601

3536-
Equal to ``None`` if :data:`STATX_DIO_READ_ALIGN` is missing from
3537-
:attr:`~os.statx_result.stx_mask`.
3602+
Time of most recent content modification expressed in nanoseconds as an
3603+
integer.
3604+
3605+
Equal to ``None`` if :data:`STATX_MTIME` is missing from
3606+
:attr:`~statx_result.stx_mask`.
3607+
3608+
.. attribute:: stx_nlink
3609+
3610+
Number of hard links.
3611+
3612+
.. attribute:: stx_rdev
3613+
3614+
Type of device if an inode device.
3615+
3616+
.. attribute:: stx_rdev_major
3617+
3618+
Major number of the device this file represents.
3619+
3620+
.. attribute:: stx_rdev_minor
3621+
3622+
Minor number of the device this file represents.
3623+
3624+
.. attribute:: stx_size
3625+
3626+
Size of the file in bytes, if it is a regular file or a symbolic link.
3627+
The size of a symbolic link is the length of the pathname it contains,
3628+
without a terminating null byte.
3629+
3630+
.. attribute:: stx_subvol
3631+
3632+
Subvolume identifier.
3633+
3634+
Equal to ``None`` if :data:`STATX_SUBVOL` is missing from
3635+
:attr:`~statx_result.stx_mask`.
35383636

35393637
.. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
3540-
userspace API headers >= 6.14.
3638+
userspace API headers >= 6.10.
3639+
3640+
.. attribute:: stx_uid
3641+
3642+
User identifier of the file owner.
35413643

35423644
.. seealso:: The :manpage:`statx(2)` man page.
35433645

‎Lib/test/test_os/test_os.py‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -750,9 +750,8 @@ def check_statx_attributes(self, filename):
750750
result = os.statx(filename, maximal_mask)
751751
basic_result = os.stat(filename)
752752

753-
time_attributes = ('stx_atime', 'stx_mtime', 'stx_ctime',
754-
'stx_birthtime')
755-
# gh-83714: st_birthtime can be None on tmpfs even if STATX_BTIME mask
753+
time_attributes = ('stx_atime', 'stx_btime', 'stx_ctime', 'stx_mtime')
754+
# gh-83714: stx_btime can be None on tmpfs even if STATX_BTIME mask
756755
# is used
757756
time_attributes = [name for name in time_attributes
758757
if getattr(result, name) is not None]

‎Modules/posixmodule.c‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3422,7 +3422,7 @@ STATX_GET_ULONGLONG(stx_subvol, stx_subvol, STATX_SUBVOL)
34223422
}
34233423

34243424
STATX_GET_DOUBLE(stx_atime, atime_sec, STATX_ATIME)
3425-
STATX_GET_DOUBLE(stx_birthtime, btime_sec, STATX_BTIME)
3425+
STATX_GET_DOUBLE(stx_btime, btime_sec, STATX_BTIME)
34263426
STATX_GET_DOUBLE(stx_ctime, ctime_sec, STATX_CTIME)
34273427
STATX_GET_DOUBLE(stx_mtime, mtime_sec, STATX_MTIME)
34283428

@@ -3441,7 +3441,7 @@ STATX_GET_DOUBLE(stx_mtime, mtime_sec, STATX_MTIME)
34413441
}
34423442

34433443
STATX_GET_NSEC(stx_atime_ns, stx_atime, STATX_ATIME)
3444-
STATX_GET_NSEC(stx_birthtime_ns, stx_btime, STATX_BTIME)
3444+
STATX_GET_NSEC(stx_btime_ns, stx_btime, STATX_BTIME)
34453445
STATX_GET_NSEC(stx_ctime_ns, stx_ctime, STATX_CTIME)
34463446
STATX_GET_NSEC(stx_mtime_ns, stx_mtime, STATX_MTIME)
34473447

@@ -3457,8 +3457,8 @@ static PyGetSetDef pystatx_result_getset[] = {
34573457
G(stx_blocks, "number of blocks allocated"),
34583458
G(stx_atime, "time of last access"),
34593459
G(stx_atime_ns, "time of last access in nanoseconds"),
3460-
G(stx_birthtime, "time of creation"),
3461-
G(stx_birthtime_ns, "time of creation in nanoseconds"),
3460+
G(stx_btime, "time of creation"),
3461+
G(stx_btime_ns, "time of creation in nanoseconds"),
34623462
G(stx_ctime, "time of last change"),
34633463
G(stx_ctime_ns, "time of last change in nanoseconds"),
34643464
G(stx_mtime, "time of last modification"),

0 commit comments

Comments
 (0)