Skip to content

Commit d1ce256

Browse files
serhiy-storchakaserhiy-storchaka
committed
gh-78502: AAdd a trackfd parameter to mmap.mmap() on Windows
If trackfd is False, the file handle corresponding to fileno will not be duplicated.
1 parent c779f23 commit d1ce256

File tree

5 files changed

+93
-71
lines changed

5 files changed

+93
-71
lines changed

‎Doc/library/mmap.rst‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,11 @@ update the underlying file.
4848

4949
To map anonymous memory, -1 should be passed as the fileno along with the length.
5050

51-
.. class:: mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0)
51+
.. class:: mmap(fileno, length, tagname=None, \
52+
access=ACCESS_DEFAULT, offset=0, *, trackfd=True)
5253
5354
**(Windows version)** Maps *length* bytes from the file specified by the
54-
file handle *fileno*, and creates a mmap object. If *length* is larger
55+
file descriptor *fileno*, and creates a mmap object. If *length* is larger
5556
than the current size of the file, the file is extended to contain *length*
5657
bytes. If *length* is ``0``, the maximum length of the map is the current
5758
size of the file, except that if the file is empty Windows raises an
@@ -69,6 +70,17 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
6970
will be relative to the offset from the beginning of the file. *offset*
7071
defaults to 0. *offset* must be a multiple of the :const:`ALLOCATIONGRANULARITY`.
7172

73+
If *trackfd* is ``False``, the file handle corresponding to *fileno* will
74+
not be duplicated, and the resulting :class:`!mmap` object will not
75+
be associated with the map's underlying file.
76+
This means that the :meth:`~mmap.mmap.size` and :meth:`~mmap.mmap.resize`
77+
methods will fail.
78+
This mode is useful to limit the number of open file handles.
79+
The original file can be renamed (but not deleted) after closing *fileno*.
80+
81+
.. versionchanged:: next
82+
The *trackfd* parameter was added.
83+
7284
.. audit-event:: mmap.__new__ fileno,length,access,offset mmap.mmap
7385

7486
.. class:: mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, \

‎Doc/whatsnew/3.15.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -358,6 +358,15 @@ math
358358
(Contributed by Bénédikt Tran in :gh:`135853`.)
359359

360360

361+
mmap
362+
----
363+
364+
* :class:`mmap.mmap` now has a *trackfd* parameter on Windows;
365+
if it is ``False``, the file handle corresponding to *fileno* will
366+
not be duplicated.
367+
(Contributed by Serhiy Storchaka in :gh:`78502`.)
368+
369+
361370
os.path
362371
-------
363372

‎Lib/test/test_mmap.py‎

