pub struct ImmutableFd<F: AsFd> { /* private fields */ }Expand description
A file descriptor for an immutable file
A file is “immutable” if it cannot possibly change size or content, ever.
This means that it’s impossible for the length or content of the file to be changed from either
inside or outside of the program. This goes beyond the usual “file is read-only” or even
chattr +i measures because they are reversible.
The only thing that can be done with an immutable file is unlinking it, but it will continue to exist (and continue to be immutable) for as long as any open file descriptors refer to it.
There are a number of ways to obtain an immutable file descriptor:
- from an fd for a fs-verity enabled file (these files can never be modified once their fs-verity status is enabled)
- from an fd for a sealed memfd (which can also never be modified)
- from any fd, unsafely
Implementations§
Source§impl<F: AsFd> ImmutableFd<F>
impl<F: AsFd> ImmutableFd<F>
Sourcepub unsafe fn from_fd(fd: F) -> Self
pub unsafe fn from_fd(fd: F) -> Self
Produces an ImmutableFd from any file descriptor, unsafely.
§Safety
This function is only safe if the caller takes the responsibility for verifying that the underlying file descriptor points to an immutable file. This means that it’s impossible for the length or content of the file to be changed from either inside or outside of the program.
Sourcepub fn from_fs_verity_file(fd: F) -> Result<Self, ImmutableFdError>
pub fn from_fs_verity_file(fd: F) -> Result<Self, ImmutableFdError>
Produces an ImmutableFd from an fd pointing to an fs-verity-enabled file
This function confirms that the file is fs-verity enabled before returning. If this could not be determined, then an error is returned.
Sourcepub fn from_sealed_memfd(fd: F) -> Result<Self, ImmutableFdError>
pub fn from_sealed_memfd(fd: F) -> Result<Self, ImmutableFdError>
Produces an ImmutableFd from a memfd which is sealed for “grow”, “shrink”, and “write”.
This function confirms that the memfd is sealed. If this could not be determined, then an error is returned.
Sourcepub unsafe fn mmap_with_length_and_offset(
&self,
len: usize,
offset: u64,
) -> Result<Mapping>
pub unsafe fn mmap_with_length_and_offset( &self, len: usize, offset: u64, ) -> Result<Mapping>
Produces a read-only memory mapping of the given length from the given offset into the given immutable file descriptor.
The offset must be a multiple of the page size. The length does not need to be a multiple of the page size. When performing the mapping, the length is rounded-up by the kernel to the next page-size boundary, but the returned Mapping will have the exact length as given.
This function corresponds exactly to a single mmap() syscall. There is no extra
validation performed on the arguments. The returned Mapping object has a Drop impl which
will call munmap().
§Safety
This function is only safe if the specified byte range is not actually available in the underlying file, you may receive a SIGBUS signal when attempting to access the memory. It is the responsibility of the caller to ensure that the passed range is valid. Calling this function on a range that doesn’t exist inside of the file produces undefined behaviour.
Sourcepub fn mmap_with_offset(&self, offset: u64) -> Result<Mapping>
pub fn mmap_with_offset(&self, offset: u64) -> Result<Mapping>
Produces a read-only memory mapping from the given offset into the given immutable file descriptor.
This function uses fstat() to query the size of the file descriptor before mapping it. The produced mapping is for the range from the given offset to the end of the file.
As a convenience, if the size of the file is exactly equal to offset parameter then this will produce a fake empty mapping. This is done to improve the ergonomics of the API when dealing with empty files: it’s not valid to call mmap() for a zero-byte range.
Sourcepub fn mmap(&self) -> Result<Mapping>
pub fn mmap(&self) -> Result<Mapping>
Produces a read-only memory mapping from the given immutable file descriptor.
This function uses fstat() to query the size of the file descriptor before mapping it. The produced mapping covers the complete file.
As a convenience, this will produce a fake empty mapping for empty files. This is done to improve the ergonomics of the API when dealing with empty files: it’s not valid to call mmap() for a zero-byte range.