io_close/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! An extension trait for safely dropping [I/O writers](std::io::Write)
4//! such as [`File`](std::fs::File) and
5//! [`BufWriter`](std::io::BufWriter). Specifically, it is for I/O
6//! writers which may contain a resource handle (such as a raw file
7//! descriptor), and where the automatic process of closing this handle
8//! during drop may generate an unseen I/O error. Using this trait
9//! (called [`Close`]) these errors can be seen and dealt with.
10//!
11//! In the case of Linux [the man page for
12//! close(2)](https://linux.die.net/man/2/close) has the following to
13//! say:
14//!
15//! > Not checking the return value of close() is a common but
16//! > nevertheless serious programming error. It is quite possible that
17//! > errors on a previous write(2) operation are first reported at the
18//! > final close(). Not checking the return value when closing the file
19//! > may lead to silent loss of data. This can especially be observed
20//! > with NFS and with disk quota.
21//!
22//! Implementations of [`Close`] are provided for most standard library
23//! I/O writers and (optionally) for a selection of I/O writers defined
24//! in external crates.
25//!
26//! # BufWriter example
27//!
28//! ```
29//! use std::io::{BufWriter, Result, Write};
30//! use io_close::Close;
31//!
32//! fn main() -> Result<()> {
33//!     let data = b"hello world";
34//!     let mut buffer = BufWriter::new(tempfile::tempfile()?);
35//!     buffer.write_all(data)?;
36//!     buffer.close()?; // safely drop buffer and its contained File
37//!     Ok(())
38//! }
39//! ```
40//!
41//! # Optional implementations
42//!
43//! Optional implementations of [`Close`] are provided for the following
44//! I/O writers defined in external crates, enabled through cargo features:
45//!
46//! - [`os_pipe::PipeWriter`] (feature: `os_pipe`)
47
48use std::io::{Error, Result, Write};
49
50pub mod fs;
51
52/// An extension trait for safely dropping I/O writers.
53pub trait Close: Write {
54    /// Drops an I/O writer and closes any resource handle contained
55    /// inside (such as a raw file descriptor). Ensures that I/O errors
56    /// resulting from closing a handle are not ignored. The writer is
57    /// flushed before any handle is closed. If any errors occur during
58    /// flushing or closing the first such error is returned.
59    fn close(self) -> Result<()>;
60}
61
62// MACRO DEFINITIONS
63
64macro_rules! unix_impl_close_raw_fd {
65    ($ty:ty, "std" $(,$lt:lifetime)* $(,$id:ident)*) => {
66        unix_impl_close_raw_fd!($ty, "unix" $(,$lt)* $(,$id)*);
67    };
68    ($ty:ty, $ft_fm:literal $(,$lt:lifetime)* $(,$id:ident)*) => {
69        #[cfg(unix)]
70        #[cfg(any(feature = $ft_fm, target_family = $ft_fm))]
71        #[cfg_attr(all(docsrs, feature = $ft_fm), doc(cfg(feature = $ft_fm)))]
72        impl<$($lt,)* $($id,)*> Close for $ty {
73            /// Drops an I/O writer containing a raw file descriptor.
74            fn close(mut self) -> Result<()> {
75                use std::io::ErrorKind;
76                use std::os::unix::io::IntoRawFd;
77
78                self.flush()?;
79                let fd = self.into_raw_fd();
80                let rv = unsafe { libc::close(fd) };
81                if rv != -1 {
82                    Ok(())
83                } else {
84                    match Error::last_os_error() {
85                        e if e.kind() == ErrorKind::Interrupted => Ok(()),
86                        e => Err(e),
87                    }
88                }
89            }
90        }
91    };
92}
93
94macro_rules! windows_impl_close_raw_handle {
95    ($ty:ty, "std" $(,$lt:lifetime)* $(,$id:ident)*) => {
96        windows_impl_close_raw_handle!($ty, "windows" $(,$lt)* $(,$id)*);
97    };
98    ($ty:ty, $ft_fm:literal $(,$lt:lifetime)* $(,$id:ident)*) => {
99        #[cfg(windows)]
100        #[cfg(any(feature = $ft_fm, target_family = $ft_fm))]
101        #[cfg_attr(all(docsrs, feature = $ft_fm), doc(cfg(feature = $ft_fm)))]
102        impl<$($lt,)* $($id,)*> Close for $ty {
103            /// Drops an I/O writer containing a raw handle.
104            fn close(mut self) -> Result<()> {
105                use std::os::windows::io::IntoRawHandle;
106                use winapi::um::handleapi;
107
108                self.flush()?;
109                let handle = self.into_raw_handle();
110                let rv = unsafe { handleapi::CloseHandle(handle) };
111                if rv != 0 {
112                    Ok(())
113                } else {
114                    Err(Error::last_os_error())
115                }
116            }
117        }
118    };
119}
120
121macro_rules! windows_impl_close_raw_socket {
122    ($ty:ty, "std" $(,$lt:lifetime)* $(,$id:ident)*) => {
123        windows_impl_close_raw_socket!($ty, "windows" $(,$lt)* $(,$id)*);
124    };
125    ($ty:ty, $ft_fm:literal $(,$lt:lifetime)* $(,$id:ident)*) => {
126        #[cfg(windows)]
127        #[cfg(any(feature = $ft_fm, target_family = $ft_fm))]
128        #[cfg_attr(all(docsrs, feature = $ft_fm), doc(cfg(feature = $ft_fm)))]
129        impl<$($lt,)* $($id,)*> Close for $ty {
130            /// Drops an I/O writer containing a raw socket.
131            fn close(mut self) -> Result<()> {
132                use std::convert::TryInto;
133                use std::os::windows::io::IntoRawSocket;
134                use winapi::um::winsock2;
135
136                self.flush()?;
137                let socket = self.into_raw_socket().try_into().unwrap();
138                let rv = unsafe { winsock2::closesocket(socket) };
139                if rv == 0 {
140                    Ok(())
141                } else {
142                    Err(Error::from_raw_os_error(unsafe {
143                        winsock2::WSAGetLastError()
144                    }))
145                }
146            }
147        }
148    };
149}
150
151macro_rules! impl_close_no_error_no_flush {
152    ($ty:ty, "std" $(,$lt:lifetime)* $(,$id:ident)*) => {
153        #[cfg(unix)]
154        impl_close_no_error_no_flush!($ty, "unix" $(,$lt)* $(,$id)*);
155        #[cfg(windows)]
156        impl_close_no_error_no_flush!($ty, "windows" $(,$lt)* $(,$id)*);
157    };
158    ($ty:ty, $ft_fm:literal $(,$lt:lifetime)* $(,$id:ident)*) => {
159        #[cfg(any(unix, windows))]
160        #[cfg(any(feature = $ft_fm, target_family = $ft_fm))]
161        #[cfg_attr(all(docsrs, feature = $ft_fm), doc(cfg(feature = $ft_fm)))]
162        impl<$($lt,)* $($id,)*> Close for $ty {
163            /// Drops an I/O writer for which `close()` never produces
164            /// an error, and for which flushing is unnecessary.
165            #[inline]
166            fn close(self) -> Result<()> {
167                Ok(())
168            }
169        }
170    };
171}
172
173macro_rules! impl_close_into_inner {
174    ($ty:ty, "std" $(,$lt:lifetime)* $(,$id:ident)*) => {
175        #[cfg(unix)]
176        impl_close_into_inner!($ty, "unix" $(,$lt)* $(,$id)*);
177        #[cfg(windows)]
178        impl_close_into_inner!($ty, "windows" $(,$lt)* $(,$id)*);
179    };
180    ($ty:ty, $ft_fm:literal $(,$lt:lifetime)* $(,$id:ident)*) => {
181        #[cfg(any(unix, windows))]
182        #[cfg(any(feature = $ft_fm, target_family = $ft_fm))]
183        #[cfg_attr(all(docsrs, feature = $ft_fm), doc(cfg(feature = $ft_fm)))]
184        impl<$($lt,)* W: Close, $($id,)*> Close for $ty {
185            /// Drops an I/O writer which can be unwrapped using
186            /// `into_inner()` to return an underlying writer.
187            fn close(self) -> Result<()> {
188                self.into_inner()?.close()
189            }
190        }
191    };
192}
193
194// IMPLEMENTATIONS
195//
196// In the below macro implementations for Close the macro parameters use
197// the following system:
198//
199//     1st paramater: the type that Close is being implemented for
200//     2nd parameter: either "std", or a feature name
201//     3rd, 4th, etc. parameters: additional generic arguments for type
202//
203// If the 2nd parameter is a feature name then the implementation will
204// be conditionally compiled only when that feature is present.
205
206unix_impl_close_raw_fd!(std::fs::File, "std");
207unix_impl_close_raw_fd!(std::net::TcpStream, "std");
208unix_impl_close_raw_fd!(std::os::unix::net::UnixStream, "std");
209unix_impl_close_raw_fd!(std::process::ChildStdin, "std");
210unix_impl_close_raw_fd!(os_pipe::PipeWriter, "os_pipe");
211
212windows_impl_close_raw_handle!(std::fs::File, "std");
213windows_impl_close_raw_socket!(std::net::TcpStream, "std");
214windows_impl_close_raw_handle!(std::process::ChildStdin, "std");
215windows_impl_close_raw_handle!(os_pipe::PipeWriter, "os_pipe");
216
217impl_close_no_error_no_flush!(&mut [u8], "std");
218impl_close_no_error_no_flush!(std::io::Cursor<&mut Vec<u8>>, "std");
219impl_close_no_error_no_flush!(std::io::Cursor<&mut [u8]>, "std");
220impl_close_no_error_no_flush!(std::io::Cursor<Box<[u8]>>, "std");
221impl_close_no_error_no_flush!(std::io::Cursor<Vec<u8>>, "std");
222impl_close_no_error_no_flush!(std::io::Sink, "std");
223impl_close_no_error_no_flush!(Vec<u8>, "std");
224
225impl_close_into_inner!(std::io::BufWriter<W>, "std");
226impl_close_into_inner!(std::io::LineWriter<W>, "std");
io_close/lib.rs

io_close/
lib.rs
