Struct File

pub struct File { /* private fields */ }

A reference to an open file on the filesystem.

This is a specialized version of std::fs::File for usage from the Tokio runtime.

An instance of a File can be read and/or written depending on what options it was opened with. Files also implement Seek to alter the logical cursor that the file contains internally.

Files are automatically closed when they go out of scope.

Examples

Create a new file and asynchronously write bytes to it:

extern crate tokio;

use tokio::prelude::{AsyncWrite, Future};

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|mut file| file.poll_write(b"hello, world!"))
        .map(|res| {
            println!("{:?}", res);
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

Read the contents of a file into a buffer

extern crate tokio;

use tokio::prelude::{AsyncRead, Future};

fn main() {
    let task = tokio::fs::File::open("foo.txt")
        .and_then(|mut file| {
            let mut contents = vec![];
            file.read_buf(&mut contents)
                .map(|res| {
                    println!("{:?}", res);
                })
        }).map_err(|err| eprintln!("IO error: {:?}", err));
    tokio::run(task);
}

Implementations

impl File

pub fn open<P>(path: P) -> OpenFuture<P>

where P: AsRef<Path> + Send + 'static,

Attempts to open a file in read-only mode.

See OpenOptions for more details.

Errors

OpenFuture results in an error if called from outside of the Tokio runtime or if the underlying open call results in an error.

Examples

use tokio::prelude::Future;
fn main() {
    let task = tokio::fs::File::open("foo.txt").and_then(|file| {
        // do something with the file ...
        file.metadata().map(|md| println!("{:?}", md))
    }).map_err(|e| {
        // handle errors
        eprintln!("IO error: {:?}", e);
    });
    tokio::run(task);
}

pub fn create<P>(path: P) -> CreateFuture<P>

where P: AsRef<Path> + Send + 'static,

Opens a file in write-only mode.

This function will create a file if it does not exist, and will truncate it if it does.

See OpenOptions for more details.

Errors

CreateFuture results in an error if called from outside of the Tokio runtime or if the underlying create call results in an error.

Examples

use tokio::prelude::Future;
fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|file| {
            // do something with the created file ...
            file.metadata().map(|md| println!("{:?}", md))
        }).map_err(|e| {
            // handle errors
            eprintln!("IO error: {:?}", e);
    });
    tokio::run(task);
}

pub fn from_std(std: StdFile) -> File

Convert a std::fs::File to a tokio_fs::File.

Examples

use std::fs::File;

fn main() {
    let std_file = File::open("foo.txt").unwrap();
    let file = tokio::fs::File::from_std(std_file);
}

pub fn poll_seek(&mut self, pos: SeekFrom) -> Poll<u64, Error>

Seek to an offset, in bytes, in a stream.

A seek beyond the end of a stream is allowed, but implementation defined.

If the seek operation completed successfully, this method returns the new position from the start of the stream. That position can be used later with SeekFrom::Start.

Errors

Seeking to a negative offset is considered an error.

Examples

use tokio::prelude::Future;
use std::io::SeekFrom;

