715: FFI Error Codes — Converting C Errors to Rust Result

// 715. C-style error code patterns in Rust FFI
//
// Demonstrates wrapping C integer-return-code conventions into
// idiomatic Result<T, E> at the FFI boundary.

use std::fmt;
use std::os::raw::{c_char, c_int};

// ── Error type ───────────────────────────────────────────────────────────────

/// Maps POSIX errno values to a typed Rust enum.
/// `#[repr(i32)]` ensures the discriminant fits a C int.
#[repr(i32)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PosixError {
    NotFound    = -2,   // ENOENT
    AccessDenied = -13, // EACCES
    AlreadyExists = -17, // EEXIST
    InvalidArg  = -22,  // EINVAL
    Unknown     = i32::MIN,
}

impl PosixError {
    /// Convert a raw negative C return value to a typed error.
    pub fn from_raw(code: c_int) -> Self {
        match code {
            -2  => Self::NotFound,
            -13 => Self::AccessDenied,
            -17 => Self::AlreadyExists,
            -22 => Self::InvalidArg,
            _   => Self::Unknown,
        }
    }
}

impl fmt::Display for PosixError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let msg = match self {
            Self::NotFound     => "No such file or directory (ENOENT)",
            Self::AccessDenied => "Permission denied (EACCES)",
            Self::AlreadyExists => "File exists (EEXIST)",
            Self::InvalidArg   => "Invalid argument (EINVAL)",
            Self::Unknown      => "Unknown error",
        };
        f.write_str(msg)
    }
}

impl std::error::Error for PosixError {}

// ── Mock C library ────────────────────────────────────────────────────────────
// In real code this block would be:
//   extern "C" { fn open(path: *const c_char, flags: c_int) -> c_int; }
//
// We stub it here so the example compiles without a C toolchain.

mod mock_libc {
    use std::os::raw::c_int;

    /// Simulates a C function: returns >=0 on success, negative on error.
    /// Real signature: `unsafe extern "C" fn open(*const c_char, c_int) -> c_int`
    pub unsafe fn open(path_ptr: *const u8, _flags: c_int) -> c_int {
        // SAFETY: caller guarantees path_ptr is a valid, null-terminated C string.
        // We read only until we find a null byte, so no OOB access.
        let mut len = 0usize;
        while *path_ptr.add(len) != 0 {
            len += 1;
        }
        let path = std::str::from_utf8(std::slice::from_raw_parts(path_ptr, len))
            .unwrap_or("");

        if path.contains("missing") {
            -2  // ENOENT
        } else if path.contains("secret") {
            -13 // EACCES
        } else {
            3   // fake fd
        }
    }

    pub unsafe fn close(_fd: c_int) -> c_int {
        // SAFETY: caller guarantees fd is a valid open file descriptor.
        0 // success
    }
}

// ── Safe wrapper ──────────────────────────────────────────────────────────────

/// A safe file descriptor handle that closes on drop.
pub struct OwnedFd(c_int);

impl Drop for OwnedFd {
    fn drop(&mut self) {
        // SAFETY: self.0 was obtained from a successful open() call and
        // has not been closed yet (we own it exclusively).
        unsafe { mock_libc::close(self.0); }
    }
}

impl OwnedFd {
    pub fn raw(&self) -> c_int { self.0 }
}

/// Open a file, converting C error codes to `Result`.
pub fn open(path: &str) -> Result<OwnedFd, PosixError> {
    // Build a null-terminated byte string on the stack.
    let mut buf = [0u8; 256];
    let bytes = path.as_bytes();
    if bytes.len() >= buf.len() {
        return Err(PosixError::InvalidArg);
    }
    buf[..bytes.len()].copy_from_slice(bytes);
    // buf[bytes.len()] is already 0 (null terminator).

    // SAFETY: `buf` is a valid null-terminated byte array living on the stack.
    // We pass a pointer to it; the C function does not retain the pointer after
    // it returns, so there are no lifetime issues.
    let fd = unsafe { mock_libc::open(buf.as_ptr(), 0) };

    if fd >= 0 {
        Ok(OwnedFd(fd))
    } else {
        Err(PosixError::from_raw(fd))
    }
}

// ── Convenience: check-and-return pattern ─────────────────────────────────────

/// Helper used throughout the codebase: turn any negative C int into an error.
#[inline]
pub fn check(rc: c_int) -> Result<c_int, PosixError> {
    if rc >= 0 { Ok(rc) } else { Err(PosixError::from_raw(rc)) }
}

// ── main ──────────────────────────────────────────────────────────────────────

fn main() {
    let paths = &["normal_file.txt", "missing_file.txt", "secret_data.bin"];

    for path in paths {
        match open(path) {
            Ok(fd)  => println!("Opened '{}' → fd={}", path, fd.raw()),
            Err(e)  => println!("Failed '{}' → {}", path, e),
        }
    }

    // Demonstrate the `check()` helper with a raw C return value.
    let raw: c_int = -22; // pretend a C call returned EINVAL
    match check(raw) {
        Ok(v)  => println!("C call succeeded: {}", v),
        Err(e) => println!("C call failed: {}", e),
    }
}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn success_path() {
        let fd = open("normal_file.txt").expect("should open");
        assert!(fd.raw() >= 0);
    }

    #[test]
    fn enoent() {
        let err = open("missing_file.txt").unwrap_err();
        assert_eq!(err, PosixError::NotFound);
    }

    #[test]
    fn eacces() {
        let err = open("secret_data.bin").unwrap_err();
        assert_eq!(err, PosixError::AccessDenied);
    }

    #[test]
    fn check_helper_positive() {
        assert_eq!(check(0), Ok(0));
        assert_eq!(check(42), Ok(42));
    }

    #[test]
    fn check_helper_negative() {
        assert_eq!(check(-2), Err(PosixError::NotFound));
    }

    #[test]
    fn error_display() {
        assert!(PosixError::AccessDenied.to_string().contains("EACCES"));
    }
}