fxcp_core/

mount_info.rs

// SPDX-License-Identifier: GPL-2.0-or-later
// Copyright (C) 2025 Joel Wirāmu Pauling <aenertia@aenertia.net>
//
// fxcp-core/src/mount_info.rs  --  Unified mount enumeration via statmount(2) / mountinfo

//! Unified mount enumeration API.
//!
//! Uses `statmount(2)` / `listmount(2)` on Linux >= 6.8 for direct kernel mount
//! queries, falling back to `/proc/self/mountinfo` text parsing on older kernels.
//! On kernels where `statmount` is available but `SB_SOURCE` is not (e.g. RHEL
//! 10.2 kernel 6.12), the statmount results are enriched with source and options
//! from `/proc/self/mountinfo`.

#![allow(clippy::expect_used)]
use std::collections::HashMap;
use std::sync::OnceLock;
use tracing::{debug, warn};

// ---------------------------------------------------------------------------
// MountEntry  --  unified result struct
// ---------------------------------------------------------------------------

/// A single mount point with fields matching `/proc/self/mountinfo` columns.
#[derive(Debug, Clone)]
pub struct MountEntry {
    /// Unique mount ID (field 1 in mountinfo, `mnt_id_old` in statmount).
    pub mount_id: u64,
    /// Parent mount ID (field 2 in mountinfo, `mnt_parent_id_old` in statmount).
    pub parent_id: u64,
    /// Device major number (field 3 `major:minor` in mountinfo).
    pub dev_major: u32,
    /// Device minor number (field 3 `major:minor` in mountinfo).
    pub dev_minor: u32,
    /// Mount root within the filesystem (field 4 in mountinfo).
    pub root: String,
    /// Mount point path (field 5 in mountinfo).
    pub mount_point: String,
    /// Per-mount options (field 6 in mountinfo, e.g. `rw,relatime`).
    pub mount_options: String,
    /// Filesystem type (after ` - ` separator in mountinfo, e.g. `xfs`, `nfs4`).
    pub fs_type: String,
    /// Mount source device or server (after ` - ` separator, e.g. `/dev/sda1`).
    pub source: String,
    /// Superblock options (after ` - ` separator, e.g. `rw,seclabel,attr2`).
    pub super_options: String,
}

// ---------------------------------------------------------------------------
// Syscall numbers
// ---------------------------------------------------------------------------

/// `statmount(2)` syscall number  --  457 on x86_64, aarch64, s390x, and powerpc64.
#[cfg(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
))]
const SYS_STATMOUNT: libc::c_long = 457;

/// `listmount(2)` syscall number  --  458 on x86_64, aarch64, s390x, and powerpc64.
#[cfg(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
))]
const SYS_LISTMOUNT: libc::c_long = 458;

// ---------------------------------------------------------------------------
// statmount request mask flags (from <linux/mount.h>)
// ---------------------------------------------------------------------------

/// Want sb_dev_major, sb_dev_minor, sb_magic, sb_flags.
const STATMOUNT_SB_BASIC: u64 = 0x0000_0001;
/// Want mnt_id, mnt_parent_id, mnt_attr, mnt_propagation, mnt_peer_group, mnt_master.
const STATMOUNT_MNT_BASIC: u64 = 0x0000_0002;
/// Want mnt_root string.
const STATMOUNT_MNT_ROOT: u64 = 0x0000_0008;
/// Want mnt_point string.
const STATMOUNT_MNT_POINT: u64 = 0x0000_0010;
/// Want fs_type string.
const STATMOUNT_FS_TYPE: u64 = 0x0000_0020;
/// Want mnt_opts string (filesystem-specific options via `show_options()`).
const STATMOUNT_MNT_OPTS: u64 = 0x0000_0080;
/// Want sb_source string (mount source device). Kernel >= 6.13.
const STATMOUNT_SB_SOURCE: u64 = 0x0000_0200;

