Changes the permissions found on a file or a directory. On certain platforms, if the file is a symlink, it will change the permissions bits on the symlink itself rather than the target (e.g. Windows, BSD, MacOS). On other platforms, this results in an error when attempting to change permissions on a symlink (e.g. Linux).

Note that non-final path elements are allowed to be symlinks.

Platform-specific behavior

This function currently corresponds to the following underlying operations:

• Android: returns Unsupported on all files.
• Linux, BSD-based platforms, QNX, NTO: fchmodat with AT_SYMLINK_NOFOLLOW. If that is not supported, we fall back to:
  • Unix-based platforms with symlinks: open with O_NOFOLLOW followed by fs::set_permissions.
  • Unix-based platforms without symlinks: open followed by fs::set_permissions.
• Windows: CreateFileW with FILE_FLAG_OPEN_REPARSE_POINT followed by SetFileInformationByHandle.

Note that, this may change in the future.

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.

Note: On Linux and other Unix-based platforms with symlinks (non-BSD-based), this will result in an Unsupported error if the final element is a symlink.

Examples

#![feature(set_permissions_nofollow)]
use std::fs;

fn main() -> std::io::Result<()> {
    let mut perms = fs::symlink_metadata("foo.txt")?.permissions();
    perms.set_readonly(true);
    // This should result in an error on certain platforms or
    // succeed in modifying the permissions of a symlink
    fs::set_permissions_nofollow("foo.txt", perms)?;
    Ok(())
}