luff_sys/

lib.rs

//! Low-level system primitives for luff
//!
//! This crate isolates all `unsafe` usage and platform-specific FFI calls.
//! It provides safe abstractions for file descriptor manipulation.

#![deny(unsafe_op_in_unsafe_fn)]
#![deny(clippy::all)]

use std::fs::File;
use std::io;

/// Re-export libc constants needed by the main crate.
/// This allows the main crate to avoid a direct dependency on libc.
#[cfg(unix)]
pub mod constants {
    pub use libc::{ELOOP, O_NOFOLLOW, O_NONBLOCK};
}

/// Drop the `O_NONBLOCK` flag from an open file
///
/// This function takes **ownership** of the `File` to ensure that no other references
/// to this specific file handle exist within the current scope while the flags are
/// being modified. This mitigates race conditions where other threads might be
/// attempting to read/write to the file or modify its flags concurrently via the
/// same handle.
///
/// # Platform Behavior
///
/// - **Unix**: Uses `fcntl` to clear `O_NONBLOCK`.
/// - **Windows**: No-op (Windows file handles do not use `O_NONBLOCK` in the same way).
///
/// # Errors
///
/// Returns an error if the underlying syscall fails.
#[cfg(unix)]
pub fn drop_nonblock(file: File) -> io::Result<File> {
    use std::os::unix::io::AsRawFd;

    let fd = file.as_raw_fd();

    // SAFETY:
    // 1. **FD Validity**: We hold an owned `File` instance. Rust's `File` guarantees
    //    that the underlying file descriptor (`fd`) is valid and open for the lifetime
    //    of the struct. Since we own the struct, the FD cannot be closed underneath us.
    //
    // 2. **Memory Safety**: `libc::fcntl` is a variadic C function. We are using the
    //    `F_GETFL` (void) and `F_SETFL` (int) commands. These operate strictly on
    //    integers (flags). We are not passing pointers, buffers, or complex structures,
    //    so there is no risk of memory corruption, buffer overflows, or lifetime issues
    //    associated with pointer dereferencing.
    //
    // 3. **Concurrency & Race Conditions**:
    //    Modifying file flags is a Read-Modify-Write (RMW) operation in user space:
    //    `flags = fcntl(GET); fcntl(SET, flags & ~NONBLOCK)`.
    //    This is *not* atomic. If another thread shares this specific Open File Description
    //    (OFD) and modifies flags (e.g. `O_APPEND`) concurrently, we could overwrite
    //    their changes.
    //
    //    *Mitigation*: We require passing `file` by value (ownership). This guarantees
    //    that the caller has given up their reference to the `File`. While it is
    //    technically possible for the FD to have been duplicated (`dup`) externally
    //    before calling this, within the context of `luff`'s usage (immediately after open),
    //    this effectively guarantees exclusive access during this operation.
    unsafe {
        // Step 1: Get current flags
        let flags = libc::fcntl(fd, libc::F_GETFL);
        if flags < 0 {
            return Err(io::Error::last_os_error());
        }

        // Step 2: Check if modification is needed
        if flags & libc::O_NONBLOCK != 0 {
            // Step 3: Clear O_NONBLOCK, preserving all other flags (e.g. O_APPEND)
            let new_flags = flags & !libc::O_NONBLOCK;
            if libc::fcntl(fd, libc::F_SETFL, new_flags) < 0 {
                return Err(io::Error::last_os_error());
            }
        }
    }

    Ok(file)
}

/// Drop the `O_NONBLOCK` flag (Windows/Non-Unix fallback)
///
/// On Windows, `O_NONBLOCK` semantics for file opens are not applicable in the same
/// way as Unix. This function simply returns the file ownership back to the caller.
#[cfg(not(unix))]
pub fn drop_nonblock(file: File) -> io::Result<File> {
    Ok(file)
}

/// Get the device and inode for a file descriptor
///
/// This provides a direct way to identify a file from its open file descriptor,
/// which is essential for accurately identifying `stdout` when it is redirected
/// to a file.
///
/// # Implementation Note
///
/// This uses `std::fs::File::from_raw_fd` wrapped in `ManuallyDrop` to leverage
/// the standard library's `Metadata` implementation. This ensures that the
/// `dev` and `ino` values returned here exactly match those returned by
/// `std::fs::metadata` (which is used by the directory walker), avoiding
/// potential mismatches due to platform-specific `stat` struct layouts or
/// type casting differences.
///
/// # Arguments
///
/// * `fd` - A borrowed file descriptor to inspect. `BorrowedFd` guarantees the
///   descriptor is valid and open for the duration of the borrow, making this
///   function safe to call without requiring `unsafe` at the call site.
///
/// # Returns
///
/// A tuple containing `(device_id, inode_number)` on success.
///
/// # Errors
///
/// Returns an `io::Error` if the underlying `fstat` syscall fails.
#[cfg(unix)]
pub fn get_fd_identity(fd: std::os::unix::io::BorrowedFd<'_>) -> io::Result<(u64, u64)> {
    use std::mem::ManuallyDrop;
    use std::os::unix::fs::MetadataExt;
    use std::os::unix::io::{AsRawFd, FromRawFd};

    let raw_fd = fd.as_raw_fd();

    // SAFETY:
    // 1. `BorrowedFd<'_>` guarantees the file descriptor is valid and open for
    //    the lifetime of the borrow. The caller cannot close it while we hold it.
    // 2. We wrap the `File` in `ManuallyDrop` to prevent the destructor from
    //    running, ensuring the FD remains open after this function returns.
    //    Ownership semantics are preserved — we never actually take ownership.
    // 3. We only call `metadata()`, which is a read-only `fstat` syscall.
    //    It does not modify the file state or position.
    let metadata = unsafe {
        let file = File::from_raw_fd(raw_fd);
        let file = ManuallyDrop::new(file);
        file.metadata()?
    };

    Ok((metadata.dev(), metadata.ino()))
}

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

    #[test]
    fn test_drop_nonblock_regular_file() {
        let temp = TempDir::new().unwrap();
        let path = temp.path().join("test.txt");
        std::fs::write(&path, "content").unwrap();

        let file = File::open(&path).unwrap();

        // Should succeed and return the file
        let result = drop_nonblock(file);
        assert!(result.is_ok());

        // Verify file is still usable
        let file = result.unwrap();
        let meta = file.metadata().unwrap();
        assert!(meta.is_file());
    }

    #[cfg(unix)]
    #[test]
    fn test_get_fd_identity() {
        use std::os::unix::fs::MetadataExt;
        use std::os::unix::io::AsFd;

        let temp = TempDir::new().unwrap();
        let path = temp.path().join("identity.txt");
        std::fs::write(&path, "content").unwrap();

        let file = File::open(&path).unwrap();
        let meta = file.metadata().unwrap();

        let (dev, ino) = get_fd_identity(file.as_fd()).unwrap();

        assert_eq!(dev, meta.dev());
        assert_eq!(ino, meta.ino());
    }
}