From aee2fff0ba0bdc2e89537499bf2fa9dd0f3be8a2 Mon Sep 17 00:00:00 2001 From: Thomas Bertschinger Date: Tue, 9 Sep 2025 09:53:16 -0600 Subject: [PATCH 1/4] fs: introduce AT_ filehandle constants for name_to_handle_at(2) --- src/backend/libc/fs/types.rs | 28 ++++++++++++++++++++++++++++ src/backend/linux_raw/conv.rs | 7 +++++++ src/backend/linux_raw/fs/types.rs | 28 ++++++++++++++++++++++++++++ 3 files changed, 63 insertions(+) diff --git a/src/backend/libc/fs/types.rs b/src/backend/libc/fs/types.rs index b8944ad7c..ff4025e61 100644 --- a/src/backend/libc/fs/types.rs +++ b/src/backend/libc/fs/types.rs @@ -543,6 +543,34 @@ bitflags! { } } +#[cfg(target_os = "linux")] +bitflags! { + /// `AT_*` constants for use with [`name_to_handle_at`] + /// + /// [`name_to_handle_at`]: crate::fs::name_to_handle_at + #[repr(transparent)] + #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] + pub struct HandleFlags: u32 { + /// `AT_HANDLE_FID` + const FID = linux_raw_sys::general::AT_HANDLE_FID; + + /// `AT_HANDLE_MNT_ID_UNIQUE` + const MNT_ID_UNIQUE = linux_raw_sys::general::AT_HANDLE_MNT_ID_UNIQUE; + + /// `AT_HANDLE_CONNECTABLE` + const CONNECTABLE = linux_raw_sys::general::AT_HANDLE_CONNECTABLE; + + /// `AT_SYMLINK_FOLLOW` + const SYMLINK_FOLLOW = linux_raw_sys::general::AT_SYMLINK_FOLLOW; + + /// `AT_EMPTY_PATH` + const EMPTY_PATH = linux_raw_sys::general::AT_EMPTY_PATH; + + /// + const _ = !0; + } +} + /// `S_IF*` constants for use with [`mknodat`] and [`Stat`]'s `st_mode` field. /// /// [`mknodat`]: crate::fs::mknodat diff --git a/src/backend/linux_raw/conv.rs b/src/backend/linux_raw/conv.rs index 3d4693fe1..45a943e8b 100644 --- a/src/backend/linux_raw/conv.rs +++ b/src/backend/linux_raw/conv.rs @@ -333,6 +333,13 @@ pub(crate) mod fs { } } + impl<'a, Num: ArgNumber> From for ArgReg<'a, Num> { + #[inline] + fn from(flags: crate::fs::HandleFlags) -> Self { + c_uint(flags.bits()) + } + } + impl<'a, Num: ArgNumber> From for ArgReg<'a, Num> { #[inline] fn from(flags: crate::fs::XattrFlags) -> Self { diff --git a/src/backend/linux_raw/fs/types.rs b/src/backend/linux_raw/fs/types.rs index 7abd66539..92589a819 100644 --- a/src/backend/linux_raw/fs/types.rs +++ b/src/backend/linux_raw/fs/types.rs @@ -321,6 +321,34 @@ bitflags! { } } +#[cfg(target_os = "linux")] +bitflags! { + /// `AT_*` constants for use with [`name_to_handle_at`] + /// + /// [`name_to_handle_at`]: crate::fs::name_to_handle_at + #[repr(transparent)] + #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] + pub struct HandleFlags: ffi::c_uint { + /// `AT_HANDLE_FID` + const FID = linux_raw_sys::general::AT_HANDLE_FID; + + /// `AT_HANDLE_MNT_ID_UNIQUE` + const MNT_ID_UNIQUE = linux_raw_sys::general::AT_HANDLE_MNT_ID_UNIQUE; + + /// `AT_HANDLE_CONNECTABLE` + const CONNECTABLE = linux_raw_sys::general::AT_HANDLE_CONNECTABLE; + + /// `AT_SYMLINK_FOLLOW` + const SYMLINK_FOLLOW = linux_raw_sys::general::AT_SYMLINK_FOLLOW; + + /// `AT_EMPTY_PATH` + const EMPTY_PATH = linux_raw_sys::general::AT_EMPTY_PATH; + + /// + const _ = !0; + } +} + /// `S_IF*` constants for use with [`mknodat`] and [`Stat`]'s `st_mode` field. /// /// [`mknodat`]: crate::fs::mknodat From 74163ec1cbf3244d75622b56ad81087b998deb90 Mon Sep 17 00:00:00 2001 From: Thomas Bertschinger Date: Tue, 9 Sep 2025 09:56:22 -0600 Subject: [PATCH 2/4] fs: introduce name_to_handle_at() --- src/backend/libc/fs/syscalls.rs | 31 ++++++ src/backend/linux_raw/fs/syscalls.rs | 23 ++++ src/fs/filehandle.rs | 160 +++++++++++++++++++++++++++ src/fs/mod.rs | 4 + 4 files changed, 218 insertions(+) create mode 100644 src/fs/filehandle.rs diff --git a/src/backend/libc/fs/syscalls.rs b/src/backend/libc/fs/syscalls.rs index 71bc8b0ab..2cbb681e4 100644 --- a/src/backend/libc/fs/syscalls.rs +++ b/src/backend/libc/fs/syscalls.rs @@ -31,6 +31,8 @@ use crate::fs::FallocateFlags; target_os = "wasi" )))] use crate::fs::FlockOperation; +#[cfg(all(target_os = "linux", feature = "alloc"))] +use crate::fs::HandleFlags; #[cfg(any(linux_kernel, target_os = "freebsd"))] use crate::fs::MemfdFlags; #[cfg(any(linux_kernel, apple, target_os = "redox"))] @@ -1898,6 +1900,35 @@ const SYS_OPENAT2: i32 = 437; #[cfg(all(linux_kernel, target_pointer_width = "64"))] const SYS_OPENAT2: i64 = 437; +#[cfg(all(target_os = "linux", feature = "alloc"))] +pub(crate) fn name_to_handle_at( + dirfd: BorrowedFd<'_>, + path: &CStr, + handle: *mut ffi::c_void, + mount_id: *mut ffi::c_void, + flags: HandleFlags, +) -> io::Result<()> { + syscall! { + fn name_to_handle_at( + dir_fd: c::c_int, + path: *const ffi::c_char, + handle: *mut ffi::c_void, + mount_id: *mut ffi::c_void, + flags: u32 + ) via SYS_name_to_handle_at -> c::c_int + } + + unsafe { + ret(name_to_handle_at( + borrowed_fd(dirfd), + c_str(path), + handle, + mount_id, + flags.bits(), + )) + } +} + #[cfg(target_os = "linux")] pub(crate) fn sendfile( out_fd: BorrowedFd<'_>, diff --git a/src/backend/linux_raw/fs/syscalls.rs b/src/backend/linux_raw/fs/syscalls.rs index 908272f45..7ab5b4b4d 100644 --- a/src/backend/linux_raw/fs/syscalls.rs +++ b/src/backend/linux_raw/fs/syscalls.rs @@ -28,6 +28,8 @@ use crate::backend::conv::{ use crate::backend::conv::{loff_t, loff_t_from_u64, ret_u64}; use crate::fd::{BorrowedFd, OwnedFd}; use crate::ffi::CStr; +#[cfg(feature = "alloc")] +use crate::fs::HandleFlags; #[cfg(any(target_arch = "aarch64", target_arch = "riscv64"))] use crate::fs::CWD; use crate::fs::{ @@ -1665,6 +1667,27 @@ pub(crate) fn fremovexattr(fd: BorrowedFd<'_>, name: &CStr) -> io::Result<()> { unsafe { ret(syscall_readonly!(__NR_fremovexattr, fd, name)) } } +#[cfg(feature = "alloc")] +#[inline] +pub(crate) fn name_to_handle_at( + dirfd: BorrowedFd<'_>, + path: &CStr, + file_handle: *mut core::ffi::c_void, + mount_id: *mut core::ffi::c_void, + flags: HandleFlags, +) -> io::Result<()> { + unsafe { + ret(syscall!( + __NR_name_to_handle_at, + dirfd, + path, + file_handle, + mount_id, + flags + )) + } +} + // Some linux_raw_sys structs have unsigned types for values which are // interpreted as signed. This defines a utility or casting to the // same-sized signed type. diff --git a/src/fs/filehandle.rs b/src/fs/filehandle.rs new file mode 100644 index 000000000..3d4a8777e --- /dev/null +++ b/src/fs/filehandle.rs @@ -0,0 +1,160 @@ +use alloc::{boxed::Box, vec}; +use core::mem::size_of; + +use crate::{backend, ffi, io, path}; +use backend::fd::{AsFd, OwnedFd}; +use backend::fs::types::{HandleFlags, OFlags}; + +/// This maximum is more of a "guideline"; the man page for name_to_handle_at(2) indicates it could +/// increase in the future. This value is defined in libc `fcntl.h`. +const MAX_HANDLE_SIZE: usize = 128; + +/// The minimum size of a `struct file_handle` is the size of an int and an unsigned int, for the +/// length and type fields. +const HANDLE_STRUCT_SIZE: usize = size_of::() + size_of::(); + +/// An opaque identifier for a file. +/// +/// While the C struct definition in `fcntl.h` exposes the length and type fields, +/// user applications cannot usefully interpret (or modify) those fields of a file handle, so +/// this implementation does not expose them. +#[derive(Debug)] +pub struct FileHandle { + raw: Box<[u8]>, +} + +impl FileHandle { + fn new(size: usize) -> Self { + let handle_allocation_size: usize = HANDLE_STRUCT_SIZE + size; + let bytes = vec![0; handle_allocation_size]; + + let mut handle = Self { + raw: Box::from(bytes), + }; + handle.set_handle_len(size); + + handle + } + + /// Create a file handle from a sequence of bytes. + /// + /// # Panics + /// + /// Panics if the given handle is malformed, suggesting that it did not originate from a + /// previous call to name_to_handle_at(). + pub fn from_raw(raw: Box<[u8]>) -> Self { + assert!(raw.len() >= HANDLE_STRUCT_SIZE); + + let handle = Self { raw }; + + assert!(handle.raw.len() >= handle.get_handle_len() + HANDLE_STRUCT_SIZE); + + handle + } + + /// Get the raw bytes of a file handle. + pub fn into_raw(self) -> Box<[u8]> { + self.raw + } + + /// Borrow the raw bytes of a file handle. + pub fn as_raw(&self) -> &[u8] { + &self.raw + } + + /// Get the `f_handle` field, i.e. the actual file handle contents, as a byte slice. + pub fn get_handle_contents(&self) -> &[u8] { + &self.raw[HANDLE_STRUCT_SIZE..] + } + + /// Set the `handle_bytes` field (first 4 bytes of the struct) to the given length. + fn set_handle_len(&mut self, size: usize) { + self.raw[0..size_of::()].copy_from_slice(&(size as ffi::c_uint).to_ne_bytes()); + } + + /// Get the length of the file handle data by reading the `handle_bytes` field + fn get_handle_len(&self) -> usize { + ffi::c_uint::from_ne_bytes( + self.raw[0..size_of::()] + .try_into() + .expect("Vector should be long enough"), + ) as usize + } + + fn as_mut_ptr(&mut self) -> *mut ffi::c_void { + self.raw.as_mut_ptr() as *mut _ + } +} + +/// `name_to_handle_at(dirfd, path, flags)` - Gets a filehandle given a path. +/// +/// # References +/// - [Linux] +/// +/// [Linux]: https://man7.org/linux/man-pages/man2/open_by_handle_at.2.html +pub fn name_to_handle_at( + dirfd: Fd, + path: P, + flags: HandleFlags, +) -> io::Result<(FileHandle, u64)> { + // name_to_handle_at(2) takes the mount_id parameter as either a 32-bit or 64-bit int pointer + // depending on the flag AT_HANDLE_MNT_ID_UNIQUE + let mount_id_unique: bool = flags.contains(HandleFlags::MNT_ID_UNIQUE); + let mut mount_id_64: u64 = 0; + let mut mount_id_int: ffi::c_int = 0; + + let mount_id_ptr = if mount_id_unique { + &mut mount_id_64 as *mut u64 as *mut _ + } else { + &mut mount_id_int as *mut ffi::c_int as *mut _ + }; + + // The MAX_HANDLE_SZ constant is not a fixed upper bound, because the kernel is permitted to + // increase it in the future. So, the loop is needed in the rare case that MAX_HANDLE_SZ was + // insufficient. + let mut handle_size: usize = MAX_HANDLE_SIZE; + path.into_with_c_str(|path| loop { + let mut file_handle = FileHandle::new(handle_size); + + let ret = backend::fs::syscalls::name_to_handle_at( + dirfd.as_fd(), + path, + file_handle.as_mut_ptr(), + mount_id_ptr, + flags, + ); + + // If EOVERFLOW was returned, and the handle size was increased, we need to try again with + // a larger handle. If the handle size was not increased, EOVERFLOW was due to some other + // cause, and should be returned to the user. + if let Err(e) = ret { + if e == io::Errno::OVERFLOW && file_handle.get_handle_len() > handle_size { + handle_size = file_handle.get_handle_len(); + continue; + } + } + + let mount_id: u64 = if mount_id_unique { + mount_id_64 + } else { + mount_id_int as u64 + }; + + return ret.map(|_| (file_handle, mount_id)); + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_name_to_handle() { + // On a new enough kernel, AT_HANDLE_MNT_ID_UNIQUE should succeed, but it should be rejected + // with -EINVAL on an older kernel: + if let Err(e) = name_to_handle_at(crate::fs::CWD, "Cargo.toml", HandleFlags::MNT_ID_UNIQUE) + { + assert!(e == io::Errno::INVAL); + } + } +} diff --git a/src/fs/mod.rs b/src/fs/mod.rs index 5dbd7cbb8..b17a91d93 100644 --- a/src/fs/mod.rs +++ b/src/fs/mod.rs @@ -25,6 +25,8 @@ mod fcntl_apple; #[cfg(apple)] mod fcopyfile; pub(crate) mod fd; +#[cfg(all(target_os = "linux", feature = "alloc"))] +mod filehandle; #[cfg(all(apple, feature = "alloc"))] mod getpath; #[cfg(not(target_os = "wasi"))] // WASI doesn't have get[gpu]id. @@ -90,6 +92,8 @@ pub use fcntl_apple::*; #[cfg(apple)] pub use fcopyfile::*; pub use fd::*; +#[cfg(all(target_os = "linux", feature = "alloc"))] +pub use filehandle::*; #[cfg(all(apple, feature = "alloc"))] pub use getpath::getpath; #[cfg(not(target_os = "wasi"))] From 1dbfeb2b7b044390dee4c2b1bc92a889759fda63 Mon Sep 17 00:00:00 2001 From: Thomas Bertschinger Date: Tue, 9 Sep 2025 09:56:51 -0600 Subject: [PATCH 3/4] fs: introduce open_by_handle_at() --- src/backend/libc/fs/syscalls.rs | 23 +++++++++++++++++++++++ src/backend/linux_raw/fs/syscalls.rs | 10 ++++++++++ src/fs/filehandle.rs | 18 ++++++++++++++++++ 3 files changed, 51 insertions(+) diff --git a/src/backend/libc/fs/syscalls.rs b/src/backend/libc/fs/syscalls.rs index 2cbb681e4..66bacd64d 100644 --- a/src/backend/libc/fs/syscalls.rs +++ b/src/backend/libc/fs/syscalls.rs @@ -1929,6 +1929,29 @@ pub(crate) fn name_to_handle_at( } } +#[cfg(all(target_os = "linux", feature = "alloc"))] +pub(crate) fn open_by_handle_at( + mount_fd: BorrowedFd<'_>, + handle: *const core::ffi::c_void, + flags: OFlags, +) -> io::Result { + syscall! { + fn open_by_handle_at( + mount_fd: c::c_int, + handle: *const ffi::c_void, + flags: u32 + ) via SYS_open_by_handle_at -> c::c_int + } + + unsafe { + ret_owned_fd(open_by_handle_at( + borrowed_fd(mount_fd), + handle, + flags.bits(), + )) + } +} + #[cfg(target_os = "linux")] pub(crate) fn sendfile( out_fd: BorrowedFd<'_>, diff --git a/src/backend/linux_raw/fs/syscalls.rs b/src/backend/linux_raw/fs/syscalls.rs index 7ab5b4b4d..5ffbde580 100644 --- a/src/backend/linux_raw/fs/syscalls.rs +++ b/src/backend/linux_raw/fs/syscalls.rs @@ -1688,6 +1688,16 @@ pub(crate) fn name_to_handle_at( } } +#[cfg(feature = "alloc")] +#[inline] +pub(crate) fn open_by_handle_at( + mount_fd: BorrowedFd<'_>, + handle: *const core::ffi::c_void, + flags: OFlags, +) -> io::Result { + unsafe { ret_owned_fd(syscall!(__NR_open_by_handle_at, mount_fd, handle, flags)) } +} + // Some linux_raw_sys structs have unsigned types for values which are // interpreted as signed. This defines a utility or casting to the // same-sized signed type. diff --git a/src/fs/filehandle.rs b/src/fs/filehandle.rs index 3d4a8777e..7177857e4 100644 --- a/src/fs/filehandle.rs +++ b/src/fs/filehandle.rs @@ -84,6 +84,10 @@ impl FileHandle { fn as_mut_ptr(&mut self) -> *mut ffi::c_void { self.raw.as_mut_ptr() as *mut _ } + + fn as_ptr(&self) -> *const ffi::c_void { + self.raw.as_ptr() as *const _ + } } /// `name_to_handle_at(dirfd, path, flags)` - Gets a filehandle given a path. @@ -144,6 +148,20 @@ pub fn name_to_handle_at( }) } +/// `open_by_handle_at(mount_fd, handle, flags)` - Open a file by filehandle. +/// +/// # References +/// - [Linux] +/// +/// [Linux]: https://man7.org/linux/man-pages/man2/open_by_handle_at.2.html +pub fn open_by_handle_at( + mount_fd: Fd, + handle: &FileHandle, + flags: OFlags, +) -> io::Result { + backend::fs::syscalls::open_by_handle_at(mount_fd.as_fd(), handle.as_ptr(), flags) +} + #[cfg(test)] mod tests { use super::*; From 77ed62505e759c353c87ad9f555763630c92ac41 Mon Sep 17 00:00:00 2001 From: Thomas Bertschinger Date: Wed, 10 Sep 2025 08:31:04 -0600 Subject: [PATCH 4/4] filehandle: trim the filehandle slice before returning it to user This way, once the user gets it, the filehandle slice is only as large as it needs to be. Then if the user copies it, excess unused bytes are not copied. --- src/fs/filehandle.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/fs/filehandle.rs b/src/fs/filehandle.rs index 7177857e4..34f1910d2 100644 --- a/src/fs/filehandle.rs +++ b/src/fs/filehandle.rs @@ -67,6 +67,16 @@ impl FileHandle { &self.raw[HANDLE_STRUCT_SIZE..] } + /// We allocate the "maximum" size for a file handle straight away in order to avoid needing + /// multiple syscalls / reallocations whenever possible. However, that leaves raw.len() + /// excessively high when the filehandle will usually be much smaller than MAX_HANDLE_SIZE. + /// This function "trims" the filehandle so that the slice is only as large as it needs to be. + fn trim(&mut self) { + let len = self.get_handle_len() + HANDLE_STRUCT_SIZE; + + self.raw = Box::from(&self.raw[0..len]); + } + /// Set the `handle_bytes` field (first 4 bytes of the struct) to the given length. fn set_handle_len(&mut self, size: usize) { self.raw[0..size_of::()].copy_from_slice(&(size as ffi::c_uint).to_ne_bytes()); @@ -144,6 +154,9 @@ pub fn name_to_handle_at( mount_id_int as u64 }; + // Ensure the slice is only as large as it needs to be before returning it to the user. + file_handle.trim(); + return ret.map(|_| (file_handle, mount_id)); }) }