//! Low-level file I/O operations that don't involve xattrs.

// Copyright 2023 Zack Weinberg

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

// https://www.apache.org/licenses/LICENSE-2.0

#[cfg(test)]

#[path = "test/file_io.rs"]

mod test;

use std::fs::File;

use std::io;

use std::os::fd::AsRawFd;

use std::time::SystemTime;

use memmap2::{Mmap, MmapOptions};

/// Succeeds if the file F was opened with O_RDONLY rather than

/// O_WRONLY or O_RDWR, fails otherwise.

/// Take an advisory read lock on a file, using flock().  The lock

/// will be released when the file is closed (most precisely when the

/// OS-level "open file description" is closed).

///

/// This function waits for the lock to be granted and therefore may

/// take a very long time to return.

///

/// # Bugs

///

/// Depending on the OS and the file system, this lock may or may not

/// block programs that use fcntl() instead of flock() to lock files.

    } else {

    }

/// Subroutine of checked_file::wrap: Given an open file, look up its

/// last modification time, lock it for reading, and create an mmap

/// region covering the entire file.

    // Rust does not allow [u8] to have more than isize::MAX elements.

    // It's possible (particularly if usize is only 32 bits) for

    // md.len() to be larger than that.  Reject such files now,

    // because the OS might allow mappings that are too large for

    // isize (but still fit in usize).

    // SAFETY: File mappings are considered unsafe because the data

    // in the file _could_ be changed by another process during the

    // lifetime of the map, and the kernel _could_ expose that change

    // through the map (even for a MAP_PRIVATE mapping), violating

    // Rust's expectations that a &[u8] slice is immutable.

    //

    // We presume that CheckedFiles are intended to be immutable on

    // disk (else what's the point of checking them?) so it should be

    // OK to trap the unsafety here and present a safe interface to

    // users of the crate.  We further mitigate the risk by applying

    // an advisory read lock to the file and, at a higher level,

    // requiring the File object to be open exclusively for reading.

    // We don't, however, attempt to enforce that the file is read-

    // only on disk, because that would interfere with use of the

    // write_checksum() method, and because the answer to "is the file

    // read-only on disk" can, for most files, change at any moment.

    };

    // As far as we can tell, it is impossible to make Metadata::modified()

    // fail on Unix.  By using map() here, instead of ?, we avoid

    // having that show up as a lacuna in branch coverage.

    //

    // In case we ever get fancier coverage testing that can catch the

    // lacuna, this function has been placed at the very bottom of

    // this file.  That keeps the lacuna out of the the way of the

    // "jump to first uncovered line" feature in llvm-cov output.