From 71252d9b80020d932aa7960a3930684489a6e167 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Tue, 27 Jun 2017 12:09:56 +0200 Subject: [PATCH 1/2] Document possible `io::ErrorKind`s of `fs::open` Try to make clear that this isn't an API guarantee for now, as we likely want to refine these errors in the future, e.g. `ENOSPC` "No space left on device". CC #40322 --- src/libstd/fs.rs | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 5b8c0c339900d..f1ec4d2dff01d 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -653,15 +653,29 @@ impl OpenOptions { /// # Errors /// /// This function will return an error under a number of different - /// circumstances, to include but not limited to: - /// - /// * Opening a file that does not exist without setting `create` or - /// `create_new`. - /// * Attempting to open a file with access that the user lacks - /// permissions for - /// * Filesystem-level errors (full disk, etc) - /// * Invalid combinations of open options (truncate without write access, - /// no access mode set, etc) + /// circumstances. Some of these error conditions are listed here, together + /// with their [`ErrorKind`]. The mapping to `ErrorKind`s is not part of + /// the compatiblity contract of the function, especially the `Other` kind + /// might change to more specific kinds in the future. + /// + /// * `NotFound`: The specified file does not exist and neither `create` or + /// `create_new` is set, + /// * `NotFound`: One of the directory components of the file path does not + /// exist. + /// * `PermissionDenied`: The user lacks permission to get the specified + /// access rights for the file. + /// * `PermissionDenied`: The user lacks permission to open one of the + /// directory components of the specified path. + /// * `AlreadyExists`: `create_new` was specified and the file already + /// exists. + /// * `InvalidInput`: Invalid combinations of open options (truncate + /// without write access, no access mode set, etc.). + /// * `Other`: One of the directory components of the specified file path + /// was not, in fact, a directory. + /// * `Other`: Filesystem-level errors: full disk, write permission + /// requested on a read-only file system, exceeded disk quota, too many + /// open files, too long filename, too many symbolic links in the + /// specified path (Unix-like systems only), etc. /// /// # Examples /// @@ -670,6 +684,8 @@ impl OpenOptions { /// /// let file = OpenOptions::new().open("foo.txt"); /// ``` + /// + /// [`ErrorKind`]: ../io/enum.ErrorKind.html #[stable(feature = "rust1", since = "1.0.0")] pub fn open>(&self, path: P) -> io::Result { self._open(path.as_ref()) From 2783d0f7dac17f764c6580a04877e6813be574d2 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Wed, 28 Jun 2017 13:43:56 +0200 Subject: [PATCH 2/2] Add links to the `ErrorKind` variants in errors of `open` --- src/libstd/fs.rs | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index f1ec4d2dff01d..88994b284c90d 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -654,25 +654,25 @@ impl OpenOptions { /// /// This function will return an error under a number of different /// circumstances. Some of these error conditions are listed here, together - /// with their [`ErrorKind`]. The mapping to `ErrorKind`s is not part of + /// with their [`ErrorKind`]. The mapping to [`ErrorKind`]s is not part of /// the compatiblity contract of the function, especially the `Other` kind /// might change to more specific kinds in the future. /// - /// * `NotFound`: The specified file does not exist and neither `create` or - /// `create_new` is set, - /// * `NotFound`: One of the directory components of the file path does not - /// exist. - /// * `PermissionDenied`: The user lacks permission to get the specified + /// * [`NotFound`]: The specified file does not exist and neither `create` + /// or `create_new` is set. + /// * [`NotFound`]: One of the directory components of the file path does + /// not exist. + /// * [`PermissionDenied`]: The user lacks permission to get the specified /// access rights for the file. - /// * `PermissionDenied`: The user lacks permission to open one of the + /// * [`PermissionDenied`]: The user lacks permission to open one of the /// directory components of the specified path. - /// * `AlreadyExists`: `create_new` was specified and the file already + /// * [`AlreadyExists`]: `create_new` was specified and the file already /// exists. - /// * `InvalidInput`: Invalid combinations of open options (truncate + /// * [`InvalidInput`]: Invalid combinations of open options (truncate /// without write access, no access mode set, etc.). - /// * `Other`: One of the directory components of the specified file path + /// * [`Other`]: One of the directory components of the specified file path /// was not, in fact, a directory. - /// * `Other`: Filesystem-level errors: full disk, write permission + /// * [`Other`]: Filesystem-level errors: full disk, write permission /// requested on a read-only file system, exceeded disk quota, too many /// open files, too long filename, too many symbolic links in the /// specified path (Unix-like systems only), etc. @@ -686,6 +686,11 @@ impl OpenOptions { /// ``` /// /// [`ErrorKind`]: ../io/enum.ErrorKind.html + /// [`AlreadyExists`]: ../io/enum.ErrorKind.html#variant.AlreadyExists + /// [`InvalidInput`]: ../io/enum.ErrorKind.html#variant.InvalidInput + /// [`NotFound`]: ../io/enum.ErrorKind.html#variant.NotFound + /// [`Other`]: ../io/enum.ErrorKind.html#variant.Other + /// [`PermissionDenied`]: ../io/enum.ErrorKind.html#variant.PermissionDenied #[stable(feature = "rust1", since = "1.0.0")] pub fn open>(&self, path: P) -> io::Result { self._open(path.as_ref())