blob: d007361fa27c597acdb9c1e265a09e6a43b07983 [file] [edit]
// 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 crate::capi::{ret::IntoCReturn, utils};
use std::{mem, ptr};
use bytemuck::{Pod, TransparentWrapper, Zeroable};
use libc::c_int;
#[derive(Debug, Clone, Copy, TransparentWrapper)]
#[repr(transparent)]
pub struct CStringPtr {
ptr: *const u8,
}
// MSRV(1.88): Use #[derive(Default)].
impl Default for CStringPtr {
fn default() -> Self {
Self { ptr: ptr::null() }
}
}
impl From<&'static str> for CStringPtr {
fn from(s: &'static str) -> Self {
s.as_ptr().into()
}
}
impl From<*const u8> for CStringPtr {
fn from(ptr: *const u8) -> Self {
Self { ptr }
}
}
// SAFETY: This pointer (which must be &'static) is serialised as a u64, which
// is safe to represent and parse. The ban on pointers is mostly about
// semantics, see <https://github.com/Lokathor/bytemuck/discussions/346>.
unsafe impl Zeroable for CStringPtr {}
unsafe impl Pod for CStringPtr {}
/// Represents the version information of the runtime libpathrs library.
#[derive(Debug, Clone, Copy, Default, Pod, Zeroable)]
#[repr(C)]
pub struct VersionInfo {
/// Pointer to static version string containing the crate version.
/// cbindgen:rename-all="const char *"
version_string: CStringPtr,
}
const VERSION_STRING: &str = concat!(env!("CARGO_PKG_VERSION"), "\0");
impl VersionInfo {
pub(crate) fn new() -> Self {
Self {
version_string: VERSION_STRING.into(),
}
}
}
/// Return the version information of the libpathrs library at runtime.
///
/// This API is designed to be extensible. The caller must pass a pointer to a
/// contiguous buffer `dst` that is large enough to store `dst_size` bytes. This
/// buffer is then filled with version information. If the library has less data
/// than the given buffer size, the trailing bytes are zero-filled. If the
/// library has more data than the given buffer size the data is truncated and
/// (if the truncated data contained non-zero values), the return value
/// indicates what buffer size is needed to contain all version data.
///
/// # Return Value
///
/// On success, this function returns `0` or (if the version data was truncated)
/// a positive integer that is the size of the buffer needed to store all data.
///
/// 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_version(dst: *mut VersionInfo, dst_size: usize) -> c_int {
{
let v = VersionInfo::new();
// SAFETY: C caller guarantees buffer is at least dst_size and can be
// written to.
unsafe { utils::copy_into_extensible_struct(dst, dst_size, &v) }.map(|truncated| {
if truncated {
mem::size_of::<VersionInfo>() as isize
} else {
0isize // not truncated, return 0
}
})
}
.into_c_return()
}
utils::symver! {
fn pathrs_version <- (pathrs_version, version = "LIBPATHRS_0.2.5", default);
}
#[cfg(test)]
mod tests {
use super::*;
use std::{mem, ptr};
use bytemuck::TransparentWrapper;
use pretty_assertions::assert_eq;
#[test]
fn version() {
let mut info = VersionInfo::default();
let ret = unsafe { pathrs_version(&mut info as *mut _, mem::size_of::<VersionInfo>()) };
assert_eq!(
ret, 0,
"pathrs_version with sizeof(VersionInfo) should not indicate truncation",
);
assert_eq!(
TransparentWrapper::peel_ref(&info.version_string),
&VERSION_STRING.as_ptr(),
"pathrs_version should set info.version_string to VERSION_STRING pointer",
);
// TODO: Parse CString and compare to CARGO_PKG_VERSION?
}
#[test]
fn version_zerosize() {
let mut info = VersionInfo::default();
let ret = unsafe { pathrs_version(&mut info as *mut _, 0) };
assert_eq!(
ret,
mem::size_of::<VersionInfo>() as i32,
"pathrs_version with zero size should indicate truncation",
);
assert_eq!(
TransparentWrapper::peel_ref(&info.version_string),
&ptr::null(),
"pathrs_version should not modify info.version_string with zero size",
);
}
#[test]
fn version_null() {
let ret = unsafe { pathrs_version(ptr::null_mut(), 0) };
assert_eq!(
ret,
mem::size_of::<VersionInfo>() as i32,
"pathrs_version with NULL and zero size should indicate truncation",
);
}
}