@@ -241,13 +241,30 @@ in various ways.  There is a separate error indicator for each thread.
    exception instance.
 
 
+.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
+
+   Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a second
+   filename object, for raising errors when a function that takes two filenames
+   fails.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
    is given as a C string.  *filename* is decoded from the filesystem encoding
    (:func:`os.fsdecode`).
 
 
+.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenames(PyObject *type, const char *filename, const char *filename2)
+
+   Similar to :c:func:`PyErr_SetFromErrnoWithFilename`, but accepts a
+   second filename.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
 
    This is a convenience function to raise :exc:`WindowsError`. If called with
@@ -266,33 +283,52 @@ in various ways.  There is a separate error indicator for each thread.
    specifying the exception type to be raised. Availability: Windows.
 
 
-.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
-
-   Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
-   that if *filenameObject* is not *NULL*, it is passed to the constructor of
-   :exc:`WindowsError` as a third parameter.  Availability: Windows.
-
-
 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
    filename is given as a C string.  *filename* is decoded from the filesystem
    encoding (:func:`os.fsdecode`).  Availability: Windows.
 
 
+.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenames(int ierr, const char *filename, const char *filename2)
+
+   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, but accepts
+   a second filename.  Availability: Windows.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
    additional parameter specifying the exception type to be raised.
    Availability: Windows.
 
 
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
+
+   Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
+   but accepts a second filename object.
+   Availability: Windows.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
    parameter specifying the exception type to be raised. Availability: Windows.
 
 
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenames(PyObject *type, int ierr, const char *filename, const char *filename2)
+
+   Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilename`,
+   but accepts a second filename object.
+   Availability: Windows.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
 
    This is a convenience function to raise :exc:`ImportError`. *msg* will be
 
@@ -29,7 +29,7 @@
 # reference to the item argument!
 
 # The parameter names are as they appear in the API manual, not the source
-# code. 
+# code.
 
 PyBool_FromLong:PyObject*::+1:
 PyBool_FromLong:long:v:0:
@@ -317,20 +317,36 @@ PyErr_SetExcFromWindowsErrWithFilename:PyObject*:type:0:
 PyErr_SetExcFromWindowsErrWithFilename:int:ierr::
 PyErr_SetExcFromWindowsErrWithFilename:const char*:filename::
 
+PyErr_SetExcFromWindowsErrWithFilenames:PyObject*::null:
+PyErr_SetExcFromWindowsErrWithFilenames:PyObject*:type:0:
+PyErr_SetExcFromWindowsErrWithFilenames:int:ierr::
+PyErr_SetExcFromWindowsErrWithFilenames:const char*:filename::
+PyErr_SetExcFromWindowsErrWithFilenames:const char*:filename2::
+
 PyErr_SetFromErrno:PyObject*::null:
 PyErr_SetFromErrno:PyObject*:type:0:
 
 PyErr_SetFromErrnoWithFilename:PyObject*::null:
 PyErr_SetFromErrnoWithFilename:PyObject*:type:0:
 PyErr_SetFromErrnoWithFilename:const char*:filename::
 
+PyErr_SetFromErrnoWithFilenames:PyObject*::null:
+PyErr_SetFromErrnoWithFilenames:PyObject*:type:0:
+PyErr_SetFromErrnoWithFilenames:const char*:filename::
+PyErr_SetFromErrnoWithFilenames:const char*:filename2::
+
 PyErr_SetFromWindowsErr:PyObject*::null:
 PyErr_SetFromWindowsErr:int:ierr::
 
 PyErr_SetFromWindowsErrWithFilename:PyObject*::null:
 PyErr_SetFromWindowsErrWithFilename:int:ierr::
 PyErr_SetFromWindowsErrWithFilename:const char*:filename::
 
+PyErr_SetFromWindowsErrWithFilenames:PyObject*::null:
+PyErr_SetFromWindowsErrWithFilenames:int:ierr::
+PyErr_SetFromWindowsErrWithFilenames:const char*:filename::
+PyErr_SetFromWindowsErrWithFilenames:const char*:filename2::
+
 PyErr_SetInterrupt:void:::
 
 PyErr_SetNone:void:::
@@ -907,7 +923,7 @@ PyNumber_Xor:PyObject*::+1:
 PyNumber_Xor:PyObject*:o1:0:
 PyNumber_Xor:PyObject*:o2:0:
 
-PyObject_AsFileDescriptor:int::: 
+PyObject_AsFileDescriptor:int:::
 PyObject_AsFileDescriptor:PyObject*:o:0:
 
 PyObject_Call:PyObject*::+1:
 
@@ -253,6 +253,11 @@ The following exceptions are the exceptions that are usually raised.
    For exceptions that involve a file system path (such as :func:`open` or
    :func:`os.unlink`), the exception instance will contain an additional
    attribute, :attr:`filename`, which is the file name passed to the function.
+   For functions that involve two file system paths (such as
+   :func:`os.rename`), the exception instance will contain a second
+   :attr:`filename2` attribute corresponding to the second file name passed
+   to the function.
+
 
    .. versionchanged:: 3.3
       :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`,
