Support creating fitsfiles from raw pointers

fitsio/examples/reading_from_memory.rs

@@ -0,0 +1,52 @@
+// `fitsio` does not currently support opening files from memory, `cfitsio` _does_. This means we
+// can use `Fitsfile::from_raw` to load a `FitsFile` from a file that was opened via
+// `fits_open_memfile` in `cfitsio`.
+
+#[cfg(all(target_pointer_width = "64", target_os = "linux"))]
+use fitsio::{sys, FileOpenMode, FitsFile};
+#[cfg(all(target_pointer_width = "64", target_os = "linux"))]
+use std::io::Read;
+
+#[cfg(all(target_pointer_width = "64", target_os = "linux"))]
+fn main() {
+    // read the bytes into memory and return a pointer and length to the file
+    let (bytes, mut ptr_size) = {
+        let filename = "./testdata/full_example.fits";
+        let mut f = std::fs::File::open(filename).unwrap();
+        let mut bytes = Vec::new();
+        let num_bytes = f.read_to_end(&mut bytes).unwrap();
+
+        (bytes, num_bytes as u64)
+    };
+
+    let mut ptr = bytes.as_ptr();
+
+    // now we have a pointer to the data, let's open this in `fitsio_sys`
+    let mut fptr = std::ptr::null_mut();
+    let mut status = 0;
+
+    let c_filename = std::ffi::CString::new("full_example.fits").unwrap();
+    unsafe {
+        sys::ffomem(
+            &mut fptr as *mut *mut _,
+            c_filename.as_ptr(),
+            sys::READONLY as _,
+            &mut ptr as *const _ as *mut *mut libc::c_void,
+            &mut ptr_size as *mut u64,
+            0,
+            None,
+            &mut status,
+        );
+    }
+
+    if status != 0 {
+        unsafe { sys::ffrprt(sys::stderr, status) };
+        panic!("bad status");
+    }
+
+    let mut f = unsafe { FitsFile::from_raw(fptr, FileOpenMode::READONLY) }.unwrap();
+    f.pretty_print().expect("pretty printing fits file");
+}
+
+#[cfg(not(all(target_pointer_width = "64", target_os = "linux")))]
+fn main() {}

fitsio/src/errors.rs

@@ -42,6 +42,9 @@ pub enum Error {
 
     /// Error unlocking a mutex
     UnlockError,
+
+    /// Null pointer error
+    NullPointer,
 }
 
 /// Error raised when the user requests invalid indexes for data
@@ -136,6 +139,7 @@ impl ::std::fmt::Display for Error {
             Error::IntoString(ref e) => e.fmt(f),
             Error::ExistingFile(ref filename) => write!(f, "File {} already exists", filename),
             Error::UnlockError => write!(f, "Invalid concurrent access to fits file"),
+            Error::NullPointer => write!(f, "Null pointer specified"),
         }
     }
 }

fitsio/src/fitsfile.rs

@@ -22,8 +22,7 @@ use std::ptr;
 
 /// Main entry point to the FITS file format
 pub struct FitsFile {
-    /// Name of the file
-    pub filename: PathBuf,
+    filename: Option<PathBuf>,
     open_mode: FileOpenMode,
     pub(crate) fptr: ptr::NonNull<fitsfile>,
 }
@@ -66,7 +65,7 @@ impl FitsFile {
             Some(p) => FitsFile {
                 fptr: p,
                 open_mode: FileOpenMode::READONLY,
-                filename: file_path.to_path_buf(),
+                filename: Some(file_path.to_path_buf()),
             },
             None => unimplemented!(),
         })
@@ -108,7 +107,7 @@ impl FitsFile {
             Some(p) => FitsFile {
                 fptr: p,
                 open_mode: FileOpenMode::READWRITE,
-                filename: file_path.to_path_buf(),
+                filename: Some(file_path.to_path_buf()),
             },
             None => unimplemented!(),
         })
