diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index a3d509ba0f12d..25461db2d59aa 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -713,7 +713,7 @@ impl DirEntry { /// This function will not traverse symlinks if this entry points at a /// symlink. /// - /// # Platform behavior + /// # Platform Notes /// /// On Windows this function is cheap to call (no extra system calls /// needed), but on Unix platforms this function is the equivalent of @@ -728,7 +728,7 @@ impl DirEntry { /// This function will not traverse symlinks if this entry points at a /// symlink. /// - /// # Platform behavior + /// # Platform Notes /// /// On Windows and most Unix platforms this function is free (no extra /// system calls needed), but some Unix platforms may require the equivalent @@ -756,6 +756,18 @@ 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 Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// `DeleteFileW` +/// +/// ### Unix +/// +/// `unlink` +/// /// # Errors /// /// This function will return an error if `path` points to a directory, if the @@ -783,6 +795,24 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// This function will traverse symbolic links to query information about the /// destination file. /// +/// # Platform Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// `GetFileAttributesExW` with the `GetFileExInfoStandard` option. +/// +/// ### Unix +/// +/// `stat` +/// +/// # 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. +/// /// # Examples /// /// ```rust @@ -794,12 +824,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) @@ -807,6 +831,24 @@ pub fn metadata>(path: P) -> io::Result { /// Query the metadata about a file without following symlinks. /// +/// # Platform Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// `GetFileAttributesExW` with the `GetFileExInfoStandard` option. +/// +/// ### Unix +/// +/// 'lstat' +/// +/// # 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. +/// /// # Examples /// /// ```rust @@ -827,6 +869,18 @@ pub fn symlink_metadata>(path: P) -> io::Result { /// /// This will not work if the new name is on a different mount point. /// +/// # Platform Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// `MoveFileExW` with the `MOVEFILE_REPLACE_EXISTING` flag. +/// +/// ### Unix +/// +/// 'rename' +/// /// # Errors /// /// This function will return an error if the provided `from` doesn't exist, if @@ -859,6 +913,26 @@ pub fn rename, Q: AsRef>(from: P, to: Q) -> io::Result<()> /// /// On success, the total number of bytes copied is returned. /// +/// # Platform Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// 'CopyFileExW' with an `LPPROGRESS_ROUTINE` returning `PROGRESS_CONTINUE` until complete. +/// +/// ### Unix +/// +/// For `from`, 'open' is called with `O_RDONLY` followed by setting `O_CLOEXEC` on the returned +/// file descriptor. +/// +/// For `to`, `open` is called with `O_WRONLY`, `O_CREAT` and `O_TRUNC` followed by setting +/// `O_CLOEXEC` on the returned file descriptor. +/// +/// The copy operation is performed by calling `read` followed by `write` until complete +/// +/// Permissions are then set with `chmod`. +/// /// # Errors /// /// This function will return an error in the following situations, but is not @@ -888,6 +962,25 @@ 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 Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// 'CreateHardLinkW' +/// +/// ### Unix +/// +/// 'link' +/// +/// # 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 /// /// ``` @@ -931,11 +1024,25 @@ 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 Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// 'CreateFileW' with `FILE_FLAG_OPEN_REPARSE_POINT` and `FILE_FLAG_BACKUP_SEMANTICS` flags set. +/// +/// ### Unix +/// +/// 'readlink' +/// /// # 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 /// @@ -962,10 +1069,25 @@ pub fn canonicalize>(path: P) -> io::Result { /// Creates a new, empty directory at the provided path /// +/// # Platform Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// 'CreateDirectoryW' +/// +/// ### Unix +/// +/// 'mkdir' +/// /// # 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 /// @@ -985,9 +1107,24 @@ pub fn create_dir>(path: P) -> io::Result<()> { /// Recursively create a directory and all of its parent components if they /// are missing. /// +/// # Platform Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// 'CreateDirectoryW' +/// +/// ### Unix +/// +/// 'mkdir' +/// /// # 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`. @@ -1009,10 +1146,25 @@ pub fn create_dir_all>(path: P) -> io::Result<()> { /// Removes an existing, empty directory. /// +/// # Platform Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// 'RemoveDirectoryW' +/// +/// ### Unix +/// +/// 'rmdir' +/// /// # 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: +/// +/// * If the user lacks permissions to remove the directory at the provided `path` +/// * If the directory isn't empty /// /// # Examples /// @@ -1035,6 +1187,21 @@ 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 Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// 'FindFirstFileW' followed by `GetFileAttributesExW` with the +/// `GetFileExInfoStandard` option. All files are removed with `DeleteFileW` +/// and all directories removed with `RemoveDirectoryW`. +/// +/// ### Unix +/// +/// `opendir` followed by `lstat`. All files are then removed with `rmdir` and +/// directories removed with `rmdir` +/// /// # Errors /// /// See `file::remove_file` and `fs::remove_dir`. @@ -1072,6 +1239,27 @@ 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 Notes +/// +/// Depending on platform, this function will invoke the following syscalls: +/// +/// ### Windows +/// +/// `FindFirstFileW` +/// +/// ### Unix +/// +/// `opendir` +/// +/// # 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 /// /// ``` @@ -1094,12 +1282,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)