blob: 0b1fbb09bc353ff034bdf5e9c168f91cb21a7706 [file]
// SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later
/*
* libpathrs: safe path resolution on Linux
* 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::{
cmp::{self, Ordering},
fmt,
};
use once_cell::sync::Lazy;
use rustix::system as rustix_system;
/// A representation of a Linux kernel version that can be mutually compared
/// against, usually to check if a kernel aught to have a particular feature.
///
/// Use [`parse_kernel_version`] to convert a kernel version string (such as
/// returned by `uname -r`) to a [`KernelVersion`].
///
/// # Comparisons #
///
/// Note that the system for comparing kernel versions is not very akin to
/// SemVer because Linux kernel versions can (in principle) have arbitrarily
/// many dot components. If both kernel versions have the same number of
/// components, then the comparison is done left-to-right per-component in a
/// manner identical to the way [`slice`]s are compared. If the kernel versions
/// have different numbers of components then the comparison is done as though
/// the shorter kernel version was right-padded with additional `0` components.
///
/// Thus, `3[.0.0] < 3.1[.0] < 3.1.18 < 4[.0.0]`.
#[derive(Clone, Debug)]
pub(crate) struct KernelVersion(pub(crate) Vec<u64>);
impl fmt::Display for KernelVersion {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(
f,
"linux-{}",
self.0
.iter()
.map(ToString::to_string)
.collect::<Vec<_>>()
.join(".")
)
}
}
impl Ord for KernelVersion {
fn cmp(&self, other: &Self) -> Ordering {
// In contrast to regular slices, when comparing kernel versions we
// effectively zero-extend the trailing part of the shorter kernel
// version specification (so 3.1.2 > 3.1[.0] > 3[.0.0]).
let common_len = cmp::min(self.0.len(), other.0.len());
match self.0[..common_len].cmp(&other.0[..common_len]) {
// We only need to deal with the annoying trailing end case if the
// common part is equal.
Ordering::Equal => match (
self.0[common_len..].iter().any(|&n| n > 0),
other.0[common_len..].iter().any(|&n| n > 0),
) {
(false, false) => Ordering::Equal, // all zeros or equal lengths
(true, false) => Ordering::Greater, // self tail > 0
(false, true) => Ordering::Less, // other tail > 0
(true, true) => unreachable!("both KernelVersion slices cannot have non-zero tails because one must be empty"),
},
cmp => cmp,
}
}
}
impl PartialOrd for KernelVersion {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
Some(self.cmp(other))
}
}
impl PartialEq for KernelVersion {
fn eq(&self, other: &Self) -> bool {
self.cmp(other) == Ordering::Equal
}
}
impl Eq for KernelVersion {}
/// Parse a kernel version string like `"4.10.23-1-default"` into a
/// [`KernelVersion`] that can be used for comparisons.
fn parse_kernel_version(kver_str: &str) -> Option<KernelVersion> {
// Strip off any of the non-version suffixes from the kver string.
let kver_str = &kver_str[..kver_str
.find(|ch: char| !ch.is_ascii_digit() && ch != '.')
.unwrap_or(kver_str.len())];
let kver = kver_str
.split('.')
.map(|num| match num {
"" => None, // version components must be non-empty
_ => num.parse().ok(), // version components must be valid numbers
})
.collect::<Option<Vec<_>>>()
.map(KernelVersion);
match kver {
// Versions must have >= 2 components (actually, in practice it's >= 3).
Some(KernelVersion(ref v)) if v.len() >= 2 => kver,
_ => None,
}
}
// MSRV(1.80): Use LazyLock.
pub(crate) static HOST_KERNEL_VERSION: Lazy<KernelVersion> = Lazy::new(host_kernel_version);
pub(crate) fn host_kernel_version() -> KernelVersion {
parse_kernel_version(&rustix_system::uname().release().to_string_lossy())
.expect("uname kernel release must be a valid KernelVersion string")
}
/// Returns the result of comparing the kernel version of the running system
/// against the specified kernel version using the specified comparator.
/// `is_kver!(>= 1,2,3)` is equivalent to `is_gte!(1, 2, 3)`.
macro_rules! is_kver {
($cmp:tt $($part:literal),+) => {
{
$(
const _: u64 = $part;
)+
// Some of our tests rely on using personality(2) to fake older
// (2.6-era) kernel versions, so we cannot use the cached kernel
// version when in test builds. However, to make sure that we still
// test that HOST_KERNEL_VERSION doesn't do anything silly (like
// crash) we still compute it in our tests.
let cached_host_kver = &*$crate::utils::kernel_version::HOST_KERNEL_VERSION;
#[cfg(test)]
let host_kver = &$crate::utils::kernel_version::host_kernel_version();
#[cfg(not(test))]
let host_kver = cached_host_kver;
#[cfg(test)]
eprintln!("cached host kernel is {cached_host_kver} but using {host_kver} for test");
let cmp_kver = &$crate::utils::kernel_version::KernelVersion(vec![$($part),+]);
host_kver $cmp cmp_kver
}
};
}
pub(crate) use is_kver;
/// Returns whether the kernel version of the running system is at least as new
/// as the kernel version specified. See the documentation of [`KernelVersion`]
/// for more information on how kernel versions are compared.
macro_rules! is_gte {
($($part:literal),+) => {
$crate::utils::kernel_version::is_kver!{>= $($part),*}
};
}
pub(crate) use is_gte;
/// Returns whether the kernel version of the running system is older than the
/// kernel version specified. See the documentation of [`KernelVersion`] for
/// more information on how kernel versions are compared.
macro_rules! is_lt {
($($part:literal),+) => {
$crate::utils::kernel_version::is_kver!{< $($part),*}
};
}
pub(crate) use is_lt;
#[cfg(test)]
mod tests {
use super::*;
use crate::syscalls;
use pretty_assertions::assert_eq;
macro_rules! kver {
($($part:literal),+) => {
KernelVersion(vec![$($part),+])
};
}
#[test]
fn parse_kernel_version_bad() {
assert_eq!(parse_kernel_version(""), None);
assert_eq!(parse_kernel_version("."), None);
assert_eq!(parse_kernel_version(".."), None);
assert_eq!(parse_kernel_version(".-foo"), None);
assert_eq!(parse_kernel_version("1..3"), None);
assert_eq!(parse_kernel_version("4...2"), None);
assert_eq!(parse_kernel_version("a.a.a"), None);
assert_eq!(parse_kernel_version("invalid"), None);
assert_eq!(parse_kernel_version("foo"), None);
assert_eq!(parse_kernel_version("foo.1.3.4"), None);
assert_eq!(parse_kernel_version("-1.2"), None);
assert_eq!(parse_kernel_version("+1.2"), None);
assert_eq!(parse_kernel_version("3a"), None);
assert_eq!(parse_kernel_version(".1"), None);
assert_eq!(parse_kernel_version(".1.2"), None);
assert_eq!(parse_kernel_version("3.foo"), None);
assert_eq!(parse_kernel_version("42.12."), None);
assert_eq!(parse_kernel_version("4.10.-default"), None);
assert_eq!(parse_kernel_version("4.10.-default"), None);
}
#[test]
fn parse_kernel_version_good() {
assert_eq!(parse_kernel_version("3.7"), Some(kver![3, 7]));
assert_eq!(parse_kernel_version("3.8"), Some(kver![3, 8]));
assert_eq!(parse_kernel_version("3.8.0"), Some(kver![3, 8, 0]));
assert_eq!(parse_kernel_version("3.8.12"), Some(kver![3, 8, 12]));
assert_eq!(
parse_kernel_version("3.8.12.10.0.2.5912"),
Some(kver![3, 8, 12, 10, 0, 2, 5912])
);
assert_eq!(
parse_kernel_version("42.12.1000"),
Some(kver![42, 12, 1000])
);
}
#[test]
fn parse_kernel_version_with_suffix() {
assert_eq!(
parse_kernel_version("2.6.16.48foobar"),
Some(kver![2, 6, 16, 48])
);
assert_eq!(parse_kernel_version("2.6.16f00b4r"), Some(kver![2, 6, 16]));
assert_eq!(
parse_kernel_version("2.6.16.13rc2"),
Some(kver![2, 6, 16, 13])
);
assert_eq!(
parse_kernel_version("2.6.16.13-rc2"),
Some(kver![2, 6, 16, 13])
);
assert_eq!(
parse_kernel_version("3.8.16-generic"),
Some(kver![3, 8, 16])
);
assert_eq!(
parse_kernel_version("6.12.49-1-default"),
Some(kver![6, 12, 49])
);
assert_eq!(
parse_kernel_version("4.9.27-default-foo.12.23"),
Some(kver![4, 9, 27])
);
assert_eq!(parse_kernel_version("5.15.0+debug"), Some(kver![5, 15, 0]));
assert_eq!(parse_kernel_version("6.1.0~beta1"), Some(kver![6, 1, 0]));
assert_eq!(
parse_kernel_version("5.4.0_custom.1.2"),
Some(kver![5, 4, 0])
);
assert_eq!(parse_kernel_version("3.8-4"), Some(kver![3, 8]));
}
#[test]
fn kernel_version_eq_same_length() {
assert!(kver![3, 8] == kver![3, 8], "3.8 == 3.8");
assert!(kver![3, 8, 12] == kver![3, 8, 12], "3.8.12 == 3.8.12");
assert!(kver![0, 0] == kver![0, 0], "0.0 == 0.0");
assert!(kver![6, 12, 49] == kver![6, 12, 49], "6.12.49 == 6.12.49");
}
#[test]
fn kernel_version_ne() {
assert!(kver![3, 8, 0] != kver![3, 8, 1], "3.8 != 3.8.1");
assert!(kver![3, 8, 12] != kver![4, 8, 12], "3.8.12 != 4.8.12");
assert!(
kver![6, 12, 49] != kver![6, 12, 49, 1],
"6.12.49 != 6.12.49.1"
);
}
#[test]
fn kernel_version_eq_trailing_zeros() {
// Trailing zeros should be treated as equal.
assert!(kver![3, 8] == kver![3, 8, 0], "3.8 == 3.8.0");
assert!(kver![3, 8] == kver![3, 8, 0, 0], "3.8 == 3.8.0.0");
assert!(kver![3, 8] == kver![3, 8, 0, 0, 0], "3.8 == 3.8.0.0.0");
assert!(kver![3, 8, 0] == kver![3, 8, 0, 0], "3.8.0 == 3.8.0.0");
assert!(kver![3, 8, 0] == kver![3, 8], "3.8.0 == 3.8");
assert!(kver![5, 0, 0, 0] == kver![5, 0], "5.0.0.0 == 5.0");
}
#[test]
fn kernel_version_lt_same_length() {
assert!(kver![3, 7] < kver![3, 8], "3.7 < 3.8");
assert!(kver![3, 8] < kver![4, 0], "3.8 < 4.0");
assert!(kver![3, 8, 11] < kver![3, 8, 12], "3.8.11 < 3.8.12");
assert!(kver![2, 6, 32] < kver![3, 0, 0], "2.6.32 < 3.0.0");
assert!(kver![5, 9, 99] < kver![5, 10, 0], "5.9.99 < 5.10.0");
}
#[test]
fn kernel_version_gt_same_length() {
assert!(kver![3, 8] > kver![3, 7], "3.8 > 3.7");
assert!(kver![4, 0] > kver![3, 8], "4.0 > 3.8");
assert!(kver![3, 8, 12] > kver![3, 8, 11], "3.8.12 > 3.8.11");
assert!(kver![6, 0, 0] > kver![5, 99, 99], "6.0.0 > 5.99.99");
}
#[test]
fn kernel_version_lt_different_length() {
// Shorter version is effectively zero-padded.
assert!(kver![3, 1] < kver![3, 1, 1], "3.1[.0] < 3.1.1");
assert!(kver![3, 1] < kver![3, 1, 18], "3.1[.0] < 3.1.18");
assert!(kver![3, 0] < kver![3, 0, 0, 1], "3.0[.0.0] < 3.0.0.1");
assert!(
kver![5, 4] < kver![5, 4, 0, 0, 1],
"5.4[.0.0.0] < 5.4.0.0.1"
);
}
#[test]
fn kernel_version_gt_different_length() {
assert!(kver![3, 1, 1] > kver![3, 1], "3.1.1 > 3.1[.0]");
assert!(kver![3, 1, 18] > kver![3, 1], "3.1.18 > 3.1[.0]");
assert!(kver![3, 0, 0, 1] > kver![3, 0], "3.0.0.1 > 3.0[.0.0]");
assert!(
kver![5, 4, 0, 0, 1] > kver![5, 4],
"5.4.0.0.1 > 5.4[.0.0.0]"
);
}
#[test]
fn kernel_version_ordering_chain() {
// Example from the doc comment.
assert!(kver![3, 0, 0] < kver![3, 1, 0], "3.0.0 < 3.1.0");
assert!(kver![3, 1, 0] < kver![3, 1, 18], "3.1.0 < 3.1.18");
assert!(kver![3, 1, 18] < kver![4, 0, 0], "3.1.18 < 4.0.0");
// Same example with implicit zeros.
assert!(kver![3] < kver![3, 1], "3[.0] < 3.1");
assert!(kver![3, 1] < kver![3, 1, 18], "3.1[.0] < 3.1.18");
assert!(kver![3, 1, 18] < kver![4, 0], "3.1.18 < 4.0[.0]");
}
#[test]
fn kernel_version_cmp_parsed() {
// Test comparison through parsed strings, like real kernel versions.
let v3_8 = parse_kernel_version("3.8.0-generic").expect("parse '3.8.0-generic'");
let v4_10 = parse_kernel_version("4.10.23-1-default").expect("parse '4.10.23-1-default'");
let v6_12 = parse_kernel_version("6.12.49-1-default").expect("parse '6.12.49-1-default'");
assert!(v3_8 < v4_10, "3.8.0 < 4.10.23");
assert!(v4_10 < v6_12, "4.10.23 < 6.12.49");
assert!(v3_8 < v6_12, "3.8.0 < 6.12.49");
// Parsed version with trailing zeros should equal shorter form.
let v5_4_0 = parse_kernel_version("5.4.0").expect("parse '5.4.0'");
let v5_4 = parse_kernel_version("5.4").expect("parse '5.4'");
assert!(v5_4_0 == v5_4, "5.4.0 == 5.4");
}
#[test]
fn kernel_version_gte() {
let v3_8 = parse_kernel_version("3.8.0-ubuntu.22.04").expect("parse '3.8.0-ubuntu.22.04");
assert!(kver![3, 8] >= v3_8, "3.8 >= 3.8.0-ubuntu.22.04");
assert!(kver![3, 8, 1] >= v3_8, "3.8.1 >= 3.8.0-ubuntu.22.04");
assert!(kver![3, 8, 0, 1] >= v3_8, "3.8.0.1 >= 3.8.0-ubuntu.22.04");
assert!(kver![4] >= v3_8, "4 >= 3.8.0-ubuntu.22.04");
assert!(kver![4, 0, 0, 0] >= v3_8, "4.0.0.0 >= 3.8.0-ubuntu.22.04");
assert!(kver![3, 7, 999] < v3_8, "3.7.999 < 3.8.0-ubuntu.22.04");
}
#[test]
fn kernel_version_display() {
assert_eq!("linux-2", kver![2].to_string(), "Linux 2");
assert_eq!(
"linux-2.6.32.182",
kver![2, 6, 32, 182].to_string(),
"Linux 2.6.32.182"
);
assert_eq!("linux-3.0", kver![3, 0].to_string(), "Linux 3.0");
assert_eq!(
"linux-4.1.18.2",
kver![4, 1, 18, 2].to_string(),
"Linux 4.1.18.2"
);
}
#[test]
fn host_kernel_version_uname26() {
// The UNAME26 personality lets us fake a pre-3.0 kernel version.
let _persona_guard = syscalls::scoped_personality(syscalls::PER_UNAME26);
let host_kver = host_kernel_version();
assert!(
kver![3, 0] > host_kver,
"UNAME26 personality should always result in a <3.0 kernel version: got {host_kver:?}"
);
assert!(
!is_gte!(3, 0),
"UNAME26 personality should always result in a <3.0 kernel version: is_gte!(3, 0) succeeded"
);
assert!(
is_lt!(3, 0),
"UNAME26 personality should always result in a <3.0 kernel version: is_lt!(3, 0) failed"
);
assert!(
is_kver!(!= 4, 0),
"UNAME26 personality should always result in a <3.0 kernel version: is_kver!(!= 4, 0) failed"
);
}
}