/// `LSMT_ROOT`  --  list all mounts in the current namespace.
const LSMT_ROOT: u64 = 0xffff_ffff_ffff_ffff;

/// `MNT_ID_REQ_SIZE_VER0`  --  24-byte v0 request (compatible with all >= 6.8).
const MNT_ID_REQ_SIZE_VER0: u32 = 24;

// ---------------------------------------------------------------------------
// statmount struct byte offsets (str[] is always at offset 512)
// ---------------------------------------------------------------------------

const OFF_SIZE: usize = 0; // u32  --  total size including strings
const OFF_MNT_OPTS_STR: usize = 4; // u32  --  string offset into str[]
const OFF_MASK: usize = 8; // u64  --  which fields were filled
const OFF_SB_DEV_MAJOR: usize = 16; // u32
const OFF_SB_DEV_MINOR: usize = 20; // u32
const OFF_FS_TYPE_STR: usize = 36; // u32  --  string offset into str[]
const _OFF_MNT_ID: usize = 40; // u64  --  new-style unique mount ID (reserved for future use)
const _OFF_MNT_PARENT_ID: usize = 48; // u64 (reserved for future use)
const OFF_MNT_ID_OLD: usize = 56; // u32  --  old-style (mountinfo-compatible)
const OFF_MNT_PARENT_ID_OLD: usize = 60; // u32
const OFF_MNT_ROOT_STR: usize = 104; // u32  --  string offset into str[]
const OFF_MNT_POINT_STR: usize = 108; // u32  --  string offset into str[]
// sb_source: at offset 124 on kernels that define it (>= 6.13).
// On older kernels this falls inside __spare2 (zeroed).
const OFF_SB_SOURCE_STR: usize = 124; // u32  --  string offset into str[]
/// `str[]` flexible array starts at this fixed offset in every kernel version.
const OFF_STR: usize = 512;

// ---------------------------------------------------------------------------
// mnt_id_req  --  request struct for statmount(2) / listmount(2)
// ---------------------------------------------------------------------------

/// Kernel `struct mnt_id_req` (v0, 24 bytes).
///
/// For `statmount`: `param` = requested mask bits.
/// For `listmount`: `param` = last mount ID seen (pagination cursor).
#[repr(C)]
struct MntIdReq {
    size: u32,
    spare: u32,
    mnt_id: u64,
    param: u64,
}

// ---------------------------------------------------------------------------
// Availability probe (cached)
// ---------------------------------------------------------------------------

static STATMOUNT_AVAILABLE: OnceLock<bool> = OnceLock::new();

#[cfg(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
))]
fn probe_statmount() -> bool {
    *STATMOUNT_AVAILABLE.get_or_init(|| {
        // SAFETY: Null pointer probe  --  the kernel returns EFAULT (syscall exists)
        // or ENOSYS (not implemented). No memory is written.
        let ret = unsafe {
            libc::syscall(
                SYS_STATMOUNT,
                std::ptr::null::<u8>(),
                std::ptr::null::<u8>(),
                0usize,
                0u32,
            )
        };
        let available = if ret == -1 {
            let errno = unsafe { *libc::__errno_location() };
            errno != libc::ENOSYS
        } else {
            true // unexpected success with null args, but syscall exists
        };
        if available {
            debug!("statmount(2)/listmount(2) available  --  using kernel mount API");
        } else {
            debug!("statmount(2) not available (ENOSYS)  --  using /proc/self/mountinfo");
        }
        available
    })
}

#[cfg(not(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
)))]
fn probe_statmount() -> bool {
    false
}

// ---------------------------------------------------------------------------
// Buffer helpers
// ---------------------------------------------------------------------------

/// Read a native-endian `u32` from `buf` at `off`.
#[inline]
fn read_u32(buf: &[u8], off: usize) -> u32 {
    let bytes: [u8; 4] = buf[off..off + 4].try_into().expect("slice too short for u32");
    u32::from_ne_bytes(bytes)
}

