src/linux/write_zeroes.rs

// Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//
// Copyright 2019 Intel Corporation. All Rights Reserved.
//
// Copyright 2018 The Chromium OS Authors. All rights reserved.
//
// SPDX-License-Identifier: BSD-3-Clause

//! Traits for replacing a range with a hole and writing zeroes in a file.

use std::cmp::min;
use std::fs::File;
use std::io::{Error, ErrorKind, Result, Seek, SeekFrom};
use std::os::unix::fs::FileExt;

use crate::fallocate::{fallocate, FallocateMode};

/// A trait for deallocating space in a file.
pub trait PunchHole {
    /// Replace a range of bytes with a hole.
    ///
    /// # Arguments
    ///
    /// * `offset`: offset of the file where to replace with a hole.
    /// * `length`: the number of bytes of the hole to replace with.
    fn punch_hole(&mut self, offset: u64, length: u64) -> Result<()>;
}

impl PunchHole for File {
    fn punch_hole(&mut self, offset: u64, length: u64) -> Result<()> {
        fallocate(self, FallocateMode::PunchHole, true, offset, length as u64)
            .map_err(|e| Error::from_raw_os_error(e.errno()))
    }
}

/// A trait for writing zeroes to a stream.
pub trait WriteZeroes {
    /// Write up to `length` bytes of zeroes to the stream, returning how many bytes were written.
    ///
    /// # Arguments
    ///
    /// * `length`: the number of bytes of zeroes to write to the stream.
    fn write_zeroes(&mut self, length: usize) -> Result<usize>;

    /// Write zeroes to the stream until `length` bytes have been written.
    ///
    /// This method will continuously write zeroes until the requested `length` is satisfied or an
    /// unrecoverable error is encountered.
    ///
    /// # Arguments
    ///
    /// * `length`: the exact number of bytes of zeroes to write to the stream.
    fn write_all_zeroes(&mut self, mut length: usize) -> Result<()> {
        while length > 0 {
            match self.write_zeroes(length) {
                Ok(0) => return Err(Error::from(ErrorKind::WriteZero)),
                Ok(bytes_written) => {
                    length = length
                        .checked_sub(bytes_written)
                        .ok_or_else(|| Error::from(ErrorKind::Other))?
                }
                // If the operation was interrupted, we should retry it.
                Err(e) => {
                    if e.kind() != ErrorKind::Interrupted {
                        return Err(e);
                    }
                }
            }
        }
        Ok(())
    }
}

/// A trait for writing zeroes to an arbitrary position in a file.
pub trait WriteZeroesAt {
    /// Write up to `length` bytes of zeroes starting at `offset`, returning how many bytes were
    /// written.
    ///
    /// # Arguments
    ///
    /// * `offset`: offset of the file where to write zeroes.
    /// * `length`: the number of bytes of zeroes to write to the stream.
    fn write_zeroes_at(&mut self, offset: u64, length: usize) -> Result<usize>;

    /// Write zeroes starting at `offset` until `length` bytes have been written.
    ///
    /// This method will continuously write zeroes until the requested `length` is satisfied or an
    /// unrecoverable error is encountered.
    ///
    /// # Arguments
    ///
    /// * `offset`: offset of the file where to write zeroes.
    /// * `length`: the exact number of bytes of zeroes to write to the stream.
    fn write_all_zeroes_at(&mut self, mut offset: u64, mut length: usize) -> Result<()> {
        while length > 0 {
            match self.write_zeroes_at(offset, length) {
                Ok(0) => return Err(Error::from(ErrorKind::WriteZero)),
                Ok(bytes_written) => {
                    length = length
                        .checked_sub(bytes_written)
                        .ok_or_else(|| Error::from(ErrorKind::Other))?;
                    offset = offset
                        .checked_add(bytes_written as u64)
                        .ok_or_else(|| Error::from(ErrorKind::Other))?;
                }
                Err(e) => {
                    // If the operation was interrupted, we should retry it.
                    if e.kind() != ErrorKind::Interrupted {
                        return Err(e);
                    }
                }
            }
        }
        Ok(())
    }
}

