| // 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)] | |
| use crate::{ | |
| error::{Error, ErrorImpl}, | |
| flags::OpenFlags, | |
| procfs::ProcfsHandle, | |
| utils::FdExt, | |
| }; | |
| use std::{ | |
| fs::File, | |
| os::unix::io::{AsFd, BorrowedFd, OwnedFd}, | |
| }; | |
| /// A handle to an existing inode within a [`Root`]. | |
| /// | |
| /// This handle references an already-resolved path which can be used for the | |
| /// purpose of "re-opening" the handle and get an actual [`File`] which can be | |
| /// used for ordinary operations. | |
| /// | |
| /// # Safety | |
| /// | |
| /// It is critical for the safety of this library that **at no point** do you | |
| /// use interfaces like [`libc::openat`] directly on the [`OwnedFd`] you can | |
| /// extract from this [`Handle`]. **You must always do operations through a | |
| /// valid [`Root`].** | |
| /// | |
| /// [`RawFd`]: std::os::unix::io::RawFd | |
| /// [`Root`]: crate::Root | |
| #[derive(Debug)] | |
| pub struct Handle { | |
| inner: OwnedFd, | |
| } | |
| impl Handle { | |
| /// Wrap an [`OwnedFd`] into a [`Handle`]. | |
| #[inline] | |
| pub fn from_fd(fd: impl Into<OwnedFd>) -> Self { | |
| Self { inner: fd.into() } | |
| } | |
| /// Borrow this [`Handle`] as a [`HandleRef`]. | |
| // XXX: We can't use Borrow/Deref for this because HandleRef takes a | |
| // lifetime rather than being a pure reference. Ideally we would use | |
| // Deref but it seems that won't be possible in standard Rust for a | |
| // long time, if ever... | |
| #[inline] | |
| pub fn as_ref(&self) -> HandleRef<'_> { | |
| HandleRef { | |
| inner: self.as_fd(), | |
| } | |
| } | |
| /// Create a copy of an existing [`Handle`]. | |
| /// | |
| /// The new handle is completely independent from the original, but | |
| /// references the same underlying file. | |
| #[inline] | |
| pub fn try_clone(&self) -> Result<Self, Error> { | |
| self.as_ref().try_clone() | |
| } | |
| /// "Upgrade" the handle to a usable [`File`] handle. | |
| /// | |
| /// This new [`File`] handle is suitable for reading and writing. This does | |
| /// not consume the original handle (allowing for it to be used many times). | |
| /// | |
| /// The [`File`] handle will be opened with `O_NOCTTY` and `O_CLOEXEC` set, | |
| /// regardless of whether those flags are present in the `flags` argument. | |
| /// You can correct these yourself if these defaults are not ideal for you: | |
| /// | |
| /// 1. `fcntl(fd, F_SETFD, 0)` will let you unset `O_CLOEXEC`. | |
| /// 2. `ioctl(fd, TIOCSCTTY, 0)` will set the fd as the controlling terminal | |
| /// (if you don't have one already, and the fd references a TTY). | |
| /// | |
| /// [`Root::create`]: crate::Root::create | |
| #[doc(alias = "pathrs_reopen")] | |
| #[inline] | |
| pub fn reopen(&self, flags: impl Into<OpenFlags>) -> Result<File, Error> { | |
| self.as_ref().reopen(flags) | |
| } | |
| } | |
| impl From<OwnedFd> for Handle { | |
| /// Shorthand for [`Handle::from_fd`]. | |
| fn from(fd: OwnedFd) -> Self { | |
| Self::from_fd(fd) | |
| } | |
| } | |
| impl From<Handle> for OwnedFd { | |
| /// Unwrap a [`Handle`] to reveal the underlying [`OwnedFd`]. | |
| /// | |
| /// **Note**: This method is primarily intended to allow for file descriptor | |
| /// passing or otherwise transmitting file descriptor information. If you | |
| /// want to get a [`File`] handle for general use, please use | |
| /// [`Handle::reopen`] instead. | |
| #[inline] | |
| fn from(handle: Handle) -> Self { | |
| handle.inner | |
| } | |
| } | |
| impl AsFd for Handle { | |
| /// Access the underlying file descriptor for a [`Handle`]. | |
| /// | |
| /// **Note**: This method is primarily intended to allow for tests and other | |
| /// code to check the status of the underlying [`OwnedFd`] without having to | |
| /// use [`OwnedFd::from`]. It is not safe to use this [`BorrowedFd`] | |
| /// directly to do filesystem operations. Please use the provided | |
| /// [`HandleRef`] methods. | |
| #[inline] | |
| fn as_fd(&self) -> BorrowedFd<'_> { | |
| self.inner.as_fd() | |
| } | |
| } | |
| /// Borrowed version of [`Handle`]. | |
| /// | |
| /// Unlike [`Handle`], when [`HandleRef`] is dropped the underlying file | |
| /// descriptor is *not* closed. This is mainly useful for programs and libraries | |
| /// that have to do operations on [`&File`][File]s and [`BorrowedFd`]s passed | |
| /// from elsewhere. | |
| /// | |
| /// [File]: std::fs::File | |
| // TODO: Is there any way we can restructure this to use Deref so that we don't | |
| // need to copy all of the methods into Handle? Probably not... Maybe GATs | |
| // will eventually support this but we'd still need a GAT-friendly Deref. | |
| #[derive(Copy, Clone, Debug)] | |
| pub struct HandleRef<'fd> { | |
| inner: BorrowedFd<'fd>, | |
| } | |
| impl HandleRef<'_> { | |
| /// Wrap a [`BorrowedFd`] into a [`HandleRef`]. | |
| pub fn from_fd(inner: BorrowedFd<'_>) -> HandleRef<'_> { | |
| HandleRef { inner } | |
| } | |
| /// Create a copy of a [`HandleRef`]. | |
| /// | |
| /// Note that (unlike [`BorrowedFd::clone`]) this method creates a full copy | |
| /// of the underlying file descriptor and thus is more equivalent to | |
| /// [`BorrowedFd::try_clone_to_owned`]. | |
| /// | |
| /// To create a shallow copy of a [`HandleRef`], you can use | |
| /// [`Clone::clone`] (or just [`Copy`]). | |
| // TODO: We might need to call this something other than try_clone(), since | |
| // it's a little too easy to confuse with Clone::clone() but we also | |
| // really want to have Copy. | |
| pub fn try_clone(&self) -> Result<Handle, Error> { | |
| self.as_fd() | |
| .try_clone_to_owned() | |
| .map_err(|err| { | |
| ErrorImpl::OsError { | |
| operation: "clone underlying handle file".into(), | |
| source: err, | |
| } | |
| .into() | |
| }) | |
| .map(Handle::from_fd) | |
| } | |
| /// "Upgrade" the handle to a usable [`File`] handle. | |
| /// | |
| /// This new [`File`] handle is suitable for reading and writing. This does | |
| /// not consume the original handle (allowing for it to be used many times). | |
| /// | |
| /// The [`File`] handle will be opened with `O_NOCTTY` and `O_CLOEXEC` set, | |
| /// regardless of whether those flags are present in the `flags` argument. | |
| /// You can correct these yourself if these defaults are not ideal for you: | |
| /// | |
| /// 1. `fcntl(fd, F_SETFD, 0)` will let you unset `O_CLOEXEC`. | |
| /// 2. `ioctl(fd, TIOCSCTTY, 0)` will set the fd as the controlling terminal | |
| /// (if you don't have one already, and the fd references a TTY). | |
| /// | |
| /// [`Root::create`]: crate::Root::create | |
| #[doc(alias = "pathrs_reopen")] | |
| pub fn reopen(&self, flags: impl Into<OpenFlags>) -> Result<File, Error> { | |
| self.inner | |
| .reopen(&ProcfsHandle::new()?, flags.into()) | |
| .map(File::from) | |
| } | |
| // TODO: All the different stat* interfaces? | |
| // TODO: bind(). This might be safe to do (set the socket path to | |
| // /proc/self/fd/...) but I'm a bit sad it'd be separate from | |
| // Handle::reopen(). | |
| } | |
| impl<'fd> From<BorrowedFd<'fd>> for HandleRef<'fd> { | |
| /// Shorthand for [`HandleRef::from_fd`]. | |
| fn from(fd: BorrowedFd<'fd>) -> Self { | |
| Self::from_fd(fd) | |
| } | |
| } | |
| impl AsFd for HandleRef<'_> { | |
| /// Access the underlying file descriptor for a [`HandleRef`]. | |
| /// | |
| /// **Note**: This method is primarily intended to allow for tests and other | |
| /// code to check the status of the underlying file descriptor. It is not | |
| /// safe to use this [`BorrowedFd`] directly to do filesystem operations. | |
| /// Please use the provided [`HandleRef`] methods. | |
| #[inline] | |
| fn as_fd(&self) -> BorrowedFd<'_> { | |
| self.inner.as_fd() | |
| } | |
| } | |
| #[cfg(test)] | |
| mod tests { | |
| use crate::{Handle, HandleRef, Root}; | |
| use std::os::unix::io::{AsFd, AsRawFd, BorrowedFd, OwnedFd}; | |
| use anyhow::Error; | |
| use pretty_assertions::assert_eq; | |
| #[test] | |
| fn from_fd() -> Result<(), Error> { | |
| let handle = Root::open(".")?.resolve(".")?; | |
| let handle_ref1 = handle.as_ref(); | |
| let handle_ref2 = HandleRef::from_fd(handle.as_fd()); | |
| assert_eq!( | |
| handle.as_fd().as_raw_fd(), | |
| handle_ref1.as_fd().as_raw_fd(), | |
| "Handle::as_ref should have the same underlying fd" | |
| ); | |
| assert_eq!( | |
| handle.as_fd().as_raw_fd(), | |
| handle_ref2.as_fd().as_raw_fd(), | |
| "HandleRef::from_fd should have the same underlying fd" | |
| ); | |
| Ok(()) | |
| } | |
| #[test] | |
| fn into_from_ownedfd() -> Result<(), Error> { | |
| let handle = Root::open(".")?.resolve(".")?; | |
| let handle_fd = handle.as_fd().as_raw_fd(); | |
| let owned: OwnedFd = handle.into(); | |
| let owned_fd = owned.as_fd().as_raw_fd(); | |
| let handle2: Handle = owned.into(); | |
| let handle2_fd = handle2.as_fd().as_raw_fd(); | |
| assert_eq!( | |
| handle_fd, owned_fd, | |
| "OwnedFd::from(handle) should have same underlying fd", | |
| ); | |
| assert_eq!( | |
| handle_fd, handle2_fd, | |
| "Handle -> OwnedFd -> Handle roundtrip should have same underlying fd", | |
| ); | |
| Ok(()) | |
| } | |
| #[test] | |
| fn from_borrowedfd() -> Result<(), Error> { | |
| let handle = Root::open(".")?.resolve(".")?; | |
| let borrowed_fd: BorrowedFd<'_> = handle.as_fd(); | |
| let handle_ref: HandleRef<'_> = borrowed_fd.into(); | |
| assert_eq!( | |
| handle.as_fd().as_raw_fd(), | |
| borrowed_fd.as_fd().as_raw_fd(), | |
| "BorrowedFd::from(HandleRef) should have the same underlying fd" | |
| ); | |
| assert_eq!( | |
| handle.as_fd().as_raw_fd(), | |
| handle_ref.as_fd().as_raw_fd(), | |
| "HandleRef::from(BorrowedFd) should have the same underlying fd" | |
| ); | |
| Ok(()) | |
| } | |
| } |