/// Read a native-endian `u64` from `buf` at `off`.
#[inline]
fn read_u64(buf: &[u8], off: usize) -> u64 {
    let bytes: [u8; 8] = buf[off..off + 8].try_into().expect("slice too short for u64");
    u64::from_ne_bytes(bytes)
}

/// Read a NUL-terminated string from the `str[]` section of a statmount buffer.
fn read_statmount_str(buf: &[u8], str_off: u32) -> String {
    let start = OFF_STR + str_off as usize;
    if start >= buf.len() {
        return String::new();
    }
    let remaining = &buf[start..];
    let end = remaining
        .iter()
        .position(|&b| b == 0)
        .unwrap_or(remaining.len());
    String::from_utf8_lossy(&remaining[..end]).into_owned()
}

// ---------------------------------------------------------------------------
// statmount(2) / listmount(2) path
// ---------------------------------------------------------------------------

#[cfg(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
))]
fn listmount_ids() -> Option<Vec<u64>> {
    let mut all_ids = Vec::new();
    let mut last_id: u64 = 0;

    loop {
        let req = MntIdReq {
            size: MNT_ID_REQ_SIZE_VER0,
            spare: 0,
            mnt_id: LSMT_ROOT,
            param: last_id,
        };
        let mut ids = [0u64; 1024];

        // SAFETY: `req` and `ids` are valid stack allocations with correct sizes.
        // The kernel writes mount IDs into `ids` and returns the count.
        let ret = unsafe {
            libc::syscall(
                SYS_LISTMOUNT,
                &req as *const MntIdReq,
                ids.as_mut_ptr(),
                ids.len(),
                0u32,
            )
        };

        if ret < 0 {
            let errno = unsafe { *libc::__errno_location() };
            warn!("listmount(2) failed: errno={errno}");
            return None;
        }

        let count = ret as usize;
        if count == 0 {
            break;
        }

        all_ids.extend_from_slice(&ids[..count]);

        if count < ids.len() {
            break; // no more mounts
        }

        // Paginate: set cursor to the last returned ID.
        last_id = ids[count - 1];
    }

    Some(all_ids)
}

