diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -177,14 +177,30 @@
    handled by calling a handler specified by *onerror* or, if that is omitted,
    they raise an exception.
 
+   .. warning::
+
+      The default :func:`rmtree` function is susceptible to so called "symlink
+      attacks": given proper timing and circumstances, an attacker can use it
+      to delete files he wouldn't have acccess to otherwise.  Thus -- on
+      platforms that support the necessary functions :func:`os.fwalk()` and
+      :func:`os.unlinkat()` -- a safe version of :func:`rmtree` is used, which
+      isn't vulnerable.
+
    If *onerror* is provided, it must be a callable that accepts three
-   parameters: *function*, *path*, and *excinfo*. The first parameter,
-   *function*, is the function which raised the exception; it will be
-   :func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or
-   :func:`os.rmdir`.  The second parameter, *path*, will be the path name passed
-   to *function*.  The third parameter, *excinfo*, will be the exception
-   information return by :func:`sys.exc_info`.  Exceptions raised by *onerror*
-   will not be caught.
+   parameters: *function*, *path*, and *excinfo*.
+
+   The first parameter, *function*, is the function which raised the exception;
+   it will be :func:`os.path.islink` or :func:`os.rmdir` and -- depending on
+   the implementation -- :func:`os.listdir` or :func:`os.remove` for the
+   default one or :func:`os.fwalk()` or :func:`os.unlinkat()` for the safe one.
+
+   The second parameter, *path*, will be the path name passed to *function*.
+   The third parameter, *excinfo*, will be the exception information return by
+   :func:`sys.exc_info`.  Exceptions raised by *onerror* will not be caught.
+
+   .. versionchanged:: 3.3
+      Added a safe version that is used automatically if supported by the
+      platform.
 
 
 .. function:: move(src, dst)