fn main() {
    let task = tokio::fs::File::open("foo.txt")
        // move cursor 6 bytes from the start of the file
        .and_then(|mut file| file.poll_seek(SeekFrom::Start(6)))
        .map(|res| {
            println!("{:?}", res);
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn seek(self, pos: SeekFrom) -> SeekFuture

Seek to an offset, in bytes, in a stream.

Similar to poll_seek, but returning a Future.

This method consumes the File and returns it back when the future completes.

Examples

use tokio::prelude::Future;
use std::io::SeekFrom;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|file| file.seek(SeekFrom::Start(6)))
        .map(|file| {
            // handle returned file ..
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn poll_sync_all(&mut self) -> Poll<(), Error>

Attempts to sync all OS-internal metadata to disk.

This function will attempt to ensure that all in-core data reaches the filesystem before returning.

Examples

use tokio::prelude::{AsyncWrite, Future};

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|mut file| {
            file.poll_write(b"hello, world!")?;
            file.poll_sync_all()
        })
        .map(|res| {
            // handle returned result ..
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn poll_sync_data(&mut self) -> Poll<(), Error>

This function is similar to poll_sync_all, except that it may not synchronize file metadata to the filesystem.

This is intended for use cases that must synchronize content, but don’t need the metadata on disk. The goal of this method is to reduce disk operations.

Note that some platforms may simply implement this in terms of poll_sync_all.

Examples

use tokio::prelude::{AsyncWrite, Future};

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|mut file| {
            file.poll_write(b"hello, world!")?;
            file.poll_sync_data()
        })
        .map(|res| {
            // handle returned result ..
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn poll_set_len(&mut self, size: u64) -> Poll<(), Error>

Truncates or extends the underlying file, updating the size of this file to become size.

If the size is less than the current file’s size, then the file will be shrunk. If it is greater than the current file’s size, then the file will be extended to size and have all of the intermediate data filled in with 0s.

Errors

This function will return an error if the file is not opened for writing.

Examples

use tokio::prelude::Future;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|mut file| {
            file.poll_set_len(10)
        })
        .map(|res| {
            // handle returned result ..
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn metadata(self) -> MetadataFuture

Queries metadata about the underlying file.

Examples

use tokio::prelude::Future;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|file| file.metadata())
        .map(|metadata| {
            println!("{:?}", metadata);
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn poll_metadata(&mut self) -> Poll<Metadata, Error>

Queries metadata about the underlying file.

Examples

use tokio::prelude::Future;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|mut file| file.poll_metadata())
        .map(|metadata| {
            // metadata is of type Async::Ready<Metadata>
            println!("{:?}", metadata);
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn poll_try_clone(&mut self) -> Poll<File, Error>

Create a new File instance that shares the same underlying file handle as the existing File instance. Reads, writes, and seeks will affect both File instances simultaneously.

Examples

use tokio::prelude::Future;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|mut file| file.poll_try_clone())
        .map(|clone| {
            // do something with the clone
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn try_clone(self) -> CloneFuture

Create a new File instance that shares the same underlying file handle as the existing File instance. Reads, writes, and seeks will affect both File instances simultaneously.

Examples

use tokio::prelude::Future;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|file| {
            file.try_clone()
                .map(|(file, clone)| {
                    // do something with the file and the clone
                })
                .map_err(|(file, err)| {
                    // you get the original file back if there's an error
                    err
                })
        })
        .map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn poll_set_permissions(&mut self, perm: Permissions) -> Poll<(), Error>

Changes the permissions on the underlying file.

Platform-specific behavior

This function currently corresponds to the fchmod function on Unix and the SetFileInformationByHandle function on Windows. Note that, this may change in the future.

Errors

This function will return an error if the user lacks permission change attributes on the underlying file. It may also return an error in other os-specific unspecified cases.

Examples

use tokio::prelude::Future;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .and_then(|file| file.metadata())
        .map(|(mut file, metadata)| {
            let mut perms = metadata.permissions();
            perms.set_readonly(true);
            match file.poll_set_permissions(perms) {
                Err(e) => eprintln!("{}", e),
                _ => println!("permissions set!"),
            }
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

pub fn into_std(self) -> StdFile

Destructures the tokio_fs::File into a std::fs::File.

Panics

This function will panic if shutdown has been called.

Examples

use tokio::prelude::Future;

fn main() {
    let task = tokio::fs::File::create("foo.txt")
        .map(|file| {
            let std_file = file.into_std();
            // do something with the std::fs::File
        }).map_err(|err| eprintln!("IO error: {:?}", err));

    tokio::run(task);
}

Trait Implementations

impl AsyncRead for File

unsafe fn prepare_uninitialized_buffer(&self, _: &mut [u8]) -> bool

Prepares an uninitialized buffer to be safe to pass to read. Returns true if the supplied buffer was zeroed out.

fn poll_read(&mut self, buf: &mut [u8]) -> Result<Async<usize>, Error>

Attempt to read from the AsyncRead into buf.

fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error>

where B: BufMut, Self: Sized,

Pull some bytes from this source into the specified BufMut, returning how many bytes were read.

fn framed<T>(self, codec: T) -> Framed<Self, T>

where T: Encoder + Decoder, Self: Sized + AsyncWrite,

👎Deprecated since 0.1.7: Use tokio_codec::Decoder::framed instead

Provides a Stream and Sink interface for reading and writing to this I/O object, using Decode and Encode to read and write the raw data.

fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>)

where Self: Sized + AsyncWrite,

Helper method for splitting this read/write object into two halves.

impl AsyncWrite for File

fn shutdown(&mut self) -> Poll<(), Error>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write(&mut self, buf: &[u8]) -> Result<Async<usize>, Error>

Attempt to write bytes from buf into the object.

fn poll_flush(&mut self) -> Result<Async<()>, Error>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn write_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error>

where B: Buf, Self: Sized,

Write a Buf into this value, returning how many bytes were written.

impl Debug for File

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for File

fn drop(&mut self)

Executes the destructor for this type.

impl Read for File

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl Write for File

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

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.