blob: d6b2d448e927ea6f0d40534c0c8c72f45de7c113 [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/>.
*/
use crate::{
capi::{
ret::IntoCReturn,
utils::{self, CBorrowedFd},
},
error::{Error, ErrorExt, ErrorImpl},
flags::OpenFlags,
procfs::{ProcfsBase, ProcfsHandle, ProcfsHandleBuilder, ProcfsHandleRef},
};
use std::os::unix::io::{AsRawFd, IntoRawFd, OwnedFd, RawFd};
use bitflags::bitflags;
use bytemuck::{Pod, Zeroable};
use libc::{c_char, c_int, size_t};
use open_enum::open_enum;
/// Bits in `pathrs_proc_base_t` that indicate the type of the base value.
///
/// NOTE: This is used internally by libpathrs. You should avoid using this
/// macro if possible.
pub const __PATHRS_PROC_TYPE_MASK: u64 = 0xFFFF_FFFF_0000_0000;
/// Bits in `pathrs_proc_base_t` that must be set for "special" `PATHRS_PROC_*`
/// values.
const __PATHRS_PROC_TYPE_SPECIAL: u64 = 0xFFFF_FFFE_0000_0000;
// Make sure that __PATHRS_PROC_TYPE_SPECIAL only uses bits in the mask.
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_SPECIAL,
__PATHRS_PROC_TYPE_SPECIAL & __PATHRS_PROC_TYPE_MASK,
);
/// Bits in `pathrs_proc_base_t` that must be set for `/proc/$pid` values. Don't
/// use this directly, instead use `PATHRS_PROC_PID(n)` to convert a PID to an
/// appropriate `pathrs_proc_base_t` value.
///
/// NOTE: This is used internally by libpathrs. You should avoid using this
/// macro if possible.
// For future-proofing the top 32 bits are blocked off by the mask, but in case
// we ever need to expand the size of pid_t (incredibly unlikely) we only use
// the top-most bit.
pub const __PATHRS_PROC_TYPE_PID: u64 = 0x8000_0000_0000_0000;
// Make sure that __PATHRS_PROC_TYPE_PID only uses bits in the mask.
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_PID,
__PATHRS_PROC_TYPE_PID & __PATHRS_PROC_TYPE_MASK,
);
/// Indicate what base directory should be used when doing operations with
/// `pathrs_proc_*`. In addition to the values defined here, the following
/// macros can be used for other values:
///
/// * `PATHRS_PROC_PID(pid)` refers to the `/proc/<pid>` directory for the
/// process with PID (or TID) `pid`.
///
/// Note that this operation is inherently racy and should probably avoided
/// for most uses -- see the block comment above `PATHRS_PROC_PID(n)` for
/// more details.
///
/// Unknown values will result in an error being returned.
// NOTE: We need to open-code the values in the definition because cbindgen
// cannot yet evaluate constexprs (see <>) and both Go's CGo and Python's cffi
// struggle to deal with non-constant values (actually CGo struggles even with
// unsigned literals -- see <https://github.com/golang/go/issues/39136>).
#[open_enum]
#[repr(u64)]
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
#[allow(non_camel_case_types, dead_code)]
#[allow(clippy::unusual_byte_groupings)] // FIXME: workaround for <https://github.com/rust-lang/rust-clippy/issues/15210>
pub enum CProcfsBase {
/// Use /proc. Note that this mode may be more expensive because we have
/// to take steps to try to avoid leaking unmasked procfs handles, so you
/// should use PATHRS_PROC_SELF if you can.
PATHRS_PROC_ROOT = 0xFFFF_FFFE_7072_6F63u64, // "proc"
/// Use /proc/self. For most programs, this is the standard choice.
PATHRS_PROC_SELF = 0xFFFF_FFFE_091D_5E1Fu64, // pid-self
/// Use /proc/thread-self. In multi-threaded programs where one thread has a
/// different CLONE_FS, it is possible for /proc/self to point the wrong
/// thread and so /proc/thread-self may be necessary.
///
/// NOTE: Using /proc/thread-self may require care if used from languages
/// where your code can change threads without warning and old threads can
/// be killed (such as Go -- where you want to use runtime.LockOSThread).
PATHRS_PROC_THREAD_SELF = 0xFFFF_FFFE_3EAD_5E1Fu64, // thread-self
}
// Make sure the defined special values have the right type flag and the right
// values. The value checks are critical because we must not change these --
// changing them will break API compatibility silently.
static_assertions::const_assert_eq!(0xFFFFFFFE70726F63, CProcfsBase::PATHRS_PROC_ROOT.0);
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_SPECIAL | 0x7072_6F63,
CProcfsBase::PATHRS_PROC_ROOT.0,
);
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_SPECIAL,
CProcfsBase::PATHRS_PROC_ROOT.0 & __PATHRS_PROC_TYPE_MASK,
);
static_assertions::const_assert_eq!(0xFFFFFFFE091D5E1F, CProcfsBase::PATHRS_PROC_SELF.0);
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_SPECIAL | 0x091D_5E1F,
CProcfsBase::PATHRS_PROC_SELF.0,
);
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_SPECIAL,
CProcfsBase::PATHRS_PROC_SELF.0 & __PATHRS_PROC_TYPE_MASK,
);
static_assertions::const_assert_eq!(0xFFFFFFFE3EAD5E1F, CProcfsBase::PATHRS_PROC_THREAD_SELF.0);
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_SPECIAL | 0x3EAD_5E1F,
CProcfsBase::PATHRS_PROC_THREAD_SELF.0,
);
static_assertions::const_assert_eq!(
__PATHRS_PROC_TYPE_SPECIAL,
CProcfsBase::PATHRS_PROC_THREAD_SELF.0 & __PATHRS_PROC_TYPE_MASK,
);
impl TryFrom<CProcfsBase> for ProcfsBase {
type Error = Error;
fn try_from(c_base: CProcfsBase) -> Result<Self, Self::Error> {
// Cannot be used inline in a pattern.
const U32_MAX: u64 = u32::MAX as _;
const U32_MAX_PLUS_ONE: u64 = U32_MAX + 1;
match c_base {
CProcfsBase::PATHRS_PROC_ROOT => Ok(ProcfsBase::ProcRoot),
CProcfsBase::PATHRS_PROC_SELF => Ok(ProcfsBase::ProcSelf),
CProcfsBase::PATHRS_PROC_THREAD_SELF => Ok(ProcfsBase::ProcThreadSelf),
CProcfsBase(arg) => match (
arg & __PATHRS_PROC_TYPE_MASK,
arg & !__PATHRS_PROC_TYPE_MASK,
) {
// Make sure that we never run into a situation where the
// argument value doesn't fit in a u32. If we ever need to
// support this, we will need additional code changes.
(_, value @ U32_MAX_PLUS_ONE..) => {
// This should really never actually happen, so ensure we
// have a compile-time check to avoid it.
static_assertions::const_assert_eq!(!__PATHRS_PROC_TYPE_MASK, u32::MAX as _);
// And mark this branch as unreachable.
unreachable!("the value portion of CProcfsBase({arg:#x}) cannot be larger than u32 (but {value:#x} is)");
}
// PATHRS_PROC_PID(pid)
(__PATHRS_PROC_TYPE_PID, pid @ 1..=U32_MAX) => {
// Just make sure...
static_assertions::const_assert_eq!(U32_MAX, u32::MAX as u64);
// We can be sure it's okay to cast to u32, as we've checked
// statically and at runtime that the value is within the
// correct range to not truncate bits.
Ok(ProcfsBase::ProcPid(pid as u32))
}
// Error fallbacks for invalid subvalues or types.
(base_type, value) => Err(ErrorImpl::InvalidArgument {
name: "procfs base".into(),
description: match base_type {
__PATHRS_PROC_TYPE_SPECIAL => format!("{arg:#X} is an invalid special procfs base (unknown sub-value {value:#X})"),
__PATHRS_PROC_TYPE_PID => format!("pid {value} is an invalid value for PATHRS_PROC_PID"),
_ => format!("{arg:#X} has an unknown procfs base type {base_type:#X}"),
}.into(),
}.into()),
}
.wrap("the procfs base must be one of the PATHRS_PROC_* values or PATHRS_PROC_PID(n)")
}
}
}
#[cfg(test)]
impl From<ProcfsBase> for CProcfsBase {
fn from(base: ProcfsBase) -> Self {
match base {
ProcfsBase::ProcPid(pid) => {
// TODO: See if we can add some kind of static assertion that
// the type of the pid is not larger than the reserved
// block in __PATHRS_PROC_TYPE_MASK. Unfortunately Rust
// doesn't have a way of doing typeof(pid)... Maybe
// pattern_types would let us do this with something like
// ProcfsBase::ProcPid::0::MAX?
//
// static_assertions::const_assert_eq!(
// type_of<pid>::MAX & _PATHRS_PROC_TYPE_MASK,
// 0,
// );
// static_assertions::const_assert_eq!(type_of<pid>::MAX,
// u32::MAX);
// We know this to be true from the check in the above TryFrom
// impl for ProcfsBase, but add an assertion here since we
// cannot actually verify this statically at the moment.
#[allow(clippy::absurd_extreme_comparisons)]
{
assert!(pid <= u32::MAX, "pid in CProcfsBase must fit inside a u32");
}
assert_eq!(
pid as u64 & __PATHRS_PROC_TYPE_MASK, 0,
"invalid pid found when converting to CProcfsBase -- pid {pid} includes type bits ({__PATHRS_PROC_TYPE_MASK:#X})"
);
CProcfsBase(__PATHRS_PROC_TYPE_PID | pid as u64)
}
ProcfsBase::ProcRoot => CProcfsBase::PATHRS_PROC_ROOT,
ProcfsBase::ProcSelf => CProcfsBase::PATHRS_PROC_SELF,
ProcfsBase::ProcThreadSelf => CProcfsBase::PATHRS_PROC_THREAD_SELF,
}
}
}
/// A sentinel value to tell `pathrs_proc_*` methods to use the default procfs
/// root handle (which may be globally cached).
pub const PATHRS_PROC_DEFAULT_ROOTFD: CBorrowedFd<'static> =
// SAFETY: The lifetime of fake fd values are 'static.
unsafe { CBorrowedFd::from_raw_fd(-libc::EBADF) };
fn parse_proc_rootfd<'fd>(fd: CBorrowedFd<'fd>) -> Result<ProcfsHandleRef<'fd>, Error> {
match fd {
PATHRS_PROC_DEFAULT_ROOTFD => ProcfsHandle::new(),
_ => ProcfsHandleRef::try_from_borrowed_fd(fd.try_as_borrowed_fd()?),
}
}
// This is needed because the macro expansion cbindgen produces for
// bitflags! is not really usable for regular structs.
/// Construct a completely unmasked procfs handle.
///
/// This is equivalent to [`ProcfsHandleBuilder::unmasked`], and is meant as
/// a flag argument to [`ProcfsOpenFlags`] (the `flags` field in `struct
/// pathrs_procfs_open_how`) for use with pathrs_procfs_open().
pub const PATHRS_PROCFS_NEW_UNMASKED: u64 = 0x0000_0000_0000_0001;
bitflags! {
#[repr(C)]
#[derive(Default, Debug, Clone, Copy, Pod, Zeroable)]
pub struct ProcfsOpenFlags: u64 {
const PATHRS_PROCFS_NEW_UNMASKED = PATHRS_PROCFS_NEW_UNMASKED;
// NOTE: Make sure to add a `pub const` for any new flags to make
// sure they show up when cbindgen generates our header.
}
}
impl ProcfsOpenFlags {
const fn contains_unknown_bits(&self) -> bool {
Self::from_bits(self.bits()).is_none()
}
}
static_assertions::const_assert_eq!(
ProcfsOpenFlags::PATHRS_PROCFS_NEW_UNMASKED.contains_unknown_bits(),
false,
);
static_assertions::const_assert_eq!(
ProcfsOpenFlags::from_bits_retain(0x1000_0000).contains_unknown_bits(),
true,
);
static_assertions::const_assert_eq!(
ProcfsOpenFlags::from_bits_retain(0xF000_0001).contains_unknown_bits(),
true,
);
#[repr(C)]
#[derive(Default, Debug, Clone, Copy, Pod, Zeroable)]
pub struct ProcfsOpenHow {
pub flags: ProcfsOpenFlags,
}
impl ProcfsOpenHow {
fn into_builder(self) -> Result<ProcfsHandleBuilder, Error> {
let mut builder = ProcfsHandleBuilder::new();
if self.flags.contains_unknown_bits() {
Err(ErrorImpl::InvalidArgument {
name: "flags".into(),
description: format!(
"contains unknown flag bits {:#x}",
self.flags.difference(ProcfsOpenFlags::all())
)
.into(),
})?;
}
if self
.flags
.contains(ProcfsOpenFlags::PATHRS_PROCFS_NEW_UNMASKED)
{
builder.set_unmasked();
}
Ok(builder)
}
}
/// Create a new (custom) procfs root handle.
///
/// This is effectively a C wrapper around [`ProcfsHandleBuilder`], allowing you
/// to create a custom procfs root handle that can be used with other
/// `pathrs_proc_*at` methods.
///
/// While most users should just use `PATHRS_PROC_DEFAULT_ROOTFD` (or the
/// non-`at` variants of `pathrs_proc_*`), creating an unmasked procfs root
/// handle (using `PATHRS_PROCFS_NEW_UNMASKED`) can be useful for programs that
/// need to operate on a lot of global procfs files. (Note that accessing global
/// procfs files does not *require* creating a custom procfs handle --
/// `pathrs_proc_*` will automatically create a global-friendly handle
/// internally when necessary but will close it immediately after operating on
/// it.)
///
/// # Extensible Structs
///
/// The [`ProcfsOpenHow`] (`struct pathrs_procfs_open_how`) argument is
/// designed to be extensible, modelled after the extensible structs scheme used
/// by Linux (for syscalls such as [clone3(2)], [openat2(2)] and other such
/// syscalls). Normally one would use symbol versioning to achieve this, but
/// unfortunately Rust's symbol versioning support is incredibly primitive (one
/// might even say "non-existent") and so this system is more robust, even if
/// the calling convention is a little strange for userspace libraries.
///
/// In addition to a pointer argument, the caller must also provide the size of
/// the structure it is passing. By providing this information, it is possible
/// for `pathrs_procfs_open()` to provide both forwards- and
/// backwards-compatibility, with size acting as an implicit version number.
/// (Because new extension fields will always be appended, the structure size
/// will always increase.)
///
/// If we let `usize` be the structure specified by the caller, and `lsize` be
/// the size of the structure internal to libpathrs, then there are three cases
/// to consider:
///
/// * If `usize == lsize`, then there is no version mismatch and the structure
/// provided by the caller can be used verbatim.
/// * If `usize < lsize`, then there are some extension fields which libpathrs
/// supports that the caller does not. Because a zero value in any added
/// extension field signifies a no-op, libpathrs treats all of the extension
/// fields not provided by the caller as having zero values. This provides
/// backwards-compatibility.
/// * If `usize > lsize`, then there are some extension fields which the caller
/// is aware of but this version of libpathrs does not support. Because any
/// extension field must have its zero values signify a no-op, libpathrs can
/// safely ignore the unsupported extension fields if they are all-zero. If
/// any unsupported extension fields are nonzero, then an `E2BIG` error is
/// returned. This provides forwards-compatibility.
///
/// Because the definition of `struct pathrs_procfs_open_how` may open in the
/// future
///
/// Because the definition of `struct pathrs_procfs_open_how` may change in the
/// future (with new fields being added when headers are updated), callers
/// should zero-fill the structure to ensure that recompiling the program with
/// new headers will not result in spurious errors at run time. The simplest
/// way is to use a designated initialiser:
///
/// ```c
/// struct pathrs_procfs_open_how how = {
/// .flags = PATHRS_PROCFS_NEW_UNMASKED,
/// };
/// ```
///
/// or explicitly using `memset(3)` or similar:
///
/// ```c
/// struct pathrs_procfs_open_how how;
/// memset(&how, 0, sizeof(how));
/// how.flags = PATHRS_PROCFS_NEW_UNMASKED;
/// ```
///
/// # Return Value
///
/// On success, this function returns *either* a file descriptor *or*
/// `PATHRS_PROC_DEFAULT_ROOTFD` (this is a negative number, equal to `-EBADF`).
/// The file descriptor will have the `O_CLOEXEC` flag automatically applied.
///
/// If an error occurs, this function will return a negative error code. To
/// retrieve information about the error (such as a string describing the error,
/// the system errno(7) value associated with the error, etc), use
/// pathrs_errorinfo().
///
/// [clone3(2)]: https://www.man7.org/linux/man-pages/man2/clone3.2.html
/// [openat2(2)]: https://www.man7.org/linux/man-pages/man2/openat2.2.html
#[no_mangle]
pub unsafe extern "C" fn pathrs_procfs_open(args: *const ProcfsOpenHow, size: usize) -> RawFd {
|| -> Result<_, Error> {
unsafe { utils::copy_from_extensible_struct(args, size) }?
.into_builder()?
.build()
.map(ProcfsHandle::into_owned_fd)
}()
.map(|fd| match fd {
Some(fd) => fd.into_raw_fd(),
None => PATHRS_PROC_DEFAULT_ROOTFD.as_raw_fd(),
})
.into_c_return()
}
utils::symver! {
fn pathrs_procfs_open <- (pathrs_procfs_open, version = "LIBPATHRS_0.2", default);
}
/// `pathrs_proc_open` but with a caller-provided file descriptor for `/proc`.
///
/// Internally, `pathrs_proc_open` will attempt to use a cached copy of a very
/// restricted `/proc` handle (a detached mount object with `subset=pid` and
/// `hidepid=4`). If a user requests a global `/proc` file, a temporary handle
/// capable of accessing global files is created and destroyed after the
/// operation completes.
///
/// For most users, this is more than sufficient. However, if a user needs to
/// operate on many global `/proc` files, the cost of creating handles can get
/// quite expensive. `pathrs_proc_openat` allows a user to manually manage the
/// global-friendly `/proc` handle. Note that passing a `subset=pid` file
/// descriptor to `pathrs_proc_openat` will *not* stop the automatic creation of
/// a global-friendly handle internally if necessary.
///
/// In order to get the behaviour of `pathrs_proc_open`, you can pass the
/// special value `PATHRS_PROC_DEFAULT_ROOTFD` (`-EBADF`) as the `proc_rootfd`
/// argument.
///
/// # Return Value
///
/// On success, this function returns a file descriptor. The file descriptor
/// will have the `O_CLOEXEC` flag automatically applied.
///
/// If an error occurs, this function will return a negative error code. To
/// retrieve information about the error (such as a string describing the error,
/// the system errno(7) value associated with the error, etc), use
/// pathrs_errorinfo().
#[no_mangle]
pub unsafe extern "C" fn pathrs_proc_openat(
proc_rootfd: CBorrowedFd<'_>,
base: CProcfsBase,
path: *const c_char,
flags: u64,
) -> RawFd {
|| -> Result<_, Error> {
let base = base.try_into()?;
// SAFETY: C caller guarantees path is safe.
let path = unsafe { utils::parse_path(path) }?;
let oflags = OpenFlags::from_bits_retain(flags);
let procfs = parse_proc_rootfd(proc_rootfd)?;
if oflags.contains(OpenFlags::O_NOFOLLOW) {
procfs.open(base, path, oflags)
} else {
procfs.open_follow(base, path, oflags)
}
}()
.map(OwnedFd::from)
.into_c_return()
}
utils::symver! {
fn pathrs_proc_openat <- (pathrs_proc_openat, version = "LIBPATHRS_0.2.5", default);
}
/// A compatibility shim for `pathrs_proc_openat` to support 64-bit
/// [`OpenFlags`].
/// cbindgen:ignore
#[doc(hidden)]
#[no_mangle]
pub unsafe extern "C" fn __pathrs_proc_openat_v1(
proc_rootfd: CBorrowedFd<'_>,
base: CProcfsBase,
path: *const c_char,
flags: libc::c_int,
) -> RawFd {
// NOTE: i32 as u64 sign-extends so we need to cast to u32 first.
unsafe { pathrs_proc_openat(proc_rootfd, base, path, flags as u32 as u64) }
}
utils::symver! {
// In libpathrs 0.2.5, all of the flags-bearing arguments were expanded to
// u64. This shim translates the old i32 (libc::c_int) callers.
fn __pathrs_proc_openat_v1 <- (pathrs_proc_openat, version = "LIBPATHRS_0.2");
}
/// Safely open a path inside a `/proc` handle.
///
/// Any bind-mounts or other over-mounts will (depending on what kernel features
/// are available) be detected and an error will be returned. Non-trailing
/// symlinks are followed but care is taken to ensure the symlinks are
/// legitimate.
///
/// Unless you intend to open a magic-link, `O_NOFOLLOW` should be set in flags.
/// Lookups with `O_NOFOLLOW` are guaranteed to never be tricked by bind-mounts
/// (on new enough Linux kernels).
///
/// If you wish to resolve a magic-link, you need to unset `O_NOFOLLOW`.
/// Unfortunately (if libpathrs is using the regular host `/proc` mount), this
/// lookup mode cannot protect you against an attacker that can modify the mount
/// table during this operation.
///
/// NOTE: Instead of using paths like `/proc/thread-self/fd`, `base` is used to
/// indicate what "base path" inside procfs is used. For example, to re-open a
/// file descriptor:
///
/// ```c
/// fd = pathrs_proc_open(PATHRS_PROC_THREAD_SELF, "fd/101", O_RDWR);
/// if (IS_PATHRS_ERR(fd)) {
/// liberr = fd; // for use with pathrs_errorinfo()
/// goto err;
/// }
/// ```
///
/// # Return Value
///
/// On success, this function returns a file descriptor. The file descriptor
/// will have the `O_CLOEXEC` flag automatically applied.
///
/// If an error occurs, this function will return a negative error code. To
/// retrieve information about the error (such as a string describing the error,
/// the system errno(7) value associated with the error, etc), use
/// pathrs_errorinfo().
#[no_mangle]
pub unsafe extern "C" fn pathrs_proc_open(
base: CProcfsBase,
path: *const c_char,
flags: u64,
) -> RawFd {
pathrs_proc_openat(PATHRS_PROC_DEFAULT_ROOTFD, base, path, flags)
}
utils::symver! {
fn pathrs_proc_open <- (pathrs_proc_open, version = "LIBPATHRS_0.1", default);
}
/// A compatibility shim for `pathrs_proc_open` to support 64-bit [`OpenFlags`].
/// cbindgen:ignore
#[doc(hidden)]
#[no_mangle]
pub unsafe extern "C" fn __pathrs_proc_open_v1(
base: CProcfsBase,
path: *const c_char,
flags: libc::c_int,
) -> RawFd {
// NOTE: i32 as u64 sign-extends so we need to cast to u32 first.
unsafe { pathrs_proc_open(base, path, flags as u32 as u64) }
}
utils::symver! {
// In libpathrs 0.2.5, all of the flags-bearing arguments were expanded to
// u64. This shim translates the old i32 (libc::c_int) callers.
fn __pathrs_proc_open_v1 <- (pathrs_proc_open, version = "LIBPATHRS_0.2");
}
/// `pathrs_proc_readlink` but with a caller-provided file descriptor for
/// `/proc`.
///
/// See the documentation of pathrs_proc_openat() for when this API might be
/// useful.
///
/// # Return Value
///
/// On success, this function copies the symlink contents to `linkbuf` (up to
/// `linkbuf_size` bytes) and returns the full size of the symlink path buffer.
/// This function will not copy the trailing NUL byte, and the return size does
/// not include the NUL byte. A `NULL` `linkbuf` or invalid `linkbuf_size` are
/// treated as zero-size buffers.
///
/// NOTE: Unlike readlinkat(2), in the case where linkbuf is too small to
/// contain the symlink contents, pathrs_proc_readlink() will return *the number
/// of bytes it would have copied if the buffer was large enough*. This matches
/// the behaviour of pathrs_inroot_readlink().
///
/// If an error occurs, this function will return a negative error code. To
/// retrieve information about the error (such as a string describing the error,
/// the system errno(7) value associated with the error, etc), use
/// pathrs_errorinfo().
#[no_mangle]
pub unsafe extern "C" fn pathrs_proc_readlinkat(
proc_rootfd: CBorrowedFd<'_>,
base: CProcfsBase,
path: *const c_char,
linkbuf: *mut c_char,
linkbuf_size: size_t,
) -> c_int {
|| -> Result<_, Error> {
let base = base.try_into()?;
// SAFETY: C caller guarantees path is safe.
let path = unsafe { utils::parse_path(path) }?;
let procfs = parse_proc_rootfd(proc_rootfd)?;
let link_target = procfs.readlink(base, path)?;
// SAFETY: C caller guarantees buffer is at least linkbuf_size and can
// be written to.
unsafe { utils::copy_path_into_buffer(link_target, linkbuf, linkbuf_size) }
}()
.into_c_return()
}
utils::symver! {
fn pathrs_proc_readlinkat <- (pathrs_proc_readlinkat, version = "LIBPATHRS_0.2", default);
}
/// Safely read the contents of a symlink inside `/proc`.
///
/// As with `pathrs_proc_open`, any bind-mounts or other over-mounts will
/// (depending on what kernel features are available) be detected and an error
/// will be returned. Non-trailing symlinks are followed but care is taken to
/// ensure the symlinks are legitimate.
///
/// This function is effectively shorthand for
///
/// ```c
/// fd = pathrs_proc_open(base, path, O_PATH|O_NOFOLLOW);
/// if (IS_PATHRS_ERR(fd)) {
/// liberr = fd; // for use with pathrs_errorinfo()
/// goto err;
/// }
/// copied = readlinkat(fd, "", linkbuf, linkbuf_size);
/// close(fd);
/// ```
///
/// # Return Value
///
/// On success, this function copies the symlink contents to `linkbuf` (up to
/// `linkbuf_size` bytes) and returns the full size of the symlink path buffer.
/// This function will not copy the trailing NUL byte, and the return size does
/// not include the NUL byte. A `NULL` `linkbuf` or invalid `linkbuf_size` are
/// treated as zero-size buffers.
///
/// NOTE: Unlike readlinkat(2), in the case where linkbuf is too small to
/// contain the symlink contents, pathrs_proc_readlink() will return *the number
/// of bytes it would have copied if the buffer was large enough*. This matches
/// the behaviour of pathrs_inroot_readlink().
///
/// If an error occurs, this function will return a negative error code. To
/// retrieve information about the error (such as a string describing the error,
/// the system errno(7) value associated with the error, etc), use
/// pathrs_errorinfo().
#[no_mangle]
pub unsafe extern "C" fn pathrs_proc_readlink(
base: CProcfsBase,
path: *const c_char,
linkbuf: *mut c_char,
linkbuf_size: size_t,
) -> c_int {
pathrs_proc_readlinkat(
PATHRS_PROC_DEFAULT_ROOTFD,
base,
path,
linkbuf,
linkbuf_size,
)
}
utils::symver! {
fn pathrs_proc_readlink <- (pathrs_proc_readlink, version = "LIBPATHRS_0.1", default);
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{
capi::{error as capi_error, utils::Leakable},
error::ErrorKind,
procfs::ProcfsBase,
};
use std::{
mem,
os::unix::io::{FromRawFd, OwnedFd},
};
use pretty_assertions::assert_eq;
#[test]
fn procfsbase_try_from_crepr_procroot() {
assert_eq!(
ProcfsBase::try_from(CProcfsBase::PATHRS_PROC_ROOT).map_err(|e| e.kind()),
Ok(ProcfsBase::ProcRoot),
"PATHRS_PROC_ROOT.try_into()"
);
}
#[test]
fn procfsbase_try_from_crepr_procself() {
assert_eq!(
ProcfsBase::try_from(CProcfsBase::PATHRS_PROC_SELF).map_err(|e| e.kind()),
Ok(ProcfsBase::ProcSelf),
"PATHRS_PROC_SELF.try_into()"
);
}
#[test]
fn procfsbase_try_from_crepr_procthreadself() {
assert_eq!(
ProcfsBase::try_from(CProcfsBase::PATHRS_PROC_THREAD_SELF).map_err(|e| e.kind()),
Ok(ProcfsBase::ProcThreadSelf),
"PATHRS_PROC_THREAD_SELF.try_into()"
);
}
#[test]
fn procfsbase_try_from_crepr_procpid() {
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_PID | 1)).map_err(|e| e.kind()),
Ok(ProcfsBase::ProcPid(1)),
"PATHRS_PROC_PID(12345).try_into()"
);
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_PID | 12345)).map_err(|e| e.kind()),
Ok(ProcfsBase::ProcPid(12345)),
"PATHRS_PROC_PID(12345).try_into()"
);
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_PID | u32::MAX as u64))
.map_err(|e| e.kind()),
Ok(ProcfsBase::ProcPid(u32::MAX)),
"PATHRS_PROC_PID(u32::MAX).try_into()"
);
}
#[test]
fn procfsbase_try_from_crepr_procspecial_invalid() {
// Invalid __PATHRS_PROC_TYPE_SPECIAL values.
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_SPECIAL)).map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"__PATHRS_PROC_TYPE_SPECIAL.try_into() -- invalid type"
);
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_SPECIAL | 0xDEADBEEF))
.map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"(__PATHRS_PROC_TYPE_SPECIAL | 0xDEADBEEF).try_into() -- invalid type"
);
}
#[test]
fn procfsbase_try_from_crepr_procpid_invalid() {
// 0 is an invalid pid.
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_PID)).map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"PATHRS_PROC_PID(0).try_into() -- invalid pid"
);
// u32::MAX + 1 is an invalid value for multiple reasons.
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_PID | (u32::MAX as u64 + 1)))
.map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"PATHRS_PROC_PID(u32::MAX + 1).try_into() -- invalid pid"
);
}
#[test]
fn procfsbase_try_from_crepr_proctype_invalid() {
// Invalid __PATHRS_PROC_TYPE_MASK values.
assert_eq!(
ProcfsBase::try_from(CProcfsBase(0xDEAD_BEEF_0000_0001)).map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"0xDEAD_BEEF_0000_0001.try_into() -- invalid type"
);
assert_eq!(
ProcfsBase::try_from(CProcfsBase(0xDEAD_BEEF_3EAD_5E1F)).map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"0xDEAD_BEEF_3EAD_5E1F.try_into() -- invalid type"
);
assert_eq!(
ProcfsBase::try_from(CProcfsBase(__PATHRS_PROC_TYPE_MASK)).map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"__PATHRS_PROC_TYPE_MASK.try_into() -- invalid type"
);
}
#[test]
fn procfsbase_try_from_crepr_invalid() {
// Plain values are invalid.
assert_eq!(
ProcfsBase::try_from(CProcfsBase(0)).map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"(0).try_into() -- invalid value"
);
assert_eq!(
ProcfsBase::try_from(CProcfsBase(0xDEADBEEF)).map_err(|e| e.kind()),
Err(ErrorKind::InvalidArgument),
"(0xDEADBEEF).try_into() -- invalid value"
);
}
#[test]
fn procfsbase_into_crepr_procroot() {
assert_eq!(
CProcfsBase::from(ProcfsBase::ProcRoot),
CProcfsBase::PATHRS_PROC_ROOT,
"ProcRoot.into() == PATHRS_PROC_ROOT"
);
}
#[test]
fn procfsbase_into_crepr_procself() {
assert_eq!(
CProcfsBase::from(ProcfsBase::ProcSelf),
CProcfsBase::PATHRS_PROC_SELF,
"ProcSelf.into() == PATHRS_PROC_SELF"
);
}
#[test]
fn procfsbase_into_crepr_procthreadself() {
assert_eq!(
CProcfsBase::from(ProcfsBase::ProcThreadSelf),
CProcfsBase::PATHRS_PROC_THREAD_SELF,
"ProcThreadSelf.into() == PATHRS_PROC_THREAD_SELF"
);
}
#[test]
fn procfsbase_into_crepr_procpid() {
assert_eq!(
CProcfsBase::from(ProcfsBase::ProcPid(1)),
CProcfsBase(__PATHRS_PROC_TYPE_PID | 1),
"ProcPid(1).into() == 1"
);
assert_eq!(
CProcfsBase::from(ProcfsBase::ProcPid(1122334455)),
CProcfsBase(__PATHRS_PROC_TYPE_PID | 1122334455),
"ProcPid(1122334455).into() == 1122334455"
);
}
fn check_round_trip(rust: ProcfsBase, c: CProcfsBase) {
let c_to_rust: ProcfsBase = c.try_into().expect("should be valid value");
assert_eq!(
rust, c_to_rust,
"c-to-rust ProcfsBase conversion ({c:?}.try_into())"
);
let rust_to_c: CProcfsBase = rust.into();
assert_eq!(
c, rust_to_c,
"rust-to-c ProcfsBase conversion ({rust:?}.into())"
);
let c_to_rust_to_c: CProcfsBase = c_to_rust.into();
assert_eq!(
c, c_to_rust_to_c,
"rust-to-c-to-rust ProcfsBase conversion ({c_to_rust:?}.into())"
);
let rust_to_c_to_rust: ProcfsBase = rust_to_c
.try_into()
.expect("must be valid value when round-tripping");
assert_eq!(
rust, rust_to_c_to_rust,
"rust-to-c-to-rust ProcfsBase conversion ({rust_to_c:?}.try_into())"
);
}
#[test]
fn procfsbase_round_trip_procroot() {
check_round_trip(ProcfsBase::ProcRoot, CProcfsBase::PATHRS_PROC_ROOT);
}
#[test]
fn procfsbase_round_trip_procself() {
check_round_trip(ProcfsBase::ProcSelf, CProcfsBase::PATHRS_PROC_SELF);
}
#[test]
fn procfsbase_round_trip_procthreadself() {
check_round_trip(
ProcfsBase::ProcThreadSelf,
CProcfsBase::PATHRS_PROC_THREAD_SELF,
);
}
#[test]
fn procfsbase_round_trip_procpid() {
check_round_trip(
ProcfsBase::ProcPid(1),
CProcfsBase(__PATHRS_PROC_TYPE_PID | 1),
);
check_round_trip(
ProcfsBase::ProcPid(12345),
CProcfsBase(__PATHRS_PROC_TYPE_PID | 12345),
);
check_round_trip(
ProcfsBase::ProcPid(1122334455),
CProcfsBase(__PATHRS_PROC_TYPE_PID | 1122334455),
);
check_round_trip(
ProcfsBase::ProcPid(u32::MAX),
CProcfsBase(__PATHRS_PROC_TYPE_PID | u32::MAX as u64),
);
}
#[test]
fn pathrs_procfs_open_cached() {
let procfs_is_cached = ProcfsHandle::new()
.expect("ProcfsHandle::new should not fail")
.into_owned_fd()
.is_none();
let how = ProcfsOpenHow::default();
let fd = unsafe { pathrs_procfs_open(&how as *const _, mem::size_of::<ProcfsOpenHow>()) };
let procfs = if procfs_is_cached {
assert_eq!(
fd,
PATHRS_PROC_DEFAULT_ROOTFD.as_raw_fd(),
"if ProcfsHandle::new() is cached then pathrs_procfs_open() should return PATHRS_PROC_DEFAULT_ROOTFD",
);
ProcfsHandle::new()
} else {
ProcfsHandle::try_from_fd(unsafe { OwnedFd::from_raw_fd(fd) })
}.expect("pathrs_procfs_open should return a valid procfs fd");
let _ = procfs
.open(ProcfsBase::ProcSelf, ".", OpenFlags::O_PATH)
.expect("open(.) should always succeed");
}
#[test]
fn pathrs_procfs_open_unmasked() {
let how = ProcfsOpenHow {
flags: ProcfsOpenFlags::PATHRS_PROCFS_NEW_UNMASKED,
};
let fd = unsafe { pathrs_procfs_open(&how as *const _, mem::size_of::<ProcfsOpenHow>()) };
assert!(fd >= 0, "fd value {fd:#x} should be >= 0");
let procfs = ProcfsHandle::try_from_fd(unsafe { OwnedFd::from_raw_fd(fd) })
.expect("pathrs_procfs_open should return a valid procfs fd");
let _ = procfs
.open(ProcfsBase::ProcSelf, ".", OpenFlags::O_PATH)
.expect("open(.) should always succeed");
}
#[test]
fn pathrs_procfs_open_bad_flag() {
let how_bad_flags = ProcfsOpenHow {
flags: ProcfsOpenFlags::from_bits_retain(0xF000),
};
let ret = unsafe {
pathrs_procfs_open(&how_bad_flags as *const _, mem::size_of::<ProcfsOpenHow>())
};
assert!(
ret < capi_error::__PATHRS_MAX_ERR_VALUE,
"ret value {ret:#x} should be error value"
);
{
let err = unsafe {
capi_error::pathrs_errorinfo(ret)
.expect("error must be retrievable")
.unleak()
};
// err.kind() == ErrorKind::InvalidArgument
assert_eq!(
err.saved_errno,
libc::EINVAL as _,
"invalid flag should return EINVAL"
);
}
}
#[test]
fn pathrs_procfs_open_bad_struct() {
#[repr(C)]
#[derive(Default, Debug, Clone, Copy, Pod, Zeroable)]
struct ProcfsOpenHowV2 {
inner: ProcfsOpenHow,
extra: u64,
}
let how_ok_struct = ProcfsOpenHowV2 {
inner: ProcfsOpenHow {
flags: ProcfsOpenFlags::PATHRS_PROCFS_NEW_UNMASKED,
},
extra: 0,
};
let fd = unsafe {
pathrs_procfs_open(
&how_ok_struct as *const _ as *const _,
mem::size_of::<ProcfsOpenHowV2>(),
)
};
assert!(fd >= 0, "fd value {fd:#x} should be >= 0");
{
// Close the file.
let _ = unsafe { OwnedFd::from_raw_fd(fd) };
}
let how_bad_struct = ProcfsOpenHowV2 {
inner: ProcfsOpenHow {
flags: ProcfsOpenFlags::PATHRS_PROCFS_NEW_UNMASKED,
},
extra: 0xFF,
};
let ret = unsafe {
pathrs_procfs_open(
&how_bad_struct as *const _ as *const _,
mem::size_of::<ProcfsOpenHowV2>(),
)
};
assert!(
ret < capi_error::__PATHRS_MAX_ERR_VALUE,
"ret value {ret:#x} should be error value"
);
{
let err = unsafe {
capi_error::pathrs_errorinfo(ret)
.expect("error must be retrievable")
.unleak()
};
// err.kind() == ErrorKind::UnsupportedStructureData
assert_eq!(
err.saved_errno,
libc::E2BIG as _,
"structure with extra trailing bytes should return E2BIG"
);
}
}
}