#[cfg(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
))]
fn statmount_entry(mnt_id: u64) -> Option<MountEntry> {
    let mask = STATMOUNT_SB_BASIC
        | STATMOUNT_MNT_BASIC
        | STATMOUNT_MNT_ROOT
        | STATMOUNT_MNT_POINT
        | STATMOUNT_FS_TYPE
        | STATMOUNT_MNT_OPTS
        | STATMOUNT_SB_SOURCE; // safe to request even if unsupported

    let req = MntIdReq {
        size: MNT_ID_REQ_SIZE_VER0,
        spare: 0,
        mnt_id,
        param: mask,
    };

    // 4 KB is sufficient for most mounts (512 byte header + strings).
    let mut buf = vec![0u8; 4096];

    // SAFETY: `req` is a valid stack allocation. `buf` is a properly-sized
    // mutable buffer. The kernel fills `buf` with the statmount struct + strings.
    let ret = unsafe {
        libc::syscall(
            SYS_STATMOUNT,
            &req as *const MntIdReq,
            buf.as_mut_ptr(),
            buf.len(),
            0u32,
        )
    };

    if ret < 0 {
        let errno = unsafe { *libc::__errno_location() };
        if errno == libc::EOVERFLOW {
            // Buffer too small  --  the kernel wrote the needed size into buf[0..4].
            let needed = read_u32(&buf, OFF_SIZE) as usize;
            if needed > 0 && needed <= 1 << 20 {
                buf.resize(needed, 0);
                let ret2 = unsafe {
                    libc::syscall(
                        SYS_STATMOUNT,
                        &req as *const MntIdReq,
                        buf.as_mut_ptr(),
                        buf.len(),
                        0u32,
                    )
                };
                if ret2 < 0 {
                    return None;
                }
            } else {
                return None;
            }
        } else {
            // Mount may have disappeared between listmount and statmount.
            return None;
        }
    }

    if buf.len() < OFF_STR {
        return None;
    }

    let filled = read_u64(&buf, OFF_MASK);

    // Device IDs.
    let dev_major = if filled & STATMOUNT_SB_BASIC != 0 {
        read_u32(&buf, OFF_SB_DEV_MAJOR)
    } else {
        0
    };
    let dev_minor = if filled & STATMOUNT_SB_BASIC != 0 {
        read_u32(&buf, OFF_SB_DEV_MINOR)
    } else {
        0
    };

    // Use old-style mount IDs for compatibility with /proc/self/mountinfo field 0.
    let mount_id = if filled & STATMOUNT_MNT_BASIC != 0 {
        read_u32(&buf, OFF_MNT_ID_OLD) as u64
    } else {
        0
    };
    let parent_id = if filled & STATMOUNT_MNT_BASIC != 0 {
        read_u32(&buf, OFF_MNT_PARENT_ID_OLD) as u64
    } else {
        0
    };

    // Strings.
    let root = if filled & STATMOUNT_MNT_ROOT != 0 {
        read_statmount_str(&buf, read_u32(&buf, OFF_MNT_ROOT_STR))
    } else {
        String::new()
    };
    let mount_point = if filled & STATMOUNT_MNT_POINT != 0 {
        read_statmount_str(&buf, read_u32(&buf, OFF_MNT_POINT_STR))
    } else {
        String::new()
    };
    let fs_type = if filled & STATMOUNT_FS_TYPE != 0 {
        read_statmount_str(&buf, read_u32(&buf, OFF_FS_TYPE_STR))
    } else {
        String::new()
    };

    // mnt_opts contains filesystem-specific options via the fs's show_options().
    // For NFS this includes vers=4.2,addr=...; for XFS it includes inode64, etc.
    // This maps to mountinfo's "super_options" (after the ` - ` separator).
    let mnt_opts = if filled & STATMOUNT_MNT_OPTS != 0 {
        read_statmount_str(&buf, read_u32(&buf, OFF_MNT_OPTS_STR))
    } else {
        String::new()
    };

    // sb_source: only filled on kernels that define STATMOUNT_SB_SOURCE (>= 6.13).
    // On older kernels the mask bit is silently ignored; the offset falls inside
    // __spare2 (zeroed), so we'd read an empty string  --  but we check the mask
    // anyway for clarity.
    let source = if filled & STATMOUNT_SB_SOURCE != 0 {
        read_statmount_str(&buf, read_u32(&buf, OFF_SB_SOURCE_STR))
    } else {
        String::new()
    };

    Some(MountEntry {
        mount_id,
        parent_id,
        dev_major,
        dev_minor,
        root,
        mount_point,
        mount_options: String::new(), // enriched from proc when needed
        fs_type,
        source,
        super_options: mnt_opts, // statmount mnt_opts ~= mountinfo super_options
    })
}

#[cfg(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
))]
fn enrich_from_proc(entries: &mut [MountEntry]) {
    let proc_entries = list_mounts_proc();
    let proc_map: HashMap<u64, &MountEntry> = proc_entries
        .iter()
        .map(|e| (e.mount_id, e))
        .collect();

    for entry in entries.iter_mut() {
        if let Some(pe) = proc_map.get(&entry.mount_id) {
            if entry.source.is_empty() {
                entry.source.clone_from(&pe.source);
            }
            if entry.mount_options.is_empty() {
                entry.mount_options.clone_from(&pe.mount_options);
            }
            if entry.super_options.is_empty() {
                entry.super_options.clone_from(&pe.super_options);
            }
        }
    }
}

