Skip to content

Commit 85e6e82

Browse files
committed
reword the paragraph on file description ownership
1 parent 03c28d5 commit 85e6e82

File tree

1 file changed

+10
-9
lines changed

1 file changed

+10
-9
lines changed

library/std/src/io/mod.rs

+10-9
Original file line numberDiff line numberDiff line change
@@ -263,15 +263,16 @@
263263
//! allocator or a memory mapping library) and now accessing the file descriptor will interfere in
264264
//! arbitrarily destructive ways with that other library.
265265
//!
266-
//! Note that this does not talk about performing other operations on the file descriptor, such as
267-
//! reading or writing. For example, on Unix, the [`OwnedFd`] and [`BorrowedFd`] types from the
268-
//! standard library do *not* exclude that there is other code that reads or writes the same
269-
//! underlying object, and indeed there exist safe functions like `BorrowedFd::try_clone_to_owned`
270-
//! that can be used to read or write an object even after the end of the borrow. However, user code
271-
//! might want to rely on keeping the object behind a file descriptor completely private and
272-
//! protected against reads or writes from other parts of the program. Whether that is sound is
273-
//! [currently unclear](https://github.com/rust-lang/rust/issues/114167). Certainly, `OwnedFd` as a
274-
//! type does not provide any promise that the underlying file descriptor has not been cloned.
266+
//! Note that exclusive ownership of a file descriptor does *not* imply exclusive ownership of the
267+
//! underlying kernel object that the file descriptor references (also called "file description" on
268+
//! some operating systems). An owned file descriptor can have duplicates, i.e., other file
269+
//! descriptors that share the same kernel object. The exact rules around ownership of kernel
270+
//! objects are [still unclear](https://github.com/rust-lang/rust/issues/114167). Until that is
271+
//! clarified, the general advice is not to perform *any* operations on file descriptors that were
272+
//! never borrowed to or owned by you. In other words, receiving a borrowed file descriptor *does*
273+
//! give you the right to make a duplicate and use that duplicate beyond the end of the borrow, but
274+
//! nothing gives you the right to just `write` to a file descriptor that never even got borrowed to
275+
//! you.
275276
//!
276277
//! [`File`]: crate::fs::File
277278
//! [`TcpStream`]: crate::net::TcpStream

0 commit comments

Comments
 (0)