libnotcurses_sys/

file.rs

//! Wrapper for `libc::FILE`, both as used by notcurses and the libc crate
//!
//! The interface is largely based on the implementation of the
//! [cfile-rs crate](https://github.com/jkarns275/cfile) by Joshua Karns

use core::ptr::{null_mut, NonNull};
use std::io::{Error, ErrorKind, Read, Seek, SeekFrom};

use libc::{
    c_long, c_void, fclose, /* feof, */ fread, fseek, ftell, SEEK_CUR, SEEK_END, SEEK_SET,
};

// A utility function to pull the current value of errno and put it into an
// Error::Errno
fn get_error<T>() -> Result<T, Error> {
    Err(Error::last_os_error())
}

// See [`NcFile`]. Notcurses functions expects this type of `*FILE` (a struct)
#[allow(clippy::upper_case_acronyms)]
type NcFile_nc = crate::c_api::ffi::FILE;

// See [`NcFile`]. The [`libc`](https://docs.rs/libc/) crate expects this type
// of `*FILE` (an opaque enum)
#[allow(clippy::upper_case_acronyms)]
type NcFile_libc = libc::FILE;

/// A wrapper struct around
/// [`libc::FILE`](https://docs.rs/libc/0.2.80/libc/enum.FILE.html)
///
/// The `notcurses`' [`FILE`][crate::c_api::ffi::FILE] type is a transparent
/// struct, while the equivalent `libc`'s [`FILE`][libc::FILE] is an opaque enum.
///
/// Several methods are provided to cast back and forth between both types,
/// in order to allow both rust libc operations and notcurses file operations
/// over the same underlying `*FILE`.
#[derive(Debug)]
pub struct NcFile {
    file_ptr: NonNull<NcFile_libc>,
}

/// # Constants
impl NcFile {
    // TODO: the following static strings aren't made public

    /// Intended to be passed into the CFile::open method.
    /// It will open the file in a way that will allow reading and writing,
    /// including overwriting old data.
    /// It will not create the file if it does not exist.
    pub const RANDOM_ACCESS_MODE: &'static str = "rb+";

    /// Intended to be passed into the CFile::open method.
    /// It will open the file in a way that will allow reading and writing,
    /// including overwriting old data
    pub const UPDATE: &'static str = "rb+";

    /// Intended to be passed into the CFile::open method.
    /// It will only allow reading.
    pub const READ_ONLY: &'static str = "r";

    /// Intended to be passed into the CFile::open method.
    /// It will only allow writing.
    pub const WRITE_ONLY: &'static str = "w";

    /// Intended to be passed into the CFile::open method.
    /// It will only allow data to be appended to the end of the file.
    pub const APPEND_ONLY: &'static str = "a";

    /// Intended to be passed into the CFile::open method.
    /// It will allow data to be appended to the end of the file, and data to be
    /// read from the file. It will create the file if it doesn't exist.
    pub const APPEND_READ: &'static str = "a+";

    /// Intended to be passed into the CFile::open method.
    /// It will open the file in a way that will allow reading and writing,
    /// including overwriting old data. It will create the file if it doesn't exist
    pub const TRUNCATE_RANDOM_ACCESS_MODE: &'static str = "wb+";
}

/// # Constructors
impl NcFile {
    /// `NcFile` constructor from a file produced by notcurses.
    pub unsafe fn from_nc(file: *mut NcFile_nc) -> Self {
        NcFile { file_ptr: unsafe { NonNull::new_unchecked(NcFile::nc2libc(file)) } }
    }

    /// `NcFile` constructor from a file produced by the libc crate.
    #[allow(clippy::missing_safety_doc)]
    pub unsafe fn from_libc(file: *mut NcFile_libc) -> Self {
        NcFile { file_ptr: NonNull::new_unchecked(file) }
    }
}

/// # Methods
impl NcFile {
    /// Returns the file pointer in the format expected by the [`libc`] crate.
    #[inline]
    pub fn as_libc_ptr(&self) -> *mut NcFile_libc {
        self.file_ptr.as_ptr()
    }

    /// Returns the file pointer in the format expected by notcurses.
    #[inline]
    pub fn as_nc_ptr(&self) -> *mut NcFile_nc {
        Self::libc2nc(self.file_ptr.as_ptr())
    }

    /// Returns the current position in the file.
    ///
    /// On error `Error::Errno(errno)` is returned.
    pub fn current_pos(&self) -> Result<u64, Error> {
        unsafe {
            let pos = ftell(self.as_libc_ptr());
            if pos != -1 {
                Ok(pos as u64)
            } else {
                get_error()
            }
        }
    }