@@ -263,7 +268,7 @@ The following exceptions are the exceptions that are usually raised.
 
       The :attr:`filename` attribute is now the original file name passed to
       the function, instead of the name encoded to or decoded from the
-      filesystem encoding.
+      filesystem encoding.  Also, the :attr:`filename2` attribute was added.
 
 
 .. exception:: OverflowError
 
@@ -53,6 +53,7 @@ typedef struct {
     PyObject *myerrno;
     PyObject *strerror;
     PyObject *filename;
+    PyObject *filename2;
 #ifdef MS_WINDOWS
     PyObject *winerror;
 #endif
@@ -225,13 +226,23 @@ PyAPI_FUNC(PyObject *) PyErr_NoMemory(void);
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrno(PyObject *);
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilenameObject(
     PyObject *, PyObject *);
+PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilenameObjects(
+    PyObject *, PyObject *, PyObject *);
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilename(
     PyObject *exc,
     const char *filename   /* decoded from the filesystem encoding */
     );
+PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilenames(
+    PyObject *exc,
+    /* decoded from the filesystem encoding */
+    const char *filename,
+    const char *filename2
+    );
 #if defined(MS_WINDOWS) && !defined(Py_LIMITED_API)
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithUnicodeFilename(
     PyObject *, const Py_UNICODE *);
+PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithUnicodeFilenames(
+    PyObject *, const Py_UNICODE *, const Py_UNICODE *);
 #endif /* MS_WINDOWS */
 
 PyAPI_FUNC(PyObject *) PyErr_Format(
@@ -245,22 +256,41 @@ PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithFilename(
     int ierr,
     const char *filename        /* decoded from the filesystem encoding */
     );
+PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithFilenames(
+    int ierr,
+    /* decoded from the filesystem encoding */
+    const char *filename,
+    const char *filename2
+    );
 #ifndef Py_LIMITED_API
 /* XXX redeclare to use WSTRING */
 PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithUnicodeFilename(
     int, const Py_UNICODE *);
+PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithUnicodeFilenames(
+    int, const Py_UNICODE *, const Py_UNICODE *);
 #endif
 PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErr(int);
 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilenameObject(
     PyObject *,int, PyObject *);
+PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilenameObjects(
+    PyObject *,int, PyObject *, PyObject *);
 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilename(
     PyObject *exc,
     int ierr,
     const char *filename        /* decoded from the filesystem encoding */
     );
+PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilenames(
+    PyObject *exc,
+    int ierr,
+    /* decoded from the filesystem encoding */
+    const char *filename,
+    const char *filename2
+    );
 #ifndef Py_LIMITED_API
 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithUnicodeFilename(
     PyObject *,int, const Py_UNICODE *);
+PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithUnicodeFilenames(
+    PyObject *,int, const Py_UNICODE *, const Py_UNICODE *);
 #endif
 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErr(PyObject *, int);
 #endif /* MS_WINDOWS */
 
@@ -266,8 +266,8 @@ def testAttributes(self):
             (OSError, ('foo', 'bar', 'baz'),
                 {'args' : ('foo', 'bar'), 'filename' : 'baz',
                  'errno' : 'foo', 'strerror' : 'bar'}),
-            (OSError, ('foo', 'bar', 'baz', 'quux'),
-                {'args' : ('foo', 'bar', 'baz', 'quux')}),
+            (OSError, ('foo', 'bar', 'baz', None, 'quux'),
+                {'args' : ('foo', 'bar'), 'filename' : 'baz', 'filename2': 'quux'}),
             (OSError, ('errnoStr', 'strErrorStr', 'filenameStr'),
                 {'args' : ('errnoStr', 'strErrorStr'),
                  'strerror' : 'strErrorStr', 'errno' : 'errnoStr',
 
@@ -1121,6 +1121,23 @@ def test_fs_holes(self):
                 # http://lists.freebsd.org/pipermail/freebsd-amd64/2012-January/014332.html
                 raise unittest.SkipTest("OSError raised!")
 
+    def test_path_error2(self):
+        """
+        Test functions that call path_error2(), providing two filenames in their exceptions.
+        """
+        for name in ("rename", "replace", "link", "symlink"):
+            function = getattr(os, name, None)
+
+            if function:
+                for dst in ("noodly2", support.TESTFN):
+                    try:
+                        function('doesnotexistfilename', dst)
+                    except OSError as e:
+                        self.assertIn("'doesnotexistfilename' -> '{}'".format(dst), str(e))
+                        break
+                else:
+                    self.fail("No valid path_error2() test for os." + name)
+
 class PosixGroupsTester(unittest.TestCase):
 
     def setUp(self):
 
@@ -32,6 +32,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #20517: Functions in the os module that accept two filenames
+  now register both filenames in the exception on failure.
+
 - Issue #20563: The ipaddress module API is now considered stable.
 
 - Issue #14983: email.generator now always adds a line end after each MIME
@@ -236,6 +239,15 @@ Build
 
 - Issue #20465: Update SQLite shipped with OS X installer to 3.8.3.
 
+C-API
+-----
+
+- Issue #20517: Added new functions allowing OSError exceptions to reference
+  two filenames instead of one: PyErr_SetFromErrnoWithFilenameObjects(),
+  PyErr_SetFromErrnoWithFilenames(), PyErr_SetFromWindowsErrWithFilenames(),
+  PyErr_SetExcFromWindowsErrWithFilenameObjects(), and
+  PyErr_SetExcFromWindowsErrWithFilenames().
+
 Documentation
 -------------
 
 
@@ -1313,6 +1313,19 @@ path_error(path_t *path)
 }
 
 
+static PyObject *
+path_error2(path_t *path, path_t *path2)
+{
+#ifdef MS_WINDOWS
+    return PyErr_SetExcFromWindowsErrWithFilenameObjects(PyExc_OSError,
+            0, path->object, path2->object);
+#else
+    return PyErr_SetFromErrnoWithFilenameObjects(PyExc_OSError,
+        path->object, path2->object);
+#endif
+}
+
+
 /* POSIX generic methods */
 
 static PyObject *
@@ -3518,7 +3531,7 @@ posix_link(PyObject *self, PyObject *args, PyObject *kwargs)
     Py_END_ALLOW_THREADS
 
     if (!result) {
-        return_value = path_error(&src);
+        return_value = path_error2(&src, &dst);
         goto exit;
     }
 #else
@@ -3536,7 +3549,7 @@ posix_link(PyObject *self, PyObject *args, PyObject *kwargs)
     Py_END_ALLOW_THREADS
 
     if (result) {
-        return_value = path_error(&src);
+        return_value = path_error2(&src, &dst);
         goto exit;
     }
 #endif
@@ -4284,7 +4297,7 @@ internal_rename(PyObject *args, PyObject *kwargs, int is_replace)
     Py_END_ALLOW_THREADS
 
     if (!result) {
-        return_value = path_error(&src);
+        return_value = path_error2(&src, &dst);
         goto exit;
     }
 
@@ -4299,7 +4312,7 @@ internal_rename(PyObject *args, PyObject *kwargs, int is_replace)
     Py_END_ALLOW_THREADS
 
     if (result) {
-        return_value = path_error(&src);
+        return_value = path_error2(&src, &dst);
         goto exit;
     }
 #endif
@@ -7345,7 +7358,7 @@ posix_symlink(PyObject *self, PyObject *args, PyObject *kwargs)
     Py_END_ALLOW_THREADS
 
     if (!result) {
-        return_value = path_error(&src);
+        return_value = path_error2(&src, &dst);
         goto exit;
     }
 
@@ -7361,7 +7374,7 @@ posix_symlink(PyObject *self, PyObject *args, PyObject *kwargs)
     Py_END_ALLOW_THREADS
 
     if (result) {
-        return_value = path_error(&src);
+        return_value = path_error2(&src, &dst);
         goto exit;
     }
 #endif