blob: 65151e0390b5061de4c56ea5539ef4c8dfdf1569 [file]
// 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/>.
*/
use std::os::unix::io::{AsFd, BorrowedFd, OwnedFd};
/// Like [`std::borrow::Cow`] but without the [`ToOwned`] requirement, and only
/// for file descriptors.
///
/// This is mainly useful when you need to write a function that takes something
/// equivalent to `Option<BorrowedFd<'_>>` and opens an alternative [`OwnedFd`]
/// (or any other `Fd: AsFd`) if passed [`None`]. Normally you cannot really do
/// this smoothly.
///
/// Note that due to Rust's temporaries handling and restrictions of the
/// [`AsFd`] trait, you need to do something like the following:
///
/// ```ignore
/// fn procfs_foobar(fd: Option<BorrowedFd<'_>>) -> Result<(), Error> {
/// let fd = match fd {
/// None => MaybeOwnedFd::OwnedFd(File::open("/proc")?),
/// Some(fd) => MaybeOwnedFd::BorrowedFd(fd),
/// };
/// let fd = fd.as_fd(); // BorrowedFd<'_>
/// // do something with fd
/// }
/// ```
///
/// This will give you a [`BorrowedFd`] with minimal fuss.
///
/// [`OwnedFd`]: std::os::unix::io::OwnedFd
/// [`ToOwned`]: std::borrow::ToOwned
#[derive(Debug)]
pub(crate) enum MaybeOwnedFd<'fd, Fd>
where
Fd: AsFd,
{
OwnedFd(Fd),
BorrowedFd(BorrowedFd<'fd>),
}
impl<'fd> From<OwnedFd> for MaybeOwnedFd<'fd, OwnedFd> {
fn from(fd: OwnedFd) -> Self {
Self::OwnedFd(fd)
}
}
impl<'fd, Fd> From<BorrowedFd<'fd>> for MaybeOwnedFd<'fd, Fd>
where
Fd: AsFd,
{
fn from(fd: BorrowedFd<'fd>) -> Self {
Self::BorrowedFd(fd)
}
}
// I wish we could make this "impl AsFd for MaybeOwnedFd" but the lifetimes
// don't match, even though it really feels like it should be possible.
impl<'fd, Fd> MaybeOwnedFd<'fd, Fd>
where
Fd: AsFd,
{
/// Unwrap `MaybeOwnedFd` into the `OwnedFd` variant if possible.
///
/// Returns `Err(self)` if this is a shared reference.
pub(crate) fn try_into_owned(self) -> Result<Fd, Self> {
match self {
Self::OwnedFd(fd) => Ok(fd),
Self::BorrowedFd(_) => Err(self),
}
}
/// Unwrap `MaybeOwnedFd` into the `OwnedFd` variant if possible.
pub(crate) fn into_owned(self) -> Option<Fd> {
self.try_into_owned().ok()
}
/// Very similar in concept to [`AsFd::as_fd`] but with some additional
/// lifetime restrictions that make it incompatible with [`AsFd`].
pub(crate) fn as_fd<'a>(&'a self) -> BorrowedFd<'a>
where
'a: 'fd,
{
match self {
Self::OwnedFd(fd) => fd.as_fd(),
Self::BorrowedFd(fd) => fd.as_fd(),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::{
fs::File,
os::unix::io::{AsFd, AsRawFd, OwnedFd},
};
use anyhow::Error;
use pretty_assertions::{assert_eq, assert_matches};
#[test]
fn as_fd() -> Result<(), Error> {
let f: OwnedFd = File::open(".")?.into();
let fd = f.as_raw_fd();
let owned: MaybeOwnedFd<OwnedFd> = f.into();
assert_matches!(owned, MaybeOwnedFd::OwnedFd(_));
assert_eq!(owned.as_fd().as_raw_fd(), fd);
assert_matches!(owned.into_owned(), Some(_));
let f = File::open(".")?;
let borrowed: MaybeOwnedFd<OwnedFd> = f.as_fd().into();
assert_matches!(borrowed, MaybeOwnedFd::BorrowedFd(_));
assert_matches!(borrowed.into_owned(), None);
Ok(())
}
#[test]
fn into_owned() -> Result<(), Error> {
let f: OwnedFd = File::open(".")?.into();
let owned: MaybeOwnedFd<OwnedFd> = f.into();
assert_matches!(
owned,
MaybeOwnedFd::OwnedFd(_),
"MaybeOwnedFd::from(OwnedFd)"
);
assert_matches!(
owned.into_owned(),
Some(_),
"MaybeOwnedFd::from(OwnedFd).into_owned()"
);
let f = File::open(".")?;
let borrowed: MaybeOwnedFd<OwnedFd> = f.as_fd().into();
assert_matches!(
borrowed,
MaybeOwnedFd::BorrowedFd(_),
"MaybeOwnedFd::from(BorrowedFd)"
);
assert_matches!(
borrowed.into_owned(),
None,
"MaybeOwnedFd::from(BorrowedFd).into_owned()"
);
Ok(())
}
#[test]
fn try_into_owned() -> Result<(), Error> {
let f: OwnedFd = File::open(".")?.into();
let owned: MaybeOwnedFd<OwnedFd> = f.into();
assert_matches!(
owned,
MaybeOwnedFd::OwnedFd(_),
"MaybeOwnedFd::from(OwnedFd)"
);
assert_matches!(
owned.try_into_owned(),
Ok(_),
"MaybeOwnedFd::from(OwnedFd).try_into_owned()"
);
let f = File::open(".")?;
let borrowed: MaybeOwnedFd<OwnedFd> = f.as_fd().into();
assert_matches!(
borrowed,
MaybeOwnedFd::BorrowedFd(_),
"MaybeOwnedFd::from(BorrowedFd)"
);
assert_matches!(
borrowed.try_into_owned(),
Err(_),
"MaybeOwnedFd::from(BorrowedFd).try_into_owned()"
);
Ok(())
}
}