    /// Reads the file from start to end. Convenience method.
    ///
    #[inline]
    pub fn read_all(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error> {
        let _ = self.seek(SeekFrom::Start(0));
        self.read_to_end(buf)
    }

    // private methods:

    /// Converts a file pointer from the struct notcurses uses to the
    /// opaque enum type libc expects.
    #[inline]
    fn nc2libc(file: *mut NcFile_nc) -> *mut NcFile_libc {
        file as *mut _ as *mut NcFile_libc
    }

    /// Converts a file pointer from the libc opaque enum format to the struct
    /// expected by notcurses.
    #[inline]
    fn libc2nc(file: *mut NcFile_libc) -> *mut NcFile_nc {
        file as *mut _ as *mut NcFile_nc
    }

    /// A utility function to expand a vector without increasing its capacity
    /// more than it needs to be expanded.
    fn expand_buffer(buff: &mut Vec<u8>, by: usize) {
        if buff.capacity() < buff.len() + by {
            buff.reserve(by);
        }
        for _ in 0..by {
            buff.push(0u8);
        }
    }
}

impl Read for NcFile {
    /// Reads exactly the number of bytes required to fill buf.
    ///
    /// If the end of the file is reached before buf is filled,
    /// `Err(EndOfFile(bytes_read))` will be returned.  The data that was read
    /// before that will still have been placed into buf.
    ///
    /// Upon some other error, `Err(Errno(errno))` will be returned.
    fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
        unsafe {
            let result = fread(
                buf.as_ptr() as *mut c_void,
                1,
                buf.len(),
                self.as_libc_ptr(),
            );
            if result != buf.len() {
                match get_error::<u8>() {
                    Err(err) => {
                        if err.kind() == ErrorKind::UnexpectedEof {
                            Ok(result)
                        } else {
                            Err(err)
                        }
                    }
                    Ok(_) => panic!("This is impossible"),
                }
            } else {
                Ok(result)
            }
        }
    }

    /// Reads the entire file starting from the current_position
    /// expanding buf as needed.
    ///
    /// On a successful read, this function will return `Ok(bytes_read)`.
    ///
    /// If an error occurs during reading, some varient of error will be returned.
    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error> {
        let pos = self.current_pos();
        let _ = self.seek(SeekFrom::End(0));
        let end = self.current_pos();
        match pos {
            Ok(cur_pos) => match end {
                Ok(end_pos) => {
                    if end_pos == cur_pos {
                        return Ok(0);
                    }
                    let to_read = (end_pos - cur_pos) as usize;
                    if buf.len() < to_read {
                        let to_reserve = to_read - buf.len();
                        Self::expand_buffer(buf, to_reserve);
                    }
                    let _ = self.seek(SeekFrom::Start(cur_pos));
                    match self.read_exact(buf) {
                        Ok(()) => Ok(to_read),
                        Err(e) => Err(e),
                    }
                }
                Err(e) => Err(e),
            },
            Err(e) => Err(e),
        }
    }

    /// Reads the entire file from the beginning and stores it in a string.
    ///
    /// On a successful read, this function will return `Ok(bytes_read)`.
    ///
    /// If an error occurs during reading, some varient of error will be returned.
    fn read_to_string(&mut self, strbuf: &mut String) -> Result<usize, Error> {
        let mut buffer = vec![0u8];

        let bytes_read = self.read_all(&mut buffer)?;

        let result = std::str::from_utf8(&buffer);

        if let Ok(strslice) = result {
            *strbuf = strslice.to_string();
            Ok(bytes_read)
        } else {
            get_error()
        }
    }

    /// Reads exactly the number of bytes required to fill buf.
    ///
    /// If the end of the file is reached before buf is filled,
    /// `Err(EndOfFile(bytes_read))` will be returned. The data that was read
    /// before that will still have been placed into buf.
    ///
    /// Upon some other error, `Err(Errno(errno))` will be returned.
    fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error> {
        unsafe {
            let result = fread(
                buf.as_ptr() as *mut c_void,
                1,
                buf.len(),
                self.as_libc_ptr(),
            );
            if result == buf.len() {
                Ok(())
            } else {
                // Check if we hit the end of the file
                // FIXME
                // if feof(self.as_libc_ptr()) != 0 {
                //     get_error()
                // } else {
                //     get_error()
                // }
                get_error()
            }
        }
    }
}

impl Seek for NcFile {
    /// Changes the current position in the file using the [`SeekFrom`] enum.
    ///
    /// To set relative to the beginning of the file (i.e. index is 0 + offset):
    /// ```ignore
    /// SeekFrom::Start(offset)
    /// ```
    /// To set relative to the end of the file (i.e. index is file_lenth - 1 - offset):
    /// ```ignore
    /// SeekFrom::End(offset)
    /// ```
    /// To set relative to the current position:
    /// ```ignore
    /// SeekFrom::End(offset)
    /// ```
    ///
    /// On error `Error::Errno(errno)` is returned.
    fn seek(&mut self, pos: SeekFrom) -> Result<u64, Error> {
        unsafe {
            let result = match pos {
                SeekFrom::Start(from) => fseek(self.as_libc_ptr(), from as c_long, SEEK_SET),
                SeekFrom::End(from) => fseek(self.as_libc_ptr(), from as c_long, SEEK_END),
                SeekFrom::Current(delta) => fseek(self.as_libc_ptr(), delta as c_long, SEEK_CUR),
            };
            if result == 0 {
                self.current_pos()
            } else {
                get_error()
            }
        }
    }
}

impl Drop for NcFile {
    /// Ensures the file stream is closed before abandoning the data.
    fn drop(&mut self) {
        let _ = unsafe {
            if !(self.as_libc_ptr()).is_null() {
                let res = fclose(self.as_libc_ptr());
                if res == 0 {
                    self.file_ptr = NonNull::new_unchecked(null_mut::<NcFile_libc>());
                    Ok(())
                } else {
                    get_error()
                }
            } else {
                Ok(())
            }
        };
    }
}