From 7cdef0876deb12e3a5a69c9dec2b386fa61a4384 Mon Sep 17 00:00:00 2001
From: Martin Pool <mbp@google.com>
Date: Mon, 11 Apr 2022 19:00:29 -0700
Subject: [PATCH] Document that DirEntry holds the directory open

---
 library/std/src/fs.rs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 10c424269c7d1..433b4d530136b 100644
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -132,6 +132,16 @@ pub struct ReadDir(fs_imp::ReadDir);
 /// An instance of `DirEntry` represents an entry inside of a directory on the
 /// filesystem. Each entry can be inspected via methods to learn about the full
 /// path or possibly other metadata through per-platform extension traits.
+///
+/// # Platform-specific behavior
+///
+/// On Unix, the `DirEntry` struct contains an internal reference to the open
+/// directory. Holding `DirEntry` objects will consume a file handle even
+/// after the `ReadDir` iterator is dropped.
+///
+/// Note that this [may change in the future][changes].
+///
+/// [changes]: io#platform-specific-behavior
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct DirEntry(fs_imp::DirEntry);