From 7f36a18df8481de61021593a4fd5d3188b09d6bb Mon Sep 17 00:00:00 2001 From: Nathan Date: Mon, 9 Nov 2015 19:43:12 -0500 Subject: [PATCH 1/3] Added platform notes to std::fs public functions. --- src/libstd/fs.rs | 200 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 165 insertions(+), 35 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 3975af74346fb..276d6efd8ac29 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -758,11 +758,19 @@ impl AsInner for DirEntry { /// guarantee that the file is immediately deleted (e.g. depending on /// platform, other open file descriptors may prevent immediate removal). /// +/// # Platform behavior +/// +/// This function currently corresponds to the `unlink` function on Unix +/// and the `DeleteFile` function on Windows. Note that, this +/// [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// -/// This function will return an error if `path` points to a directory, if the -/// user lacks permissions to remove the file, or if some other filesystem-level -/// error occurs. +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * `path` points to a directory +/// * The user lacks permissions to remove the file /// /// # Examples /// @@ -785,6 +793,20 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// This function will traverse symbolic links to query information about the /// destination file. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `stat` function on Unix +/// and the `GetFileAttributesEx` function on Windows. Note that, this +/// [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// +/// # Errors +/// +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * The user lacks permissions to perform `metadata` call on `path` +/// * `path` does not exist +/// /// # Examples /// /// ```rust @@ -796,12 +818,6 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// # Ok(()) /// # } /// ``` -/// -/// # Errors -/// -/// This function will return an error if the user lacks the requisite -/// permissions to perform a `metadata` call on the given `path` or if there -/// is no entry in the filesystem at the provided path. #[stable(feature = "rust1", since = "1.0.0")] pub fn metadata>(path: P) -> io::Result { fs_imp::stat(path.as_ref()).map(Metadata) @@ -809,6 +825,20 @@ pub fn metadata>(path: P) -> io::Result { /// Query the metadata about a file without following symlinks. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `lstat` function on Unix +/// and the `GetFileAttributesEx` function on Windows. Note that, this +/// [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// +/// # Errors +/// +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * The user lacks permissions to perform `metadata` call on `path` +/// * `path` does not exist +/// /// # Examples /// /// ```rust @@ -829,12 +859,20 @@ pub fn symlink_metadata>(path: P) -> io::Result { /// /// This will not work if the new name is on a different mount point. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `rename` function on Unix +/// and the `MoveFileEx` function with the `MOVEFILE_REPLACE_EXISTING` flag on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// -/// This function will return an error if the provided `from` doesn't exist, if -/// the process lacks permissions to view the contents, if `from` and `to` -/// reside on separate filesystems, or if some other intermittent I/O error -/// occurs. +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * `from` does not exist +/// * The user lacks permissions to view contents +/// * `from` and `to` are on separate filesystems /// /// # Examples /// @@ -861,6 +899,14 @@ pub fn rename, Q: AsRef>(from: P, to: Q) -> io::Result<()> /// /// On success, the total number of bytes copied is returned. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `open` function in Unix +/// with `O_RDONLY` for `from` and `O_WRONLY`, `O_CREAT`, and `O_TRUNC` for `to`. +/// `O_CLOEXEC` is set for returned file descriptors. +/// On Windows, this function currently corresponds to `CopyFileEx`. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// /// This function will return an error in the following situations, but is not @@ -890,6 +936,19 @@ pub fn copy, Q: AsRef>(from: P, to: Q) -> io::Result { /// The `dst` path will be a link pointing to the `src` path. Note that systems /// often require these two paths to both be located on the same filesystem. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `link` function on Unix +/// and the `CreateHardLink` function on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// +/// # Errors +/// +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * The `src` path is not a file or doesn't exist +/// /// # Examples /// /// ``` @@ -933,11 +992,20 @@ pub fn soft_link, Q: AsRef>(src: P, dst: Q) -> io::Result<( /// Reads a symbolic link, returning the file that the link points to. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `readlink` function on Unix +/// and the `CreateFile` function with `FILE_FLAG_OPEN_REPARSE_POINT` and +/// `FILE_FLAG_BACKUP_SEMANTICS` flags on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// -/// This function will return an error on failure. Failure conditions include -/// reading a file that does not exist or reading a file that is not a symbolic -/// link. +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * `path` is not a symbolic link +/// * `path` does not exist /// /// # Examples /// @@ -957,8 +1025,19 @@ pub fn read_link>(path: P) -> io::Result { /// Returns the canonical form of a path with all intermediate components /// normalized and symbolic links resolved. /// -/// This function may return an error in situations like where the path does not -/// exist, a component in the path is not a directory, or an I/O error happens. +/// # Platform behavior +/// +/// This function currently corresponds to the `realpath` function on Unix +/// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// +/// # Errors +/// +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * `path` does not exist +/// * A component in path is not a directory /// /// # Examples /// @@ -977,10 +1056,19 @@ pub fn canonicalize>(path: P) -> io::Result { /// Creates a new, empty directory at the provided path /// +/// # Platform behavior +/// +/// This function currently corresponds to the `mkdir` function on Unix +/// and the `CreateDirectory` function on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// -/// This function will return an error if the user lacks permissions to make a -/// new directory at the provided `path`, or if the directory already exists. +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * User lacks permissions to create directory at `path` +/// * `path` already exists /// /// # Examples /// @@ -1000,9 +1088,18 @@ pub fn create_dir>(path: P) -> io::Result<()> { /// Recursively create a directory and all of its parent components if they /// are missing. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `mkdir` function on Unix +/// and the `CreateDirectory` function on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// -/// This function will fail if any directory in the path specified by `path` +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * If any directory in the path specified by `path` /// does not already exist and it could not be created otherwise. The specific /// error conditions for when a directory is being created (after it is /// determined to not exist) are outlined by `fs::create_dir`. @@ -1024,10 +1121,19 @@ pub fn create_dir_all>(path: P) -> io::Result<()> { /// Removes an existing, empty directory. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `rmdir` function on Unix +/// and the `RemoveDirectory` function on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// -/// This function will return an error if the user lacks permissions to remove -/// the directory at the provided `path`, or if the directory isn't empty. +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * The user lacks permissions to remove the directory at the provided `path` +/// * The directory isn't empty /// /// # Examples /// @@ -1050,6 +1156,13 @@ pub fn remove_dir>(path: P) -> io::Result<()> { /// This function does **not** follow symbolic links and it will simply remove the /// symbolic link itself. /// +/// # Platform behavior +/// +/// This function currently corresponds to `opendir`, `lstat`, `rm` and `rmdir` functions on Unix +/// and the `FindFirstFile`, `GetFileAttributesEx`, `DeleteFile`, and `RemoveDirectory` functions +/// on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// /// # Errors /// /// See `file::remove_file` and `fs::remove_dir`. @@ -1087,6 +1200,21 @@ fn _remove_dir_all(path: &Path) -> io::Result<()> { /// The iterator will yield instances of `io::Result`. New errors may /// be encountered after an iterator is initially constructed. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `opendir` function on Unix +/// and the `FindFirstFile` function on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// +/// # Errors +/// +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * The provided `path` doesn't exist +/// * The process lacks permissions to view the contents +/// * The `path` points at a non-directory file +/// /// # Examples /// /// ``` @@ -1109,12 +1237,6 @@ fn _remove_dir_all(path: &Path) -> io::Result<()> { /// Ok(()) /// } /// ``` -/// -/// # Errors -/// -/// This function will return an error if the provided `path` doesn't exist, if -/// the process lacks permissions to view the contents or if the `path` points -/// at a non-directory file #[stable(feature = "rust1", since = "1.0.0")] pub fn read_dir>(path: P) -> io::Result { fs_imp::readdir(path.as_ref()).map(ReadDir) @@ -1180,6 +1302,20 @@ impl Iterator for WalkDir { /// Changes the permissions found on a file or a directory. /// +/// # Platform behavior +/// +/// This function currently corresponds to the `chmod` function on Unix +/// and the `SetFileAttributes` function on Windows. +/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// +/// # Errors +/// +/// This function will return an error in the following situations, but is not +/// limited to just these cases: +/// +/// * `path` does not exist +/// * The user lacks the permission to change attributes of the file +/// /// # Examples /// /// ``` @@ -1192,12 +1328,6 @@ impl Iterator for WalkDir { /// # Ok(()) /// # } /// ``` -/// -/// # Errors -/// -/// This function will return an error if the provided `path` doesn't exist, if -/// the process lacks permissions to change the attributes of the file, or if -/// some other I/O error is encountered. #[stable(feature = "set_permissions", since = "1.1.0")] pub fn set_permissions>(path: P, perm: Permissions) -> io::Result<()> { From 66e842b6de633dd1099992782d1175c366ee27f7 Mon Sep 17 00:00:00 2001 From: Nathan Date: Mon, 9 Nov 2015 20:13:10 -0500 Subject: [PATCH 2/3] Links and punctionaction fixes. --- src/libstd/fs.rs | 100 +++++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 43 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 276d6efd8ac29..1819a308b3cbd 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -761,16 +761,17 @@ impl AsInner for DirEntry { /// # Platform behavior /// /// This function currently corresponds to the `unlink` function on Unix -/// and the `DeleteFile` function on Windows. Note that, this -/// [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// and the `DeleteFile` function on Windows. +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * `path` points to a directory -/// * The user lacks permissions to remove the file +/// * `path` points to a directory. +/// * The user lacks permissions to remove the file. /// /// # Examples /// @@ -796,16 +797,17 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// # Platform behavior /// /// This function currently corresponds to the `stat` function on Unix -/// and the `GetFileAttributesEx` function on Windows. Note that, this -/// [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// and the `GetFileAttributesEx` function on Windows. +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * The user lacks permissions to perform `metadata` call on `path` -/// * `path` does not exist +/// * The user lacks permissions to perform `metadata` call on `path`. +/// * `path` does not exist. /// /// # Examples /// @@ -828,16 +830,17 @@ pub fn metadata>(path: P) -> io::Result { /// # Platform behavior /// /// This function currently corresponds to the `lstat` function on Unix -/// and the `GetFileAttributesEx` function on Windows. Note that, this -/// [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// and the `GetFileAttributesEx` function on Windows. +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * The user lacks permissions to perform `metadata` call on `path` -/// * `path` does not exist +/// * The user lacks permissions to perform `metadata` call on `path`. +/// * `path` does not exist. /// /// # Examples /// @@ -863,16 +866,17 @@ pub fn symlink_metadata>(path: P) -> io::Result { /// /// This function currently corresponds to the `rename` function on Unix /// and the `MoveFileEx` function with the `MOVEFILE_REPLACE_EXISTING` flag on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * `from` does not exist -/// * The user lacks permissions to view contents -/// * `from` and `to` are on separate filesystems +/// * `from` does not exist. +/// * The user lacks permissions to view contents. +/// * `from` and `to` are on separate filesystems. /// /// # Examples /// @@ -905,17 +909,18 @@ pub fn rename, Q: AsRef>(from: P, to: Q) -> io::Result<()> /// with `O_RDONLY` for `from` and `O_WRONLY`, `O_CREAT`, and `O_TRUNC` for `to`. /// `O_CLOEXEC` is set for returned file descriptors. /// On Windows, this function currently corresponds to `CopyFileEx`. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * The `from` path is not a file -/// * The `from` file does not exist +/// * The `from` path is not a file. +/// * The `from` file does not exist. /// * The current process does not have the permission rights to access -/// `from` or write `to` +/// `from` or write `to`. /// /// # Examples /// @@ -940,14 +945,15 @@ pub fn copy, Q: AsRef>(from: P, to: Q) -> io::Result { /// /// This function currently corresponds to the `link` function on Unix /// and the `CreateHardLink` function on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * The `src` path is not a file or doesn't exist +/// * The `src` path is not a file or doesn't exist. /// /// # Examples /// @@ -997,15 +1003,16 @@ pub fn soft_link, Q: AsRef>(src: P, dst: Q) -> io::Result<( /// This function currently corresponds to the `readlink` function on Unix /// and the `CreateFile` function with `FILE_FLAG_OPEN_REPARSE_POINT` and /// `FILE_FLAG_BACKUP_SEMANTICS` flags on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * `path` is not a symbolic link -/// * `path` does not exist +/// * `path` is not a symbolic link. +/// * `path` does not exist. /// /// # Examples /// @@ -1029,15 +1036,16 @@ pub fn read_link>(path: P) -> io::Result { /// /// This function currently corresponds to the `realpath` function on Unix /// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * `path` does not exist -/// * A component in path is not a directory +/// * `path` does not exist. +/// * A component in path is not a directory. /// /// # Examples /// @@ -1060,15 +1068,16 @@ pub fn canonicalize>(path: P) -> io::Result { /// /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * User lacks permissions to create directory at `path` -/// * `path` already exists +/// * User lacks permissions to create directory at `path`. +/// * `path` already exists. /// /// # Examples /// @@ -1092,7 +1101,8 @@ pub fn create_dir>(path: P) -> io::Result<()> { /// /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// @@ -1125,15 +1135,16 @@ pub fn create_dir_all>(path: P) -> io::Result<()> { /// /// This function currently corresponds to the `rmdir` function on Unix /// and the `RemoveDirectory` function on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * The user lacks permissions to remove the directory at the provided `path` -/// * The directory isn't empty +/// * The user lacks permissions to remove the directory at the provided `path`. +/// * The directory isn't empty. /// /// # Examples /// @@ -1161,7 +1172,8 @@ pub fn remove_dir>(path: P) -> io::Result<()> { /// This function currently corresponds to `opendir`, `lstat`, `rm` and `rmdir` functions on Unix /// and the `FindFirstFile`, `GetFileAttributesEx`, `DeleteFile`, and `RemoveDirectory` functions /// on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// @@ -1204,16 +1216,17 @@ fn _remove_dir_all(path: &Path) -> io::Result<()> { /// /// This function currently corresponds to the `opendir` function on Unix /// and the `FindFirstFile` function on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * The provided `path` doesn't exist -/// * The process lacks permissions to view the contents -/// * The `path` points at a non-directory file +/// * The provided `path` doesn't exist. +/// * The process lacks permissions to view the contents. +/// * The `path` points at a non-directory file. /// /// # Examples /// @@ -1306,15 +1319,16 @@ impl Iterator for WalkDir { /// /// This function currently corresponds to the `chmod` function on Unix /// and the `SetFileAttributes` function on Windows. -/// Note that, this [may change in the future.][https://github.com/rust-lang/rust/pull/28613] +/// Note that, this [may change in the future][changes]. +/// [changes]: https://github.com/rust-lang/rust/pull/28613 /// /// # Errors /// /// This function will return an error in the following situations, but is not /// limited to just these cases: /// -/// * `path` does not exist -/// * The user lacks the permission to change attributes of the file +/// * `path` does not exist. +/// * The user lacks the permission to change attributes of the file. /// /// # Examples /// From 3e9d5fea48f616c1052d38e67b18e98624210867 Mon Sep 17 00:00:00 2001 From: Nathan Date: Mon, 30 Nov 2015 21:23:19 -0500 Subject: [PATCH 3/3] Adjusted heading and created dedicated section in std::io docs --- src/libstd/fs.rs | 60 ++++++++++++++++++++++---------------------- src/libstd/io/mod.rs | 9 +++++++ 2 files changed, 39 insertions(+), 30 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 1819a308b3cbd..635ed91f35da4 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -715,7 +715,7 @@ impl DirEntry { /// This function will not traverse symlinks if this entry points at a /// symlink. /// - /// # Platform behavior + /// # Platform-specific behavior /// /// On Windows this function is cheap to call (no extra system calls /// needed), but on Unix platforms this function is the equivalent of @@ -730,7 +730,7 @@ impl DirEntry { /// This function will not traverse symlinks if this entry points at a /// symlink. /// - /// # Platform behavior + /// # Platform-specific behavior /// /// On Windows and most Unix platforms this function is free (no extra /// system calls needed), but some Unix platforms may require the equivalent @@ -758,12 +758,12 @@ impl AsInner for DirEntry { /// guarantee that the file is immediately deleted (e.g. depending on /// platform, other open file descriptors may prevent immediate removal). /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `unlink` function on Unix /// and the `DeleteFile` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -794,12 +794,12 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// This function will traverse symbolic links to query information about the /// destination file. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `stat` function on Unix /// and the `GetFileAttributesEx` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -827,12 +827,12 @@ pub fn metadata>(path: P) -> io::Result { /// Query the metadata about a file without following symlinks. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `lstat` function on Unix /// and the `GetFileAttributesEx` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -862,12 +862,12 @@ pub fn symlink_metadata>(path: P) -> io::Result { /// /// This will not work if the new name is on a different mount point. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `rename` function on Unix /// and the `MoveFileEx` function with the `MOVEFILE_REPLACE_EXISTING` flag on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -903,14 +903,14 @@ pub fn rename, Q: AsRef>(from: P, to: Q) -> io::Result<()> /// /// On success, the total number of bytes copied is returned. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `open` function in Unix /// with `O_RDONLY` for `from` and `O_WRONLY`, `O_CREAT`, and `O_TRUNC` for `to`. /// `O_CLOEXEC` is set for returned file descriptors. /// On Windows, this function currently corresponds to `CopyFileEx`. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -941,12 +941,12 @@ pub fn copy, Q: AsRef>(from: P, to: Q) -> io::Result { /// The `dst` path will be a link pointing to the `src` path. Note that systems /// often require these two paths to both be located on the same filesystem. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `link` function on Unix /// and the `CreateHardLink` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -998,13 +998,13 @@ pub fn soft_link, Q: AsRef>(src: P, dst: Q) -> io::Result<( /// Reads a symbolic link, returning the file that the link points to. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `readlink` function on Unix /// and the `CreateFile` function with `FILE_FLAG_OPEN_REPARSE_POINT` and /// `FILE_FLAG_BACKUP_SEMANTICS` flags on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1032,12 +1032,12 @@ pub fn read_link>(path: P) -> io::Result { /// Returns the canonical form of a path with all intermediate components /// normalized and symbolic links resolved. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `realpath` function on Unix /// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1064,12 +1064,12 @@ pub fn canonicalize>(path: P) -> io::Result { /// Creates a new, empty directory at the provided path /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1097,12 +1097,12 @@ pub fn create_dir>(path: P) -> io::Result<()> { /// Recursively create a directory and all of its parent components if they /// are missing. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1131,12 +1131,12 @@ pub fn create_dir_all>(path: P) -> io::Result<()> { /// Removes an existing, empty directory. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `rmdir` function on Unix /// and the `RemoveDirectory` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1167,13 +1167,13 @@ pub fn remove_dir>(path: P) -> io::Result<()> { /// This function does **not** follow symbolic links and it will simply remove the /// symbolic link itself. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to `opendir`, `lstat`, `rm` and `rmdir` functions on Unix /// and the `FindFirstFile`, `GetFileAttributesEx`, `DeleteFile`, and `RemoveDirectory` functions /// on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1212,12 +1212,12 @@ fn _remove_dir_all(path: &Path) -> io::Result<()> { /// The iterator will yield instances of `io::Result`. New errors may /// be encountered after an iterator is initially constructed. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `opendir` function on Unix /// and the `FindFirstFile` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1315,12 +1315,12 @@ impl Iterator for WalkDir { /// Changes the permissions found on a file or a directory. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `chmod` function on Unix /// and the `SetFileAttributes` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 8ac46bf51f1bf..b5ba6ff54c0e3 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -238,6 +238,15 @@ //! //! [result]: type.Result.html //! [try]: ../macro.try!.html +//! +//! ## Platform-specific behavior +//! +//! Many I/O functions throughout the standard library are documented to indicate +//! what various library or syscalls they are delegated to. This is done to help +//! applications both understand what's happening under the hood as well as investigate +//! any possibly unclear semantics. Note, however, that this is informative, not a binding +//! contract. The implementation of many of these functions are subject to change over +//! time and may call fewer or more syscalls/library functions. #![stable(feature = "rust1", since = "1.0.0")]