Struct TempFile

pub struct TempFile { /* private fields */ }

A named temporary file that will be cleaned automatically after the last reference to it is dropped.

Implementations

impl TempFile

pub async fn new() -> Result<Self, Error>

Creates a new temporary file in the default location. When the instance goes out of scope, the file will be deleted.

Example

let file = TempFile::new().await?;

// The file exists.
let file_path = file.file_path().clone();
assert!(fs::metadata(file_path.clone()).await.is_ok());

// Deletes the file.
drop(file);

// The file was removed.
assert!(fs::metadata(file_path).await.is_err());

pub async fn new_with_name<N: AsRef<str>>(name: N) -> Result<Self, Error>

Creates a new temporary file in the default location. When the instance goes out of scope, the file will be deleted.

Arguments

• name - The name of the file to create in the default temporary directory.

Example

let file = TempFile::new_with_name("temporary.file").await?;

// The file exists.
let file_path = file.file_path().clone();
assert!(fs::metadata(file_path.clone()).await.is_ok());

// Deletes the file.
drop(file);

// The file was removed.
assert!(fs::metadata(file_path).await.is_err());

pub async fn new_with_uuid(uuid: Uuid) -> Result<Self, Error>

Creates a new temporary file in the default location. When the instance goes out of scope, the file will be deleted.

Arguments

• uuid - A UUID to use as a suffix to the file name.

Example

let id = uuid::Uuid::new_v4();
let file = TempFile::new_with_uuid(id).await?;

// The file exists.
let file_path = file.file_path().clone();
assert!(fs::metadata(file_path.clone()).await.is_ok());

// Deletes the file.
drop(file);

// The file was removed.
assert!(fs::metadata(file_path).await.is_err());

pub async fn new_in<P: Borrow<PathBuf>>(dir: P) -> Result<Self, Error>

Creates a new temporary file in the specified location. When the instance goes out of scope, the file will be deleted.

Arguments

• dir - The directory to create the file in.

Example

let path = std::env::temp_dir();
let file = TempFile::new_in(path).await?;

// The file exists.
let file_path = file.file_path().clone();
assert!(fs::metadata(file_path.clone()).await.is_ok());

// Deletes the file.
drop(file);

// The file was removed.
assert!(fs::metadata(file_path).await.is_err());

pub async fn new_with_name_in<N: AsRef<str>, P: Borrow<PathBuf>>( name: N, dir: P, ) -> Result<Self, Error>

Creates a new temporary file in the specified location. When the instance goes out of scope, the file will be deleted.

Arguments

• dir - The directory to create the file in.
• name - The file name to use.

Example

let path = std::env::temp_dir();
let file = TempFile::new_with_name_in("temporary.file", path).await?;

// The file exists.
let file_path = file.file_path().clone();
assert!(fs::metadata(file_path.clone()).await.is_ok());

// Deletes the file.
drop(file);

// The file was removed.
assert!(fs::metadata(file_path).await.is_err());

pub async fn new_with_uuid_in<P: Borrow<PathBuf>>( uuid: Uuid, dir: P, ) -> Result<Self, Error>

Creates a new temporary file in the specified location. When the instance goes out of scope, the file will be deleted.

Arguments

• dir - The directory to create the file in.
• uuid - A UUID to use as a suffix to the file name.

Example

let path = std::env::temp_dir();
let id = uuid::Uuid::new_v4();
let file = TempFile::new_with_uuid_in(id, path).await?;

// The file exists.
let file_path = file.file_path().clone();
assert!(fs::metadata(file_path.clone()).await.is_ok());

// Deletes the file.
drop(file);

// The file was removed.
assert!(fs::metadata(file_path).await.is_err());

pub async fn from_existing( path: PathBuf, ownership: Ownership, ) -> Result<Self, Error>

Wraps a new instance of this type around an existing file. If ownership is set to Ownership::Borrowed, this method does not take ownership of the file, i.e. the file will not be deleted when the instance is dropped.

Arguments

• path - The path of the file to wrap.
• ownership - The ownership of the file.

pub fn file_path(&self) -> &PathBuf

Returns the path of the underlying temporary file.

pub async fn open_rw(&self) -> Result<TempFile, Error>

