1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
|
[][crate]
[][docs]
[][ci]
# faccess
Basic cross-platform file accessibility checks for Rust.
## Synopsis
```rust
pub trait PathExt {
fn access(&self, mode: AccessMode) -> std::io::Result<()>;
fn readable(&self) -> bool;
fn writable(&self) -> bool;
fn executable(&self) -> bool;
}
impl PathExt for std::path::Path;
```
## Description
`faccess` provides an extension trait for `std::path::Path` which adds an
`access` method for checking the accessibility of a path for the given access
permissions — a bitwise-inclusive OR of one or more `AccessMode` flags
(`EXISTS`, `READ`, `WRITE`, `EXECUTE`).
It also provides convenience methods `readable`, `writable`, and `executable`
if only a single permission needs to be checked in a simple boolean fashion.
## Example
```rust
use std::path::Path;
use faccess::{AccessMode, PathExt};
let path = Path::new("/bin/ls");
assert!(path.access(AccessMode::READ | AccessMode::EXECUTE).is_ok());
assert!(path.readable());
assert!(!path.writable());
assert!(path.executable());
```
## Platform-specific Behaviour
On Unix platforms, `access` directly maps to [`faccessat(2)`], with the
`AT_EACCESS` flag used where available to test against the effective user and
group ID's.
On Windows, a complex custom implementation is used to approximate these
semantics in a best-effort fashion, using a mixture of file extension checks,
simply attempting to open a file, [`GetNamedSecurityInfoW`], and [`AccessCheck`],
depending on the permissions being checked. This is similar to implementations
found in other languages.
On other platforms it simply proxies to `exists()` and `readonly()` as appropriate.
## Caveats
There is a history of time-of-check to time-of-use ([TOCTOU]) bugs with this
class of function, particularly with set-user-ID programs relying on them to
validate effective user/group permissions prior to accessing files on behalf
of other users. They should not be relied upon in a security context.
[`faccessat(2)`]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/access.html
[`GetNamedSecurityInfoW`]: https://docs.microsoft.com/en-us/windows/win32/api/aclapi/nf-aclapi-getnamedsecurityinfow
[`AccessCheck`]: https://docs.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-accesscheck
[TOCTOU]: https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use
[crate]: https://crates.io/crates/faccess
[docs]: https://docs.rs/faccess
[ci]: https://github.com/Freaky/faccess/actions?query=workflow%3Abuild
|