Lines changed: 37 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
from test import support
12
from test.support import (
23
requires, _2G, _4G, gc_collect, cpython_only, is_emscripten, is_apple,
34
in_systemd_nspawn_sync_suppressed,
@@ -270,42 +271,45 @@ def test_access_parameter(self):
270271
self.assertRaises(TypeError, m.write_byte, 0)
271272
m.close()
272273

273-
@unittest.skipIf(os.name == 'nt', 'trackfd not present on Windows')
274-
def test_trackfd_parameter(self):
274+
@support.subTests('close_original_fd', (True, False))
275+
def test_trackfd_parameter(self, close_original_fd):
275276
size = 64
276277
with open(TESTFN, "wb") as f:
277278
f.write(b"a"*size)
278-
for close_original_fd in True, False:
279-
with self.subTest(close_original_fd=close_original_fd):
280-
with open(TESTFN, "r+b") as f:
281-
with mmap.mmap(f.fileno(), size, trackfd=False) as m:
282-
if close_original_fd:
283-
f.close()
284-
self.assertEqual(len(m), size)
285-
with self.assertRaises(OSError) as err_cm:
286-
m.size()
287-
self.assertEqual(err_cm.exception.errno, errno.EBADF)
288-
with self.assertRaises(ValueError):
289-
m.resize(size * 2)
290-
with self.assertRaises(ValueError):
291-
m.resize(size // 2)
292-
self.assertEqual(m.closed, False)
293-
294-
# Smoke-test other API
295-
m.write_byte(ord('X'))
296-
m[2] = ord('Y')
297-
m.flush()
298-
with open(TESTFN, "rb") as f:
299-
self.assertEqual(f.read(4), b'XaYa')
300-
self.assertEqual(m.tell(), 1)
301-
m.seek(0)
302-
self.assertEqual(m.tell(), 0)
303-
self.assertEqual(m.read_byte(), ord('X'))
304-
305-
self.assertEqual(m.closed, True)
306-
self.assertEqual(os.stat(TESTFN).st_size, size)
307-
308-
@unittest.skipIf(os.name == 'nt', 'trackfd not present on Windows')
279+
with open(TESTFN, "r+b") as f:
280+
with mmap.mmap(f.fileno(), size, trackfd=1|False) as m:
281+
if close_original_fd:
282+
f.close()
283+
self.assertEqual(len(m), size)
284+
with self.assertRaises(OSError) as err_cm:
285+
m.size()
286+
self.assertEqual(err_cm.exception.errno, errno.EBADF)
287+
with self.assertRaises(ValueError):
288+
m.resize(size * 2)
289+
with self.assertRaises(ValueError):
290+
m.resize(size // 2)
291+
self.assertIs(m.closed, False)
292+
293+
# Smoke-test other API
294+
m.write_byte(ord('X'))
295+
m[2] = ord('Y')
296+
m.flush()
297+
with open(TESTFN, "rb") as f:
298+
self.assertEqual(f.read(4), b'XaYa')
299+
self.assertEqual(m.tell(), 1)
300+
m.seek(0)
301+
self.assertEqual(m.tell(), 0)
302+
self.assertEqual(m.read_byte(), ord('X'))
303+
304+
if os.name == 'nt' and not close_original_fd:
305+
self.assertRaises(PermissionError, os.rename, TESTFN, TESTFN+'1')
306+
else:
307+
os.rename(TESTFN, TESTFN+'1')
308+
os.rename(TESTFN+'1', TESTFN)
309+
310+
self.assertIs(m.closed, True)
311+
self.assertEqual(os.stat(TESTFN).st_size, size)
312+
309313
def test_trackfd_neg1(self):
310314
size = 64
311315
with mmap.mmap(-1, size, trackfd=False) as m:
@@ -317,15 +321,6 @@ def test_trackfd_neg1(self):
317321
m[0] = ord('a')
318322
assert m[0] == ord('a')
319323

320-
@unittest.skipIf(os.name != 'nt', 'trackfd only fails on Windows')
321-
def test_no_trackfd_parameter_on_windows(self):
322-
# 'trackffd' is an invalid keyword argument for this function
323-
size = 64
324-
with self.assertRaises(TypeError):
325-
mmap.mmap(-1, size, trackfd=True)
326-
with self.assertRaises(TypeError):
327-
mmap.mmap(-1, size, trackfd=False)
328-
329324
def test_bad_file_desc(self):
330325
# Try opening a bad file descriptor...
331326
self.assertRaises(OSError, mmap.mmap, -2, 4096)

‎Misc/NEWS.d/next/Library/2025-08-29-12-05-33.gh-issue-78502.VpIMxg.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
:class:`mmap.mmap` now has a *trackfd* parameter on Windows; if it is
2+
``False``, the file handle corresponding to *fileno* will not be duplicated.

‎Modules/mmapmodule.c‎

Lines changed: 31 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -119,11 +119,11 @@ typedef struct {
119119

120120
#ifdef UNIX
121121
int fd;
122-
_Bool trackfd;
123122
#endif
124123

125124
PyObject *weakreflist;
126125
access_mode access;
126+
_Bool trackfd;
127127
} mmap_object;
128128

129129
#define mmap_object_CAST(op) ((mmap_object *)(op))
@@ -642,13 +642,11 @@ is_resizeable(mmap_object *self)
642642
"mmap can't resize with extant buffers exported.");
643643
return 0;
644644
}
645-
#ifdef UNIX
646645
if (!self->trackfd) {
647646
PyErr_SetString(PyExc_ValueError,
648647
"mmap can't resize with trackfd=False.");
649648
return 0;
650649
}
651-
#endif
652650
if ((self->access == ACCESS_WRITE) || (self->access == ACCESS_DEFAULT))
653651
return 1;
654652
PyErr_Format(PyExc_TypeError,
@@ -725,7 +723,7 @@ mmap_size_method(PyObject *op, PyObject *Py_UNUSED(ignored))
725723
CHECK_VALID(NULL);
726724

727725
#ifdef MS_WINDOWS
728-
if (self->file_handle != INVALID_HANDLE_VALUE) {
726+
if (self->file_handle != INVALID_HANDLE_VALUE || !self->trackfd) {
729727
DWORD low,high;
730728
long long size;
731729
low = GetFileSize(self->file_handle, &high);
@@ -1467,7 +1465,7 @@ static PyObject *
14671465
new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict);
14681466

14691467
PyDoc_STRVAR(mmap_doc,
1470-
"Windows: mmap(fileno, length[, tagname[, access[, offset]]])\n\
1468+
"Windows: mmap(fileno, length[, tagname[, access[, offset[, trackfd]]]])\n\
14711469
\n\
14721470
Maps length bytes from the file specified by the file handle fileno,\n\
14731471
and returns a mmap object. If length is larger than the current size\n\
@@ -1727,16 +1725,16 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
17271725
PyObject *tagname = Py_None;
17281726
DWORD dwErr = 0;
17291727
int fileno;
1730-
HANDLE fh = 0;
1731-
int access = (access_mode)ACCESS_DEFAULT;
1728+
HANDLE fh = INVALID_HANDLE_VALUE;
1729+
int access = (access_mode)ACCESS_DEFAULT, trackfd = 1;
17321730
DWORD flProtect, dwDesiredAccess;
17331731
static char *keywords[] = { "fileno", "length",
17341732
"tagname",
1735-
"access", "offset", NULL };
1733+
"access", "offset", "trackfd", NULL };
17361734

1737-
if (!PyArg_ParseTupleAndKeywords(args, kwdict, "in|OiL", keywords,
1735+
if (!PyArg_ParseTupleAndKeywords(args, kwdict, "in|OiL$p", keywords,
17381736
&fileno, &map_size,
1739-
&tagname, &access, &offset)) {
1737+
&tagname, &access, &offset, &trackfd)) {
17401738
return NULL;
17411739
}
17421740

@@ -1803,30 +1801,36 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
18031801
m_obj->map_handle = NULL;
18041802
m_obj->tagname = NULL;
18051803
m_obj->offset = offset;
1804+
m_obj->trackfd = trackfd;
18061805

1807-
if (fh) {
1808-
/* It is necessary to duplicate the handle, so the
1809-
Python code can close it on us */
1810-
if (!DuplicateHandle(
1811-
GetCurrentProcess(), /* source process handle */
1812-
fh, /* handle to be duplicated */
1813-
GetCurrentProcess(), /* target proc handle */
1814-
(LPHANDLE)&m_obj->file_handle, /* result */
1815-
0, /* access - ignored due to options value */
1816-
FALSE, /* inherited by child processes? */
1817-
DUPLICATE_SAME_ACCESS)) { /* options */
1818-
dwErr = GetLastError();
1819-
Py_DECREF(m_obj);
1820-
PyErr_SetFromWindowsErr(dwErr);
1821-
return NULL;
1806+
if (fh != INVALID_HANDLE_VALUE) {
1807+
if (trackfd) {
1808+
/* It is necessary to duplicate the handle, so the
1809+
Python code can close it on us */
1810+
if (!DuplicateHandle(
1811+
GetCurrentProcess(), /* source process handle */
1812+
fh, /* handle to be duplicated */
1813+
GetCurrentProcess(), /* target proc handle */
1814+
&fh, /* result */
1815+
0, /* access - ignored due to options value */
1816+
FALSE, /* inherited by child processes? */
1817+
DUPLICATE_SAME_ACCESS)) /* options */
1818+
{
1819+
dwErr = GetLastError();
1820+
Py_DECREF(m_obj);
1821+
PyErr_SetFromWindowsErr(dwErr);
1822+
return NULL;
1823+
}
1824+
m_obj->file_handle = fh;
18221825
}
18231826
if (!map_size) {
18241827
DWORD low,high;
18251828
low = GetFileSize(fh, &high);
18261829
/* low might just happen to have the value INVALID_FILE_SIZE;
18271830
so we need to check the last error also. */
18281831
if (low == INVALID_FILE_SIZE &&
1829-
(dwErr = GetLastError()) != NO_ERROR) {
1832+
(dwErr = GetLastError()) != NO_ERROR)
1833+
{
18301834
Py_DECREF(m_obj);
18311835
return PyErr_SetFromWindowsErr(dwErr);
18321836
}
@@ -1888,7 +1892,7 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
18881892
off_lo = (DWORD)(offset & 0xFFFFFFFF);
18891893
/* For files, it would be sufficient to pass 0 as size.
18901894
For anonymous maps, we have to pass the size explicitly. */
1891-
m_obj->map_handle = CreateFileMappingW(m_obj->file_handle,
1895+
m_obj->map_handle = CreateFileMappingW(fh,
18921896
NULL,
18931897
flProtect,
18941898
size_hi,

0 commit comments

Comments
 (0)