#[cfg(any(
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "s390x",
    target_arch = "powerpc64"
))]
fn list_mounts_statmount() -> Option<Vec<MountEntry>> {
    let ids = listmount_ids()?;
    let mut entries = Vec::with_capacity(ids.len());

    for id in ids {
        if let Some(entry) = statmount_entry(id) {
            entries.push(entry);
        }
    }

    // Enrich with /proc/self/mountinfo for fields statmount could not fill.
    let needs_enrichment = entries
        .iter()
        .any(|e| e.source.is_empty() || e.mount_options.is_empty());
    if needs_enrichment {
        enrich_from_proc(&mut entries);
    }

    Some(entries)
}

// ---------------------------------------------------------------------------
// /proc/self/mountinfo fallback
// ---------------------------------------------------------------------------

/// Parse `/proc/self/mountinfo` into [`MountEntry`] values.
pub fn list_mounts_proc() -> Vec<MountEntry> {
    parse_mountinfo_text(
        &std::fs::read_to_string("/proc/self/mountinfo").unwrap_or_default(),
    )
}

/// Parse mountinfo-formatted text into [`MountEntry`] values.
///
/// Format per line:
/// ```text
/// mnt_id parent_id major:minor root mount_point options optional_fields - fs_type source super_options
/// ```
fn parse_mountinfo_text(text: &str) -> Vec<MountEntry> {
    let mut entries = Vec::new();

    for line in text.lines() {
        let fields: Vec<&str> = line.split_whitespace().collect();
        if fields.len() < 10 {
            continue;
        }

        let mount_id: u64 = match fields[0].parse() {
            Ok(v) => v,
            Err(_) => continue,
        };
        let parent_id: u64 = match fields[1].parse() {
            Ok(v) => v,
            Err(_) => continue,
        };

        // Parse major:minor.
        let (dev_major, dev_minor) = match fields[2].split_once(':') {
            Some((maj, min)) => match (maj.parse::<u32>(), min.parse::<u32>()) {
                (Ok(ma), Ok(mi)) => (ma, mi),
                _ => continue,
            },
            None => continue,
        };

        let root = fields[3].to_string();
        let mount_point = fields[4].to_string();
        let mount_options = fields[5].to_string();

        // Find the " - " separator (may be preceded by optional tagged fields).
        let sep_pos = match fields.iter().position(|&f| f == "-") {
            Some(p) => p,
            None => continue,
        };
        if sep_pos + 3 > fields.len() {
            continue;
        }

        let fs_type = fields[sep_pos + 1].to_string();
        let source = fields[sep_pos + 2].to_string();
        let super_options = if sep_pos + 3 < fields.len() {
            fields[sep_pos + 3].to_string()
        } else {
            String::new()
        };

        entries.push(MountEntry {
            mount_id,
            parent_id,
            dev_major,
            dev_minor,
            root,
            mount_point,
            mount_options,
            fs_type,
            source,
            super_options,
        });
    }

    entries
}

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

/// Enumerate all mounts visible to the current process.
///
/// Uses `statmount(2)` / `listmount(2)` on Linux >= 6.8 for direct kernel
/// queries, falling back to `/proc/self/mountinfo` parsing on older kernels.
pub fn list_mounts() -> Vec<MountEntry> {
    #[cfg(any(
        target_arch = "x86_64",
        target_arch = "aarch64",
        target_arch = "s390x",
        target_arch = "powerpc64"
    ))]
    if probe_statmount() {
        if let Some(entries) = list_mounts_statmount() {
            return entries;
        }
        warn!("statmount enumeration failed  --  falling back to /proc/self/mountinfo");
    }
    list_mounts_proc()
}

