gh-113092: Support F_PREALLOCATE in fcntl

Doc/library/fcntl.rst

@@ -83,6 +83,13 @@ descriptor.
    On Linux >= 6.1, the :mod:`!fcntl` module exposes the ``F_DUPFD_QUERY``
    to query a file descriptor pointing to the same file.
 
+.. versionchanged:: next
+   On macOS, the :mod:`!fcntl` module exposes the ``F_PREALLOCATE`` constant
+   and related constants (``F_ALLOCATECONTIG``, ``F_ALLOCATEALL``,
+   ``F_ALLOCATEPERSIST``, ``F_PEOFPOSMODE``, ``F_VOLPOSMODE``) for file
+   preallocation operations. The module also provides the :class:`fstore` type
+   for use with the ``F_PREALLOCATE`` command.
+
 The module defines the following functions:
 
 
@@ -248,6 +255,53 @@ The module defines the following functions:
 
    .. audit-event:: fcntl.lockf fd,cmd,len,start,whence fcntl.lockf
 
+
+.. class:: fstore(flags=0, posmode=0, offset=0, length=0)
+
+   A Python type that wraps the ``struct fstore`` C structure used with the
+   ``F_PREALLOCATE`` command on macOS. This type implements the buffer protocol,
+   allowing it to be used directly with :func:`fcntl`.
+
+   .. attribute:: flags
+
+      Allocation flags. Can be one of:
+
+      * :const:`!F_ALLOCATECONTIG` - Allocate contiguous space
+      * :const:`!F_ALLOCATEALL` - Allocate all requested space
+      * :const:`!F_ALLOCATEPERSIST` - Make the allocation persistent
+
+   .. attribute:: posmode
+
+      Position mode. Can be one of:
+
+      * :const:`!F_PEOFPOSMODE` - Allocate relative to the physical end of file
+      * :const:`!F_VOLPOSMODE` - Allocate relative to volume position
+
+   .. attribute:: offset
+
+      File offset for the allocation.
+
+   .. attribute:: length
+
+      Length of space to allocate.
+
+   .. attribute:: bytesalloc
+
+      Number of bytes actually allocated (read-only). This field is populated
+      by the system after the F_PREALLOCATE operation.
+
+   .. staticmethod:: from_buffer(data)
+
+      Create an :class:`fstore` instance from bytes data.
+
+      This is useful for creating an fstore instance from the result of
+      :func:`fcntl.fcntl` when using the F_PREALLOCATE command.
+
+   .. availability:: macOS
+
+   .. versionadded:: next
+
+
 Examples (all on a SVR4 compliant system)::
 
    import struct, fcntl, os

Include/internal/pycore_global_strings.h

@@ -685,6 +685,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(pos1)
         STRUCT_FOR_ID(pos2)
         STRUCT_FOR_ID(posix)
+        STRUCT_FOR_ID(posmode)
         STRUCT_FOR_ID(prec)
         STRUCT_FOR_ID(preserve_exc)
         STRUCT_FOR_ID(print_file_and_line)

Lib/test/test_fcntl.py

@@ -288,6 +288,22 @@ def test_bad_fd(self):
         with self.assertRaises(OSError):
             fcntl.fcntl(fd, fcntl.F_DUPFD, b'\0' * 2048)
 
+    @unittest.skipUnless(hasattr(fcntl, 'F_PREALLOCATE'), 'need F_PREALLOCATE')
+    def test_fcntl_preallocate(self):
+        self.f = open(TESTFN, 'wb+')
+        fd = self.f.fileno()
+
+        fs = fcntl.fstore(
+            flags=fcntl.F_ALLOCATECONTIG | fcntl.F_ALLOCATEALL | fcntl.F_ALLOCATEPERSIST,
+            posmode=fcntl.F_PEOFPOSMODE,
+            offset=0,
+            length=1024
+        )
+
+        bs = fcntl.fcntl(fd, fcntl.F_PREALLOCATE, fs)
+        result = fcntl.fstore.from_buffer(bs)
+        self.assertEqual(result.bytesalloc, 1024)
+
 
 if __name__ == '__main__':
     unittest.main()

Misc/NEWS.d/next/Library/2025-10-11-19-40-33.gh-issue-113092.belDmD.rst

@@ -0,0 +1 @@
+Add ``fstore`` type, ``F_PREALLOCATE`` and related constants support to the :mod:`fcntl` module