From e9c75a889f972ca88b9c41d0ddb4b0cf487c5ebe Mon Sep 17 00:00:00 2001 From: Alexis Hunt Date: Fri, 16 Feb 2018 08:51:40 -0500 Subject: [PATCH 1/2] Add a warning to File about mutability. Fixes #47708. --- src/libstd/fs.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 5cea389531f94..1798bf4760b34 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -81,9 +81,18 @@ use time::SystemTime; /// # } /// ``` /// +/// Note that, although read and write methods require a `&mut File`, because +/// of the interfaces for [`Read`] and [`Write`], it is still possible to +/// modify a file through a `&File`, either through methods that take `&File` +/// or by retrieving a raw OS filehandle and modifying the file that way. +/// Additionally, many operating systems allow concurrent modification of files +/// by different processes. Care should be taken not to assume that holding a +/// `&File` means that the file will not change. +/// /// [`Seek`]: ../io/trait.Seek.html /// [`String`]: ../string/struct.String.html /// [`Read`]: ../io/trait.Read.html +/// [`Write`]: ../io/trait.Write.html /// [`BufReader`]: ../io/struct.BufReader.html #[stable(feature = "rust1", since = "1.0.0")] pub struct File { @@ -459,6 +468,9 @@ impl File { /// # Ok(()) /// # } /// ``` + /// + /// Note that this method alters the content of the underlying file, even + /// though it takes `&self` rather than `&mut self`. #[stable(feature = "rust1", since = "1.0.0")] pub fn set_len(&self, size: u64) -> io::Result<()> { self.inner.truncate(size) @@ -557,6 +569,9 @@ impl File { /// # Ok(()) /// # } /// ``` + /// + /// Note that this method alters the permissions of the underlying file, + /// even though it takes `&self` rather than `&mut self`. #[stable(feature = "set_permissions_atomic", since = "1.16.0")] pub fn set_permissions(&self, perm: Permissions) -> io::Result<()> { self.inner.set_permissions(perm.0) From ec905975b85d504abdd428be668346d008bc7a69 Mon Sep 17 00:00:00 2001 From: Alexis Hunt Date: Sat, 17 Feb 2018 08:47:03 -0500 Subject: [PATCH 2/2] Wording fixes from review for File. --- src/libstd/fs.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 1798bf4760b34..292a78278ab0a 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -82,12 +82,12 @@ use time::SystemTime; /// ``` /// /// Note that, although read and write methods require a `&mut File`, because -/// of the interfaces for [`Read`] and [`Write`], it is still possible to -/// modify a file through a `&File`, either through methods that take `&File` -/// or by retrieving a raw OS filehandle and modifying the file that way. +/// of the interfaces for [`Read`] and [`Write`], the holder of a `&File` can +/// still modify the file, either through methods that take `&File` or by +/// retrieving the underlying OS object and modifying the file that way. /// Additionally, many operating systems allow concurrent modification of files -/// by different processes. Care should be taken not to assume that holding a -/// `&File` means that the file will not change. +/// by different processes. Avoid assuming that holding a `&File` means that the +/// file will not change. /// /// [`Seek`]: ../io/trait.Seek.html /// [`String`]: ../string/struct.String.html