impl WriteZeroesAt for File {
    fn write_zeroes_at(&mut self, offset: u64, length: usize) -> Result<usize> {
        // Try to use fallocate() first, since it is more efficient than writing zeroes with
        // write().
        if fallocate(self, FallocateMode::ZeroRange, true, offset, length as u64).is_ok() {
            return Ok(length);
        }

        // Fall back to write().
        // fallocate() failed; fall back to writing a buffer of zeroes until we have written up
        // to `length`.
        let buf_size = min(length, 0x10000);
        let buf = vec![0u8; buf_size];
        let mut num_written: usize = 0;
        while num_written < length {
            let remaining = length - num_written;
            let write_size = min(remaining, buf_size);
            num_written += self.write_at(&buf[0..write_size], offset + num_written as u64)?;
        }
        Ok(length)
    }
}

impl<T: WriteZeroesAt + Seek> WriteZeroes for T {
    fn write_zeroes(&mut self, length: usize) -> Result<usize> {
        let offset = self.seek(SeekFrom::Current(0))?;
        let num_written = self.write_zeroes_at(offset, length)?;
        // Advance the seek cursor as if we had done a real write().
        self.seek(SeekFrom::Current(num_written as i64))?;
        Ok(length)
    }
}

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

    use std::io::{Read, Seek, SeekFrom, Write};

    use crate::tempfile::TempFile;

    #[test]
    fn test_small_write_zeroes() {
        const NON_ZERO_VALUE: u8 = 0x55;
        const BUF_SIZE: usize = 5678;

        let mut f = TempFile::new().unwrap().into_file();
        f.set_len(16384).unwrap();

        // Write buffer of non-zero bytes to offset 1234.
        let orig_data = [NON_ZERO_VALUE; BUF_SIZE];
        f.seek(SeekFrom::Start(1234)).unwrap();
        f.write_all(&orig_data).unwrap();

        // Read back the data plus some overlap on each side.
        let mut readback = [0u8; 16384];
        f.seek(SeekFrom::Start(0)).unwrap();
        f.read_exact(&mut readback).unwrap();
        // Bytes before the write should still be 0.
        for read in &readback[0..1234] {
            assert_eq!(*read, 0);
        }
        // Bytes that were just written should have `NON_ZERO_VALUE` value.
        for read in &readback[1234..(1234 + BUF_SIZE)] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }
        // Bytes after the written area should still be 0.
        for read in &readback[(1234 + BUF_SIZE)..] {
            assert_eq!(*read, 0);
        }

        // Overwrite some of the data with zeroes.
        f.seek(SeekFrom::Start(2345)).unwrap();
        f.write_all_zeroes(4321).unwrap();
        // Verify seek position after `write_all_zeroes()`.
        assert_eq!(f.seek(SeekFrom::Current(0)).unwrap(), 2345 + 4321);

        // Read back the data and verify that it is now zero.
        f.seek(SeekFrom::Start(0)).unwrap();
        f.read_exact(&mut readback).unwrap();
        // Bytes before the write should still be 0.
        for read in &readback[0..1234] {
            assert_eq!(*read, 0);
        }
        // Original data should still exist before the zeroed region.
        for read in &readback[1234..2345] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }
        // Verify that `write_all_zeroes()` zeroed the intended region.
        for read in &readback[2345..(2345 + 4321)] {
            assert_eq!(*read, 0);
        }
        // Original data should still exist after the zeroed region.
        for read in &readback[(2345 + 4321)..(1234 + BUF_SIZE)] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }
        // The rest of the file should still be 0.
        for read in &readback[(1234 + BUF_SIZE)..] {
            assert_eq!(*read, 0);
        }
    }

    #[test]
    fn test_large_write_zeroes() {
        const NON_ZERO_VALUE: u8 = 0x55;
        const SIZE: usize = 0x2_0000;

        let mut f = TempFile::new().unwrap().into_file();
        f.set_len(16384).unwrap();

        // Write buffer of non-zero bytes. The size of the buffer will be the new
        // size of the file.
        let orig_data = [NON_ZERO_VALUE; SIZE];
        f.seek(SeekFrom::Start(0)).unwrap();
        f.write_all(&orig_data).unwrap();
        assert_eq!(f.metadata().unwrap().len(), SIZE as u64);

        // Overwrite some of the data with zeroes.
        f.seek(SeekFrom::Start(0)).unwrap();
        f.write_all_zeroes(0x1_0001).unwrap();
        // Verify seek position after `write_all_zeroes()`.
        assert_eq!(f.seek(SeekFrom::Current(0)).unwrap(), 0x1_0001);

        // Read back the data and verify that it is now zero.
        let mut readback = [0u8; SIZE];
        f.seek(SeekFrom::Start(0)).unwrap();
        f.read_exact(&mut readback).unwrap();
        // Verify that `write_all_zeroes()` zeroed the intended region.
        for read in &readback[0..0x1_0001] {
            assert_eq!(*read, 0);
        }
        // Original data should still exist after the zeroed region.
        for read in &readback[0x1_0001..SIZE] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }

        // Now let's zero a certain region by using `write_all_zeroes_at()`.
        f.write_all_zeroes_at(0x1_8001, 0x200).unwrap();
        f.seek(SeekFrom::Start(0)).unwrap();
        f.read_exact(&mut readback).unwrap();

        // Original data should still exist before the zeroed region.
        for read in &readback[0x1_0001..0x1_8001] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }
        // Verify that `write_all_zeroes_at()` zeroed the intended region.
        for read in &readback[0x1_8001..(0x1_8001 + 0x200)] {
            assert_eq!(*read, 0);
        }
        // Original data should still exist after the zeroed region.
        for read in &readback[(0x1_8001 + 0x200)..SIZE] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }
    }

    #[test]
    fn test_punch_hole() {
        const NON_ZERO_VALUE: u8 = 0x55;
        const SIZE: usize = 0x2_0000;

        let mut f = TempFile::new().unwrap().into_file();
        f.set_len(16384).unwrap();

        // Write buffer of non-zero bytes. The size of the buffer will be the new
        // size of the file.
        let orig_data = [NON_ZERO_VALUE; SIZE];
        f.seek(SeekFrom::Start(0)).unwrap();
        f.write_all(&orig_data).unwrap();
        assert_eq!(f.metadata().unwrap().len(), SIZE as u64);

        // Punch a hole at offset 0x10001.
        // Subsequent reads from this range will return zeros.
        f.punch_hole(0x1_0001, 0x200).unwrap();

        // Read back the data.
        let mut readback = [0u8; SIZE];
        f.seek(SeekFrom::Start(0)).unwrap();
        f.read_exact(&mut readback).unwrap();
        // Original data should still exist before the hole.
        for read in &readback[0..0x1_0001] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }
        // Verify that `punch_hole()` zeroed the intended region.
        for read in &readback[0x1_0001..(0x1_0001 + 0x200)] {
            assert_eq!(*read, 0);
        }
        // Original data should still exist after the hole.
        for read in &readback[(0x1_0001 + 0x200)..] {
            assert_eq!(*read, NON_ZERO_VALUE);
        }

        // Punch a hole at the end of the file.
        // Subsequent reads from this range should return zeros.
        f.punch_hole(SIZE as u64 - 0x400, 0x400).unwrap();
        // Even though we punched a hole at the end of the file, the file size should remain the
        // same since FALLOC_FL_PUNCH_HOLE must be used with FALLOC_FL_KEEP_SIZE.
        assert_eq!(f.metadata().unwrap().len(), SIZE as u64);

        let mut readback = [0u8; 0x400];
        f.seek(SeekFrom::Start(SIZE as u64 - 0x400)).unwrap();
        f.read_exact(&mut readback).unwrap();
        // Verify that `punch_hole()` zeroed the intended region.
        for read in &readback[0..0x400] {
            assert_eq!(*read, 0);
        }

        // Punching a hole of len 0 should return an error.
        assert!(f.punch_hole(0x200, 0x0).is_err());
        // Zeroing a region of len 0 should not return an error since we have a fallback path
        // in `write_zeroes_at()` for `fallocate()` failure.
        assert!(f.write_zeroes_at(0x200, 0x0).is_ok());
    }
}