[][src]Struct tokio_fs::file::File

pub struct File { /* fields omitted */ }

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);
}

Methods

impl File[src]

pub fn open<P>(path: P) -> OpenFuture<P> where
    P: AsRef<Path> + Send + 'static, 
[src]

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, 
[src]

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[src]

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>[src]

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[src]

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>[src]

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>[src]

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>[src]

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[src]

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>[src]

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>[src]

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[src]

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>[src]

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[src]

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[src]

impl AsyncWrite for File[src]

impl Debug for File[src]

impl Drop for File[src]

impl Read for File[src]

impl Write for File[src]

Auto Trait Implementations

impl RefUnwindSafe for File

impl Send for File

impl Sync for File

impl Unpin for File

impl UnwindSafe for File

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<R> ReadBytesExt for R where
    R: Read + ?Sized
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<W> WriteBytesExt for W where
    W: Write + ?Sized
[src]