| // SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later | |
| /* | |
| * libpathrs: safe path resolution on Linux | |
| * Copyright (C) 2019-2025 SUSE LLC | |
| * Copyright (C) 2026 Aleksa Sarai <cyphar@cyphar.com> | |
| * | |
| * == MPL-2.0 == | |
| * | |
| * This Source Code Form is subject to the terms of the Mozilla Public | |
| * License, v. 2.0. If a copy of the MPL was not distributed with this | |
| * file, You can obtain one at https://mozilla.org/MPL/2.0/. | |
| * | |
| * Alternatively, this Source Code Form may also (at your option) be used | |
| * under the terms of the GNU Lesser General Public License Version 3, as | |
| * described below: | |
| * | |
| * == LGPL-3.0-or-later == | |
| * | |
| * This program is free software: you can redistribute it and/or modify it | |
| * under the terms of the GNU Lesser General Public License as published by | |
| * the Free Software Foundation, either version 3 of the License, or (at | |
| * your option) any later version. | |
| * | |
| * This program is distributed in the hope that it will be useful, but | |
| * WITHOUT ANY WARRANTY; without even the implied warranty of | |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General | |
| * Public License for more details. | |
| * | |
| * You should have received a copy of the GNU Lesser General Public License | |
| * along with this program. If not, see <https://www.gnu.org/licenses/>. | |
| */ | |
| #![forbid(unsafe_code)] | |
| //! Bit-flags for modifying the behaviour of libpathrs. | |
| use crate::syscalls; | |
| use bitflags::bitflags; | |
| use rustix::fs as rustix_fs; | |
| bitflags! { | |
| /// Wrapper for the underlying `libc`'s `O_*` flags. | |
| /// | |
| /// The flag values and their meaning is identical to the description in the | |
| /// `open(2)` man page. | |
| /// | |
| /// # Caveats | |
| /// | |
| /// For historical reasons, the first three bits of `open(2)`'s flags are | |
| /// for the access mode and are actually treated as a 2-bit number. So, it | |
| /// is incorrect to attempt to do any checks on the access mode without | |
| /// masking it correctly. So some helpers were added to make usage more | |
| /// ergonomic. | |
| /// | |
| /// ``` | |
| /// # use pathrs::flags::OpenFlags; | |
| /// // Using .contains() can lead to confusing behaviour: | |
| /// # let ret = | |
| /// OpenFlags::O_WRONLY.contains(OpenFlags::O_RDONLY); // returns true! | |
| /// # assert!(ret); | |
| /// # let ret = | |
| /// OpenFlags::O_RDWR.contains(OpenFlags::O_RDONLY); // returns true! | |
| /// # assert!(ret); | |
| /// # let ret = | |
| /// OpenFlags::O_RDWR.contains(OpenFlags::O_WRONLY); // returns false! | |
| /// # assert!(!ret); | |
| /// // But using the .wants_write() and .wants_read() helpers works: | |
| /// assert_eq!(OpenFlags::O_WRONLY.wants_read(), false); | |
| /// # #[allow(clippy::bool_assert_comparison)] | |
| /// assert_eq!(OpenFlags::O_RDONLY.wants_read(), true); | |
| /// # #[allow(clippy::bool_assert_comparison)] | |
| /// assert_eq!(OpenFlags::O_RDWR.wants_write(), true); | |
| /// // And we also correctly handle O_PATH as being "neither read nor write". | |
| /// assert_eq!((OpenFlags::O_PATH | OpenFlags::O_RDWR).access_mode(), None); | |
| /// assert_eq!((OpenFlags::O_PATH | OpenFlags::O_RDWR).wants_read(), false); | |
| /// assert_eq!((OpenFlags::O_PATH | OpenFlags::O_RDWR).wants_write(), false); | |
| /// // As well as the sneaky "implied write" cases. | |
| /// assert_eq!((OpenFlags::O_CREAT|OpenFlags::O_RDONLY).wants_write(), true); | |
| /// assert_eq!((OpenFlags::O_TRUNC|OpenFlags::O_RDONLY).wants_write(), true); | |
| /// ``` | |
| /// | |
| /// Also, if you wish to check for `O_TMPFILE`, make sure to use `contains`. | |
| /// `O_TMPFILE` includes `O_DIRECTORY`, so doing `intersection` will match | |
| /// `O_DIRECTORY` as well. | |
| /// | |
| /// ``` | |
| /// # use pathrs::flags::OpenFlags; | |
| /// // O_TMPFILE contains O_DIRECTORY (as a kernel implementation detail). | |
| /// # let ret = | |
| /// OpenFlags::O_DIRECTORY.intersection(OpenFlags::O_TMPFILE).is_empty(); // returns false! | |
| /// # assert!(!ret); | |
| /// // Instead, use contains: | |
| /// assert_eq!(OpenFlags::O_DIRECTORY.contains(OpenFlags::O_TMPFILE), false); | |
| /// ``` | |
| #[derive(Default, PartialEq, Eq, Debug, Clone, Copy)] | |
| pub struct OpenFlags: u64 { | |
| // Access modes (including O_PATH). | |
| const O_RDWR = libc::O_RDWR as _; | |
| const O_RDONLY = libc::O_RDONLY as _; | |
| const O_WRONLY = libc::O_WRONLY as _; | |
| const O_PATH = libc::O_PATH as _; | |
| // Fd flags. | |
| const O_CLOEXEC = libc::O_CLOEXEC as _; | |
| // Control lookups. | |
| const O_NOFOLLOW = libc::O_NOFOLLOW as _; | |
| const O_DIRECTORY = libc::O_DIRECTORY as _; | |
| const O_NOCTTY = libc::O_NOCTTY as _; | |
| // NOTE: This flag contains O_DIRECTORY! | |
| const O_TMPFILE = libc::O_TMPFILE as _; | |
| // File creation. | |
| const O_CREAT = libc::O_CREAT as _; | |
| const O_EXCL = libc::O_EXCL as _; | |
| const O_TRUNC = libc::O_TRUNC as _; | |
| const O_APPEND = libc::O_APPEND as _; | |
| // Sync. | |
| const O_SYNC = libc::O_SYNC as _; | |
| const O_ASYNC = libc::O_ASYNC as _; | |
| const O_DSYNC = libc::O_DSYNC as _; | |
| #[cfg(not(target_env = "musl"))] // musl doesn't provide FSYNC | |
| const O_FSYNC = libc::O_FSYNC as _; | |
| const O_RSYNC = libc::O_RSYNC as _; | |
| const O_DIRECT = libc::O_DIRECT as _; | |
| const O_NDELAY = libc::O_NDELAY as _; | |
| const O_NOATIME = libc::O_NOATIME as _; | |
| const O_NONBLOCK = libc::O_NONBLOCK as _; | |
| // NOTE: This is effectively a kernel-internal flag (auto-set on systems | |
| // with large offset support). glibc defines it as 0, and it is | |
| // also architecture-specific. | |
| //const O_LARGEFILE = libc::O_LARGEFILE as _; | |
| // Don't clobber unknown O_* bits. | |
| const _ = !0; | |
| } | |
| } | |
| /// Convert an [`OpenFlags`] set of flags to the [`openat`]-compatible | |
| /// [`OFlags`]. If the value cannot be converted then `Err(())` is returned. | |
| /// | |
| /// [`OFlags`]: rustix::fs::OFlags | |
| // TODO: It might even make sense to make this do an explicit check for O_* | |
| // flags versus openat2(2)-only flags if we end up having any in the lower | |
| // bits... | |
| #[doc(hidden)] | |
| impl TryFrom<OpenFlags> for rustix_fs::OFlags { | |
| // No need for an actual error type, if this fails the meaning is obvious. | |
| type Error = (); | |
| fn try_from(flags: OpenFlags) -> Result<Self, Self::Error> { | |
| flags | |
| .bits() | |
| .try_into() | |
| .map(Self::from_bits_retain) | |
| .map_err(|_| ()) | |
| } | |
| } | |
| impl OpenFlags { | |
| /// Grab the access mode bits from the flags. | |
| /// | |
| /// If the flags contain `O_PATH`, this returns `None`. | |
| #[inline] | |
| pub fn access_mode(self) -> Option<libc::c_int> { | |
| if self.contains(OpenFlags::O_PATH) { | |
| None | |
| } else { | |
| let acc_mode = self.bits() & (libc::O_ACCMODE as u64); | |
| debug_assert!( | |
| acc_mode <= 0b11, | |
| "{:X} masked by O_ACCMODE ({:X}) mask should only set bottom two bits", | |
| self.bits(), | |
| libc::O_ACCMODE, | |
| ); | |
| Some(acc_mode as _) | |
| } | |
| } | |
| /// Does the access mode imply read access? | |
| /// | |
| /// Returns false for `O_PATH`. | |
| #[inline] | |
| pub fn wants_read(self) -> bool { | |
| match self.access_mode() { | |
| None => false, // O_PATH | |
| Some(acc) => acc == libc::O_RDONLY || acc == libc::O_RDWR, | |
| } | |
| } | |
| /// Does the access mode imply write access? Note that there are several | |
| /// other bits in OpenFlags that imply write access other than `O_WRONLY` | |
| /// and `O_RDWR`. This function checks those bits as well. | |
| /// | |
| /// Returns false for `O_PATH`. | |
| #[inline] | |
| pub fn wants_write(self) -> bool { | |
| match self.access_mode() { | |
| None => false, // O_PATH | |
| Some(acc) => { | |
| acc == libc::O_WRONLY | |
| || acc == libc::O_RDWR | |
| // O_CREAT and O_TRUNC are silently ignored with O_PATH. | |
| || self.intersects(OpenFlags::O_TRUNC | OpenFlags::O_CREAT) | |
| } | |
| } | |
| } | |
| } | |
| bitflags! { | |
| /// Wrapper for the underlying `libc`'s `RENAME_*` flags. | |
| /// | |
| /// The flag values and their meaning is identical to the description in the | |
| /// [`renameat2(2)`] man page. | |
| /// | |
| /// [`renameat2(2)`] might not not be supported on your kernel -- in which | |
| /// case [`Root::rename`] will fail if you specify any RenameFlags. You can | |
| /// verify whether [`renameat2(2)`] flags are supported by calling | |
| /// [`RenameFlags::supported`]. | |
| /// | |
| /// [`renameat2(2)`]: http://man7.org/linux/man-pages/man2/rename.2.html | |
| /// [`Root::rename`]: crate::Root::rename | |
| #[derive(Default, PartialEq, Eq, Debug, Clone, Copy)] | |
| pub struct RenameFlags: u64 { | |
| const RENAME_EXCHANGE = libc::RENAME_EXCHANGE as _; | |
| const RENAME_NOREPLACE = libc::RENAME_NOREPLACE as _; | |
| const RENAME_WHITEOUT = libc::RENAME_WHITEOUT as _; | |
| // Don't clobber unknown RENAME_* bits. | |
| const _ = !0; | |
| } | |
| } | |
| impl From<RenameFlags> for rustix::fs::RenameFlags { | |
| fn from(flags: RenameFlags) -> Self { | |
| debug_assert!( | |
| flags.bits() < (1u64 << 32), | |
| "RenameFlags cannot contain anything in the top 32 bits." | |
| ); | |
| Self::from_bits_retain(flags.bits() as _) | |
| } | |
| } | |
| impl RenameFlags { | |
| /// Is this set of RenameFlags supported by the running kernel? | |
| pub fn is_supported(self) -> bool { | |
| // TODO: This check won't work once new RENAME_* flags are added. | |
| self.is_empty() || *syscalls::RENAME_FLAGS_SUPPORTED | |
| } | |
| } | |
| #[cfg(test)] | |
| mod tests { | |
| use crate::{ | |
| flags::{OpenFlags, RenameFlags}, | |
| syscalls, | |
| }; | |
| macro_rules! openflags_tests { | |
| ($($test_name:ident ( $($flag:ident)|+ ) == {accmode: $accmode:expr, read: $wants_read:expr, write: $wants_write:expr} );+ $(;)?) => { | |
| $( | |
| paste::paste! { | |
| #[test] | |
| fn [<openflags_ $test_name _access_mode>]() { | |
| let flags = $(OpenFlags::$flag)|*; | |
| let accmode: Option<i32> = $accmode; | |
| assert_eq!(flags.access_mode(), accmode, "{flags:?} access mode should be {:?}", accmode.map(|flags| OpenFlags::from_bits_retain(flags as _))); | |
| } | |
| #[test] | |
| fn [<openflags_ $test_name _wants_read>]() { | |
| let flags = $(OpenFlags::$flag)|*; | |
| assert_eq!(flags.wants_read(), $wants_read, "{flags:?} wants_read should be {:?}", $wants_read); | |
| } | |
| #[test] | |
| fn [<openflags_ $test_name _wants_write>]() { | |
| let flags = $(OpenFlags::$flag)|*; | |
| assert_eq!(flags.wants_write(), $wants_write, "{flags:?} wants_write should be {:?}", $wants_write); | |
| } | |
| } | |
| )* | |
| } | |
| } | |
| openflags_tests! { | |
| plain_rdonly(O_RDONLY) == {accmode: Some(libc::O_RDONLY), read: true, write: false}; | |
| plain_wronly(O_WRONLY) == {accmode: Some(libc::O_WRONLY), read: false, write: true}; | |
| plain_rdwr(O_RDWR) == {accmode: Some(libc::O_RDWR), read: true, write: true}; | |
| plain_opath(O_PATH) == {accmode: None, read: false, write: false}; | |
| rdwr_opath(O_RDWR|O_PATH) == {accmode: None, read: false, write: false}; | |
| wronly_opath(O_WRONLY|O_PATH) == {accmode: None, read: false, write: false}; | |
| trunc_rdonly(O_RDONLY|O_TRUNC) == {accmode: Some(libc::O_RDONLY), read: true, write: true}; | |
| trunc_wronly(O_WRONLY|O_TRUNC) == {accmode: Some(libc::O_WRONLY), read: false, write: true}; | |
| trunc_rdwr(O_RDWR|O_TRUNC) == {accmode: Some(libc::O_RDWR), read: true, write: true}; | |
| trunc_path(O_PATH|O_TRUNC) == {accmode: None, read: false, write: false}; | |
| creat_rdonly(O_RDONLY|O_CREAT) == {accmode: Some(libc::O_RDONLY), read: true, write: true}; | |
| creat_wronly(O_WRONLY|O_CREAT) == {accmode: Some(libc::O_WRONLY), read: false, write: true}; | |
| creat_rdwr(O_RDWR|O_CREAT) == {accmode: Some(libc::O_RDWR), read: true, write: true}; | |
| creat_path(O_PATH|O_CREAT) == {accmode: None, read: false, write: false}; | |
| } | |
| #[test] | |
| fn rename_flags_is_supported() { | |
| assert!( | |
| RenameFlags::empty().is_supported(), | |
| "empty flags should be supported" | |
| ); | |
| assert_eq!( | |
| RenameFlags::RENAME_EXCHANGE.is_supported(), | |
| *syscalls::RENAME_FLAGS_SUPPORTED, | |
| "rename flags being supported should be identical to RENAME_FLAGS_SUPPORTED" | |
| ); | |
| } | |
| } | |
| bitflags! { | |
| /// Optional flags to modify the resolution of paths inside a [`Root`]. | |
| /// | |
| /// [`Root`]: crate::Root | |
| #[derive(Default, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)] | |
| pub struct ResolverFlags: u64 { | |
| // TODO: We should probably have our own bits... | |
| const NO_SYMLINKS = libc::RESOLVE_NO_SYMLINKS; | |
| } | |
| } |