languages/rust
languages/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust synced 2024-11-02 13:50:48 +00:00
Code Issues Projects Releases Packages Wiki Activity

Rollup merge of #42925 - tbu-:pr_document_file_open_errors, r=GuillaumeGomez

Browse source 
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
This commit is contained in:
Guillaume Gomez 2017-06-30 22:44:45 +02:00 committed by GitHub
commit db004d4f55
1 changed files with 29 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
src/libstd/fs.rs
View file

@ -653,15 +653,29 @@ pub fn create_new(&mut self, create_new: bool) -> &mut OpenOptions {
/// # Errors
///
/// This function will return an error under a number of different
/// circumstances, to include but not limited to:
/// 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.
///
/// * 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)
/// * [`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,13 @@ pub fn create_new(&mut self, create_new: bool) -> &mut OpenOptions {
///
/// let file = OpenOptions::new().open("foo.txt");
/// ```
///
/// [`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<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
self._open(path.as_ref())