/// Find the mount entry whose `mount_point` is the longest prefix of `path`.
///
/// This is the common "find covering mount" operation used by all four existing
/// mountinfo parsers.
pub fn find_mount_for_path(path: &std::path::Path) -> Option<MountEntry> {
    let canonical = path.canonicalize().ok()?;
    let canonical_str = canonical.to_string_lossy();
    let entries = list_mounts();

    entries
        .into_iter()
        .filter(|e| canonical_str.starts_with(&e.mount_point) || e.mount_point == "/")
        .max_by_key(|e| {
            if e.mount_point == "/" {
                0
            } else {
                e.mount_point.len()
            }
        })
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;

    #[test]
    fn test_probe_statmount_does_not_panic() {
        let available = probe_statmount();
        println!("statmount(2) available: {available}");
    }

    #[test]
    fn test_list_mounts_returns_entries() {
        let entries = list_mounts();
        assert!(
            !entries.is_empty(),
            "list_mounts() should return at least one mount"
        );

        // Root filesystem must always be present.
        let has_root = entries.iter().any(|e| e.mount_point == "/");
        assert!(has_root, "root mount (/) must be present");

        // All entries should have non-empty mount_point and fs_type.
        for e in &entries {
            assert!(!e.mount_point.is_empty(), "mount_point empty: {e:?}");
            assert!(!e.fs_type.is_empty(), "fs_type empty: {e:?}");
        }

        println!("list_mounts() returned {} entries", entries.len());
    }

    #[test]
    fn test_list_mounts_proc_returns_entries() {
        let entries = list_mounts_proc();
        assert!(
            !entries.is_empty(),
            "proc fallback should return entries"
        );
        assert!(entries.iter().any(|e| e.mount_point == "/"));
    }

    #[test]
    fn test_statmount_vs_proc_field_counts() {
        // Compare entry counts between statmount and proc paths.
        let proc_entries = list_mounts_proc();
        let proc_count = proc_entries.len();

        if probe_statmount() {
            if let Some(sm_entries) = list_mounts_statmount() {
                let sm_count = sm_entries.len();
                println!(
                    "statmount: {sm_count} entries, /proc/self/mountinfo: {proc_count} entries"
                );
                // Allow minor differences (kernel internal mounts may appear/disappear).
                let diff = (sm_count as i64 - proc_count as i64).unsigned_abs();
                assert!(
                    diff <= 5,
                    "statmount ({sm_count}) vs proc ({proc_count}) differ by more than 5"
                );
            } else {
                println!("statmount probe succeeded but enumeration failed  --  skipping comparison");
            }
        } else {
            println!("statmount not available  --  skipping comparison test");
        }
    }

    #[test]
    fn test_parse_mountinfo_text() {
        let text = "\
22 1 8:1 / / rw,relatime shared:1 - ext4 /dev/sda1 rw,errors=continue
29 22 0:25 / /sys rw,nosuid,nodev,noexec,relatime shared:7 - sysfs sysfs rw
30 22 0:5 / /dev rw,nosuid shared:2 - devtmpfs devtmpfs rw,size=4096k
100 22 0:50 / /mnt/nfs rw,relatime shared:50 - nfs4 server:/export rw,vers=4.2,addr=10.0.0.1
";
        let entries = parse_mountinfo_text(text);
        assert_eq!(entries.len(), 4);

        assert_eq!(entries[0].mount_id, 22);
        assert_eq!(entries[0].parent_id, 1);
        assert_eq!(entries[0].dev_major, 8);
        assert_eq!(entries[0].dev_minor, 1);
        assert_eq!(entries[0].root, "/");
        assert_eq!(entries[0].mount_point, "/");
        assert_eq!(entries[0].mount_options, "rw,relatime");
        assert_eq!(entries[0].fs_type, "ext4");
        assert_eq!(entries[0].source, "/dev/sda1");
        assert_eq!(entries[0].super_options, "rw,errors=continue");

        // NFS entry.
        assert_eq!(entries[3].fs_type, "nfs4");
        assert_eq!(entries[3].source, "server:/export");
        assert!(entries[3].super_options.contains("vers=4.2"));
    }

    #[test]
    fn test_find_mount_for_path() {
        let entry = find_mount_for_path(std::path::Path::new("/"));
        assert!(entry.is_some(), "should find mount for /");
        assert_eq!(entry.unwrap().mount_point, "/");
    }
}