Trait std::os::unix::fs::FileExt

pub trait FileExt {
    fn read_at(&self, buf: &mut [u8], offset: u64) -> Result<usize>;
    fn write_at(&self, buf: &[u8], offset: u64) -> Result<usize>;

    fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()> { ... }
    fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()> { ... }
}

This is supported on Unix only.

Unix-specific extensions to File.

Required methods

fn read_at(&self, buf: &mut [u8], offset: u64) -> Result<usize>

This is supported on Unix only.

Reads a number of bytes starting from a given offset.

Returns the number of bytes read.

The offset is relative to the start of the file and thus independent from the current cursor.

The current file cursor is not affected by this function.

Note that similar to File::read, it is not an error to return with a short read.

Examples

use std::io;
use std::fs::File;
use std::os::unix::prelude::FileExt;

fn main() -> io::Result<()> {
    let mut buf = [0u8; 8];
    let file = File::open("foo.txt")?;

    // We now read 8 bytes from the offset 10.
    let num_bytes_read = file.read_at(&mut buf, 10)?;
    println!("read {} bytes: {:?}", num_bytes_read, buf);
    Ok(())
}

fn write_at(&self, buf: &[u8], offset: u64) -> Result<usize>

This is supported on Unix only.

Writes a number of bytes starting from a given offset.

Returns the number of bytes written.

The offset is relative to the start of the file and thus independent from the current cursor.

The current file cursor is not affected by this function.

When writing beyond the end of the file, the file is appropriately extended and the intermediate bytes are initialized with the value 0.

Note that similar to File::write, it is not an error to return a short write.

Examples

use std::fs::File;
use std::io;
use std::os::unix::prelude::FileExt;

fn main() -> io::Result<()> {
    let file = File::open("foo.txt")?;

    // We now write at the offset 10.
    file.write_at(b"sushi", 10)?;
    Ok(())
}

Loading content...

Provided methods

fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>

This is supported on Unix only.

Reads the exact number of byte required to fill buf from the given offset.

The offset is relative to the start of the file and thus independent from the current cursor.

The current file cursor is not affected by this function.

Similar to Read::read_exact but uses read_at instead of read.

Errors

If this function encounters an error of the kind ErrorKind::Interrupted then the error is ignored and the operation will continue.

If this function encounters an "end of file" before completely filling the buffer, it returns an error of the kind ErrorKind::UnexpectedEof. The contents of buf are unspecified in this case.

If any other read error is encountered then this function immediately returns. The contents of buf are unspecified in this case.

If this function returns an error, it is unspecified how many bytes it has read, but it will never read more than would be necessary to completely fill the buffer.

Examples

use std::io;
use std::fs::File;
use std::os::unix::prelude::FileExt;

fn main() -> io::Result<()> {
    let mut buf = [0u8; 8];
    let file = File::open("foo.txt")?;

    // We now read exactly 8 bytes from the offset 10.
    file.read_exact_at(&mut buf, 10)?;
    println!("read {} bytes: {:?}", buf.len(), buf);
    Ok(())
}

fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

This is supported on Unix only.

Attempts to write an entire buffer starting from a given offset.

The offset is relative to the start of the file and thus independent from the current cursor.

The current file cursor is not affected by this function.

This method will continuously call write_at until there is no more data to be written or an error of non-ErrorKind::Interrupted kind is returned. This method will not return until the entire buffer has been successfully written or such an error occurs. The first error that is not of ErrorKind::Interrupted kind generated from this method will be returned.

Errors

This function will return the first error of non-ErrorKind::Interrupted kind that write_at returns.

Examples

use std::fs::File;
use std::io;
use std::os::unix::prelude::FileExt;

fn main() -> io::Result<()> {
    let file = File::open("foo.txt")?;

    // We now write at the offset 10.
    file.write_all_at(b"sushi", 10)?;
    Ok(())
}

Loading content...

Implementors

impl FileExt for File

fn read_at(&self, buf: &mut [u8], offset: u64) -> Result<usize>

This is supported on Unix only.

fn write_at(&self, buf: &[u8], offset: u64) -> Result<usize>

This is supported on Unix only.

fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>

This is supported on Unix only.

fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

This is supported on Unix only.

Loading content...