bpo-34321: Add a trackfd parameter to mmap.mmap()

If *trackfd* is False, the file descriptor specified by *fileno*
will not be duplicated.

Author: ZackerySpytz

Doc/library/mmap.rst

@@ -69,7 +69,8 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
 
    .. audit-event:: mmap.__new__ fileno,length,access,offset mmap.mmap
 
-.. class:: mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])
+.. class:: mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, \
+                access=ACCESS_DEFAULT[, offset], trackfd=True)
    :noindex:
 
    **(Unix version)** Maps *length* bytes from the file specified by the file
@@ -100,10 +101,16 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
    defaults to 0. *offset* must be a multiple of :const:`ALLOCATIONGRANULARITY`
    which is equal to :const:`PAGESIZE` on Unix systems.
 
+   If *trackfd* is ``False``, the file descriptor specified by *fileno* will
+   not be duplicated.
+
    To ensure validity of the created memory mapping the file specified
    by the descriptor *fileno* is internally automatically synchronized
    with physical backing store on Mac OS X and OpenVMS.
 
+   .. versionchanged:: 3.10
+      The *trackfd* parameter was added.
+
    This example shows a simple way of using :class:`~mmap.mmap`::
 
       import mmap

Doc/whatsnew/3.10.rst

@@ -831,6 +831,13 @@ linecache
 When a module does not define ``__loader__``, fall back to ``__spec__.loader``.
 (Contributed by Brett Cannon in :issue:`42133`.)
 
+mmap
+----
+
+:class:`mmap.mmap` now has a *trackfd* parameter on Unix; if it is ``False``,
+the file descriptor specified by *fileno* will not be duplicated.
+(Contributed by Zackery Spytz in :issue:`34321`.)
+
 os
 --
 

Lib/test/test_mmap.py

@@ -246,6 +246,16 @@ def test_access_parameter(self):
                 self.assertRaises(TypeError, m.write_byte, 0)
                 m.close()
 
+    @unittest.skipIf(os.name == 'nt', 'trackfd not present on Windows')
+    def test_trackfd_parameter(self):
+        size = 64
+        with open(TESTFN, "wb") as f:
+            f.write(b"a"*size)
+        with open(TESTFN, "r+b") as f:
+            m = mmap.mmap(f.fileno(), size, trackfd=False)
+            self.assertEqual(len(m), size)
+            m.close()
+
     def test_bad_file_desc(self):
         # Try opening a bad file descriptor...
         self.assertRaises(OSError, mmap.mmap, -2, 4096)

Misc/NEWS.d/next/Library/2021-04-15-10-41-51.bpo-34321.36m6_l.rst

@@ -0,0 +1,2 @@
+:class:`mmap.mmap` now has a *trackfd* parameter on Unix; if it is
+``False``, the file descriptor specified by *fileno* will not be duplicated.

Modules/mmapmodule.c

@@ -1136,15 +1136,17 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
     off_t offset = 0;
     int fd, flags = MAP_SHARED, prot = PROT_WRITE | PROT_READ;
     int devzero = -1;
-    int access = (int)ACCESS_DEFAULT;
+    int access = (int)ACCESS_DEFAULT, trackfd = 1;
     static char *keywords[] = {"fileno", "length",
                                "flags", "prot",
-                               "access", "offset", NULL};
+                               "access", "offset", "trackfd", NULL};
 
-    if (!PyArg_ParseTupleAndKeywords(args, kwdict, "in|iii" _Py_PARSE_OFF_T, keywords,
+    if (!PyArg_ParseTupleAndKeywords(args, kwdict,
+                                     "in|iii" _Py_PARSE_OFF_T "p", keywords,
                                      &fd, &map_size, &flags, &prot,
-                                     &access, &offset))
+                                     &access, &offset, &trackfd)) {
         return NULL;
+    }
     if (map_size < 0) {
         PyErr_SetString(PyExc_OverflowError,
                         "memory mapped length must be positive");
@@ -1265,13 +1267,16 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
         }
 #endif
     }
-    else {
+    else if (trackfd) {
         m_obj->fd = _Py_dup(fd);
         if (m_obj->fd == -1) {
             Py_DECREF(m_obj);
             return NULL;
         }
     }
+    else {
+        m_obj->fd = -1;
+    }
 
     m_obj->data = mmap(NULL, map_size,
                        prot, flags,