blob: 14e95b4e5db1e0cab407839696ffc49597a67d55 [file] [edit]
// 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(())
}
}