Opens a new TempFile instance in read-write mode.

pub async fn open_ro(&self) -> Result<TempFile, Error>

Opens a new TempFile instance in read-only mode.

pub async fn try_clone(&self) -> Result<TempFile, Error>

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

pub fn ownership(&self) -> Ownership

Determines the ownership of the temporary file.

Example

let file = TempFile::new().await?;
assert_eq!(file.ownership(), Ownership::Owned);

Methods from Deref<Target = File>

pub async fn sync_all(&self) -> Result<(), 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::fs::File;
use tokio::io::AsyncWriteExt;

let mut file = File::create("foo.txt").await?;
file.write_all(b"hello, world!").await?;
file.sync_all().await?;

The write_all method is defined on the AsyncWriteExt trait.

pub async fn sync_data(&self) -> Result<(), Error>

This function is similar to 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 sync_all.

Examples

use tokio::fs::File;
use tokio::io::AsyncWriteExt;

let mut file = File::create("foo.txt").await?;
file.write_all(b"hello, world!").await?;
file.sync_data().await?;

The write_all method is defined on the AsyncWriteExt trait.

pub async fn set_len(&self, size: u64) -> Result<(), 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::fs::File;
use tokio::io::AsyncWriteExt;

let mut file = File::create("foo.txt").await?;
file.write_all(b"hello, world!").await?;
file.set_len(10).await?;

The write_all method is defined on the AsyncWriteExt trait.

pub async fn metadata(&self) -> Result<Metadata, Error>

Queries metadata about the underlying file.

Examples

use tokio::fs::File;

let file = File::open("foo.txt").await?;
let metadata = file.metadata().await?;

println!("{:?}", metadata);

pub async fn try_clone(&self) -> Result<File, Error>

Creates 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::fs::File;

let file = File::open("foo.txt").await?;
let file_clone = file.try_clone().await?;

pub async fn set_permissions(&self, perm: Permissions) -> Result<(), 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::fs::File;

let file = File::open("foo.txt").await?;
let mut perms = file.metadata().await?.permissions();
perms.set_readonly(true);
file.set_permissions(perms).await?;

pub fn set_max_buf_size(&mut self, max_buf_size: usize)

Set the maximum buffer size for the underlying AsyncRead / AsyncWrite operation.

Although Tokio uses a sensible default value for this buffer size, this function would be useful for changing that default depending on the situation.

Examples

use tokio::fs::File;
use tokio::io::AsyncWriteExt;

let mut file = File::open("foo.txt").await?;

// Set maximum buffer size to 8 MiB
file.set_max_buf_size(8 * 1024 * 1024);

let mut buf = vec![1; 1024 * 1024 * 1024];

// Write the 1 GiB buffer in chunks up to 8 MiB each.
file.write_all(&mut buf).await?;

Trait Implementations

impl AsRef<File> for TempFile

fn as_ref(&self) -> &File

Converts this type into a shared reference of the (usually inferred) input type.

impl AsyncRead for TempFile

Forwarding AsyncWrite to the embedded TempFile

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl AsyncSeek for TempFile

Forwarding AsyncSeek to the embedded File

fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Result<()>

Attempts to seek to an offset, in bytes, in a stream.

fn poll_complete( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<u64>>

Waits for a seek operation to complete.

impl AsyncWrite for TempFile

Forwarding AsyncWrite to the embedded File

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from buf into the object.

fn poll_flush( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

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

fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

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

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

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

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Borrow<File> for TempFile

fn borrow(&self) -> &File

Immutably borrows from an owned value.

impl BorrowMut<File> for TempFile

fn borrow_mut(&mut self) -> &mut File

Mutably borrows from an owned value.

impl Debug for TempFile

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

Formats the value using the given formatter.

impl Deref for TempFile

Allows implicit treatment of TempFile as a File.

type Target = File

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for TempFile

Allows implicit treatment of TempFile as a mutable File.

fn deref_mut(&mut self) -> &mut File

Mutably dereferences the value.

impl Drop for TempFile

Ensures the file handles are closed before the core reference is freed. If the core reference would be freed while handles are still open, it is possible that the underlying file cannot be deleted.

fn drop(&mut self)

Executes the destructor for this type.