@@ -659,7 +658,9 @@ impl FitsFile {
     where
         W: Write,
     {
-        writeln!(w, "\n  file: {:?}", self.filename)?;
+        if let Some(ref filename) = self.filename {
+            writeln!(w, "\n  file: {:?}", filename)?;
+        }
         match self.open_mode {
             FileOpenMode::READONLY => writeln!(w, "  mode: READONLY")?,
             FileOpenMode::READWRITE => writeln!(w, "  mode: READWRITE")?,
@@ -753,6 +754,60 @@ impl FitsFile {
     pub unsafe fn as_raw(&mut self) -> *mut fitsfile {
         self.fptr.as_mut() as *mut _
     }
+
+    /// Load a `FitsFile` from a `fitsio_sys::fitsfile` pointer.
+    ///
+    /// # Safety
+    ///
+    /// This constructor is inherently unsafe - the Rust compiler cannot verify the validity of
+    /// the pointer supplied. It is therefore the responsibility of the caller to prove that the
+    /// pointer is a valid `fitsfile` by calling an `unsafe` function.
+    ///
+    /// it is up to the caller to guarantee that the pointer given was
+    ///
+    /// 1. created by `cfitsio` (or [`fitsio_sys`]), and
+    /// 2. it represents a valid FITS file.
+    ///
+    /// Given these two things, a [`FitsFile`] can be created.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # #[cfg(not(feature="bindgen"))]
+    /// # use fitsio_sys;
+    /// # #[cfg(feature="bindgen")]
+    /// # use fitsio_sys_bindgen as fitsio_sys;
+    ///
+    /// use fitsio_sys::ffopen;
+    /// use fitsio::{FileOpenMode, FitsFile};
+    ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// let filename = "../testdata/full_example.fits";
+    /// let mut fptr = std::ptr::null_mut();
+    /// let mut status = 0;
+    /// let c_filename = std::ffi::CString::new(filename).expect("filename is not a valid C-string");
+    ///
+    /// unsafe {
+    ///     ffopen(
+    ///         &mut fptr as *mut *mut _,
+    ///         c_filename.as_ptr(),
+    ///         0, // readonly
+    ///         &mut status,
+    ///     );
+    /// }
+    /// assert_eq!(status, 0);
+    ///
+    /// let mut f = unsafe { FitsFile::from_raw(fptr, FileOpenMode::READONLY) }.unwrap();
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub unsafe fn from_raw(fptr: *mut fitsfile, mode: FileOpenMode) -> Result<FitsFile> {
+        Ok(Self {
+            filename: None,
+            open_mode: mode,
+            fptr: ptr::NonNull::new(fptr).ok_or(Error::NullPointer)?,
+        })
+    }
 }
 
 impl Drop for FitsFile {
@@ -869,7 +924,7 @@ where
                 Some(p) => FitsFile {
                     fptr: p,
                     open_mode: FileOpenMode::READWRITE,
-                    filename: file_path.to_path_buf(),
+                    filename: Some(file_path.to_path_buf()),
                 },
                 None => unimplemented!(),
             };

fitsio/src/lib.rs

@@ -860,6 +860,8 @@ let newhdu = hdu.delete_column(&mut fptr, 0)?;
 
 # Raw fits file access
 
+## Converting a `FitsFile` to a raw `fitsio_sys::fitsfile` pointer
+
 If this library does not support the particular use case that is needed, the raw `fitsfile`
 pointer can be accessed:
 
@@ -880,11 +882,11 @@ let mut num_hdus = 0;
 let mut status = 0;
 
 unsafe {
-let fitsfile = fptr.as_raw();
+    let fitsfile = fptr.as_raw();
 
-/* Use the unsafe fitsio-sys low level library to call a function that is possibly not
-implemented in this crate */
-fitsio_sys::ffthdu(fitsfile, &mut num_hdus, &mut status);
+    /* Use the unsafe fitsio-sys low level library to call a function that is possibly not
+    implemented in this crate */
+    fitsio_sys::ffthdu(fitsfile, &mut num_hdus, &mut status);
 }
 assert_eq!(num_hdus, 2);
 # Ok(())
@@ -894,6 +896,45 @@ assert_eq!(num_hdus, 2);
 
 This (unsafe) pointer can then be used with the underlying [`fitsio-sys`][fitsio-sys] library directly.
 
+## Creating a `FitsFile` from a raw `fitsio_sys::fitsfile` pointer
+
+The inverse of the process described above can be performed. Note: calling this [`FitsFile`]
+constructor is _unsafe_ => it is up to the caller to guarantee that the pointer given was
+
+1. created by `cfitsio` (or [`fitsio_sys`]), and
+2. it represents a valid FITS file.
+
+Given these two things, a [`FitsFile`] can be created.
+
+```rust
+# #[cfg(not(feature="bindgen"))]
+# use fitsio_sys;
+# #[cfg(feature="bindgen")]
+# use fitsio_sys_bindgen as fitsio_sys;
+use fitsio_sys::ffopen;
+use fitsio::{FileOpenMode, FitsFile};
+
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+let filename = "../testdata/full_example.fits";
+let mut fptr = std::ptr::null_mut();
+let mut status = 0;
+let c_filename = std::ffi::CString::new(filename).expect("filename is not a valid C-string");
+
+unsafe {
+    ffopen(
+        &mut fptr as *mut *mut _,
+        c_filename.as_ptr(),
+        0, // readonly
+        &mut status,
+    );
+}
+assert_eq!(status, 0);
+
+let mut f = unsafe { FitsFile::from_raw(fptr, FileOpenMode::READONLY) }.unwrap();
+# Ok(())
+# }
+```
+
 # Threadsafe access
 
 Access to a [`FitsFile`][fits-file] is not threadsafe. Behind the scenes, fetching a
@@ -995,9 +1036,9 @@ let _hdu = t.hdu(hdu_num).unwrap();
 
 // If we are using the `bindgen` feature then import `fitsio_sys_bindgen` with a new name
 #[cfg(feature = "default")]
-use fitsio_sys as sys;
+pub use fitsio_sys as sys;
 #[cfg(feature = "bindgen")]
-use fitsio_sys_bindgen as sys;
+pub use fitsio_sys_bindgen as sys;
 
 #[macro_use]
 mod macros;
@@ -1020,7 +1061,7 @@ pub mod threadsafe_fitsfile;
 pub mod errors;
 
 // Re-exports
-pub use crate::fitsfile::FitsFile;
+pub use crate::fitsfile::{FileOpenMode, FitsFile};
 
 // For custom derive purposes
 // pub use tables::FitsRow;

fitsio/tests/test_from_raw.rs

@@ -0,0 +1,39 @@
+use fitsio::{FileOpenMode, FitsFile};
+#[cfg(not(feature = "bindgen"))]
+use fitsio_sys;
+use fitsio_sys::ffopen;
+#[cfg(feature = "bindgen")]
+use fitsio_sys_bindgen as fitsio_sys;
+use std::ptr;
+
+#[test]
+fn from_raw() {
+    let filename = "../testdata/full_example.fits";
+    let mut fptr = ptr::null_mut();
+    let mut status = 0;
+    let c_filename = std::ffi::CString::new(filename).expect("filename is not a valid C-string");
+
+    unsafe {
+        ffopen(
+            &mut fptr as *mut *mut _,
+            c_filename.as_ptr(),
+            0, // readonly
+            &mut status,
+        );
+    }
+    assert_eq!(status, 0);
+
+    let mut f = unsafe { FitsFile::from_raw(fptr, FileOpenMode::READONLY) }.unwrap();
+
+    // the rest of this test is taken from the `images.rs::test_read_image_data` test.
+    let hdu = f.hdu(0).unwrap();
+    let first_row: Vec<i32> = hdu.read_section(&mut f, 0, 100).unwrap();
+    assert_eq!(first_row.len(), 100);
+    assert_eq!(first_row[0], 108);
+    assert_eq!(first_row[49], 176);
+
+    let second_row: Vec<i32> = hdu.read_section(&mut f, 100, 200).unwrap();
+    assert_eq!(second_row.len(), 100);
+    assert_eq!(second_row[0], 177);
+    assert_eq!(second_row[49], 168);
+}