Attempts to open a file in read-only mode.

See theOpenOptions::open method for more details.

If you only need to read the entire file contents,considerstd::fs::read() orstd::fs::read_to_string() instead.

§Errors

This function will return an error ifpath does not already exist.Other errors may also be returned according toOpenOptions::open.

§Examples

usestd::fs::File;usestd::io::Read;fnmain() -> std::io::Result<()> {letmutf = File::open("foo.txt")?;letmutdata =vec![];    f.read_to_end(&mutdata)?;Ok(())}

Attempts to open a file in read-only mode with buffering.

See theOpenOptions::open method, theBufReader type,and theBufRead trait for more details.

If you only need to read the entire file contents,considerstd::fs::read() orstd::fs::read_to_string() instead.

§Errors

This function will return an error ifpath does not already exist,or if memory allocation fails for the new buffer.Other errors may also be returned according toOpenOptions::open.

§Examples

#![feature(file_buffered)]usestd::fs::File;usestd::io::BufRead;fnmain() -> std::io::Result<()> {letmutf = File::open_buffered("foo.txt")?;assert!(f.capacity() >0);for(line, i)inf.lines().zip(1..) {println!("{i:6}: {}", line?);    }Ok(())}

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.

Depending on the platform, this function may fail if thefull directory path does not exist.See theOpenOptions::open function for more details.

See alsostd::fs::write() for a simple function tocreate a file with some given data.

§Examples

usestd::fs::File;usestd::io::Write;fnmain() -> std::io::Result<()> {letmutf = File::create("foo.txt")?;    f.write_all(&1234_u32.to_be_bytes())?;Ok(())}

Opens a file in write-only mode with buffering.

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

Depending on the platform, this function may fail if thefull directory path does not exist.

See theOpenOptions::open method and theBufWriter type for more details.

See alsostd::fs::write() for a simple function tocreate a file with some given data.

§Examples

#![feature(file_buffered)]usestd::fs::File;usestd::io::Write;fnmain() -> std::io::Result<()> {letmutf = File::create_buffered("foo.txt")?;assert!(f.capacity() >0);foriin0..100{writeln!(&mutf,"{i}")?;    }    f.flush()?;Ok(())}

Creates a new file in read-write mode; error if the file exists.

This function will create a file if it does not exist, or return an error if it does. Thisway, if the call succeeds, the file returned is guaranteed to be new.If a file exists at the target location, creating a new file will fail withAlreadyExistsor another error based on the situation. SeeOpenOptions::open for anon-exhaustive list of likely errors.

This option is useful because it is atomic. Otherwise between checking whether a fileexists and creating a new one, the file may have been created by another process (a TOCTOUrace condition / attack).

This can also be written usingFile::options().read(true).write(true).create_new(true).open(...).

§Examples

usestd::fs::File;usestd::io::Write;fnmain() -> std::io::Result<()> {letmutf = File::create_new("foo.txt")?;    f.write_all("Hello, world!".as_bytes())?;Ok(())}

Returns a new OpenOptions object.

This function returns a new OpenOptions object that you can use toopen or create a file with specific options ifopen() orcreate()are not appropriate.

It is equivalent toOpenOptions::new(), but allows you to write morereadable code. Instead ofOpenOptions::new().append(true).open("example.log"),you can writeFile::options().append(true).open("example.log"). Thisalso avoids the need to importOpenOptions.

See theOpenOptions::new function for more details.

§Examples

usestd::fs::File;usestd::io::Write;fnmain() -> std::io::Result<()> {letmutf = File::options().append(true).open("example.log")?;writeln!(&mutf,"new line")?;Ok(())}

Attempts to sync all OS-internal file content and metadata to disk.

This function will attempt to ensure that all in-memory data reaches thefilesystem before returning.

This can be used to handle errors that would otherwise only be caughtwhen theFile is closed, as dropping aFile will ignore all errors.Note, however, thatsync_all is generally more expensive than closinga file by dropping it, because the latter is not required to block untilthe data has been written to the filesystem.

If synchronizing the metadata is not required, usesync_data instead.

§Examples

usestd::fs::File;usestd::io::prelude::*;fnmain() -> std::io::Result<()> {letmutf = File::create("foo.txt")?;    f.write_all(b"Hello, world!")?;    f.sync_all()?;Ok(())}

This function is similar tosync_all, except that it might notsynchronize file metadata to the filesystem.

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

Note that some platforms may simply implement this in terms ofsync_all.

§Examples

usestd::fs::File;usestd::io::prelude::*;fnmain() -> std::io::Result<()> {letmutf = File::create("foo.txt")?;    f.write_all(b"Hello, world!")?;    f.sync_data()?;Ok(())}

Acquire an exclusive lock on the file. Blocks until the lock can be acquired.

This acquires an exclusive lock; no other file handle to this file may acquire another lock.

This lock may be advisory or mandatory. This lock is meant to interact withlock,try_lock,lock_shared,try_lock_shared, andunlock. Its interactions withother methods, such asread andwrite are platform specific, and it may or may notcause non-lockholders to block.

If this file handle/descriptor, or a clone of it, already holds an lock the exact behavioris unspecified and platform dependent, including the possibility that it will deadlock.However, if this method returns, then an exclusive lock is held.

If the file not open for writing, it is unspecified whether this function returns an error.

The lock will be released when this file (along with any other file descriptors/handlesduplicated or inherited from it) is closed, or if theunlock method is called.

§Platform-specific behavior

This function currently corresponds to theflock function on Unix with theLOCK_EX flag,and theLockFileEx function on Windows with theLOCKFILE_EXCLUSIVE_LOCK flag. Note that,thismay change in the future.

On Windows, locking a file will fail if the file is opened only for append. To lock a file,open it with one of.read(true),.read(true).append(true), or.write(true).

§Examples

#![feature(file_lock)]usestd::fs::File;fnmain() -> std::io::Result<()> {letf = File::create("foo.txt")?;    f.lock()?;Ok(())}

Acquire a shared (non-exclusive) lock on the file. Blocks until the lock can be acquired.

This acquires a shared lock; more than one file handle may hold a shared lock, but none mayhold an exclusive lock at the same time.

This lock may be advisory or mandatory. This lock is meant to interact withlock,try_lock,lock_shared,try_lock_shared, andunlock. Its interactions withother methods, such asread andwrite are platform specific, and it may or may notcause non-lockholders to block.

If this file handle/descriptor, or a clone of it, already holds an lock, the exact behavioris unspecified and platform dependent, including the possibility that it will deadlock.However, if this method returns, then a shared lock is held.

The lock will be released when this file (along with any other file descriptors/handlesduplicated or inherited from it) is closed, or if theunlock method is called.

§Platform-specific behavior

This function currently corresponds to theflock function on Unix with theLOCK_SH flag,and theLockFileEx function on Windows. Note that, thismay change in the future.

On Windows, locking a file will fail if the file is opened only for append. To lock a file,open it with one of.read(true),.read(true).append(true), or.write(true).

§Examples

#![feature(file_lock)]usestd::fs::File;fnmain() -> std::io::Result<()> {letf = File::open("foo.txt")?;    f.lock_shared()?;Ok(())}

Try to acquire an exclusive lock on the file.

ReturnsErr(TryLockError::WouldBlock) if a different lock is already held on this file(via another handle/descriptor).

This acquires an exclusive lock; no other file handle to this file may acquire another lock.

This lock may be advisory or mandatory. This lock is meant to interact withlock,try_lock,lock_shared,try_lock_shared, andunlock. Its interactions withother methods, such asread andwrite are platform specific, and it may or may notcause non-lockholders to block.

If this file handle/descriptor, or a clone of it, already holds an lock, the exact behavioris unspecified and platform dependent, including the possibility that it will deadlock.However, if this method returnsOk(true), then it has acquired an exclusive lock.

If the file not open for writing, it is unspecified whether this function returns an error.

The lock will be released when this file (along with any other file descriptors/handlesduplicated or inherited from it) is closed, or if theunlock method is called.

§Platform-specific behavior

This function currently corresponds to theflock function on Unix with theLOCK_EX andLOCK_NB flags, and theLockFileEx function on Windows with theLOCKFILE_EXCLUSIVE_LOCKandLOCKFILE_FAIL_IMMEDIATELY flags. Note that, thismay change in the future.

On Windows, locking a file will fail if the file is opened only for append. To lock a file,open it with one of.read(true),.read(true).append(true), or.write(true).

§Examples

#![feature(file_lock)]usestd::fs::{File, TryLockError};fnmain() -> std::io::Result<()> {letf = File::create("foo.txt")?;matchf.try_lock() {Ok(_) => (),Err(TryLockError::WouldBlock) => (),// Lock not acquiredErr(TryLockError::Error(err)) =>returnErr(err),    }Ok(())}

Try to acquire a shared (non-exclusive) lock on the file.

ReturnsErr(TryLockError::WouldBlock) if a different lock is already held on this file(via another handle/descriptor).

This acquires a shared lock; more than one file handle may hold a shared lock, but none mayhold an exclusive lock at the same time.

This lock may be advisory or mandatory. This lock is meant to interact withlock,try_lock,lock_shared,try_lock_shared, andunlock. Its interactions withother methods, such asread andwrite are platform specific, and it may or may notcause non-lockholders to block.

If this file handle, or a clone of it, already holds an lock, the exact behavior isunspecified and platform dependent, including the possibility that it will deadlock.However, if this method returnsOk(true), then it has acquired a shared lock.

The lock will be released when this file (along with any other file descriptors/handlesduplicated or inherited from it) is closed, or if theunlock method is called.

§Platform-specific behavior

This function currently corresponds to theflock function on Unix with theLOCK_SH andLOCK_NB flags, and theLockFileEx function on Windows with theLOCKFILE_FAIL_IMMEDIATELY flag. Note that, thismay change in the future.

On Windows, locking a file will fail if the file is opened only for append. To lock a file,open it with one of.read(true),.read(true).append(true), or.write(true).

§Examples

#![feature(file_lock)]usestd::fs::{File, TryLockError};fnmain() -> std::io::Result<()> {letf = File::open("foo.txt")?;matchf.try_lock_shared() {Ok(_) => (),Err(TryLockError::WouldBlock) => (),// Lock not acquiredErr(TryLockError::Error(err)) =>returnErr(err),    }Ok(())}

Release all locks on the file.

All locks are released when the file (along with any other file descriptors/handlesduplicated or inherited from it) is closed. This method allows releasing locks withoutclosing the file.

If no lock is currently held via this file descriptor/handle, this method may return anerror, or may return successfully without taking any action.

§Platform-specific behavior

This function currently corresponds to theflock function on Unix with theLOCK_UN flag,and theUnlockFile function on Windows. Note that, thismay change in the future.

On Windows, locking a file will fail if the file is opened only for append. To lock a file,open it with one of.read(true),.read(true).append(true), or.write(true).

§Examples

#![feature(file_lock)]usestd::fs::File;fnmain() -> std::io::Result<()> {letf = File::open("foo.txt")?;    f.lock()?;    f.unlock()?;Ok(())}

Truncates or extends the underlying file, updating the size ofthis file to becomesize.

If thesize is less than the current file’s size, then the file willbe shrunk. If it is greater than the current file’s size, then the filewill be extended tosize and have all of the intermediate data filledin with 0s.

The file’s cursor isn’t changed. In particular, if the cursor was at theend and the file is shrunk using this operation, the cursor will now bepast the end.

§Errors

This function will return an error if the file is not opened for writing.Also,std::io::ErrorKind::InvalidInputwill be returned if the desired length would cause an overflow due tothe implementation specifics.

§Examples

usestd::fs::File;fnmain() -> std::io::Result<()> {letmutf = File::create("foo.txt")?;    f.set_len(10)?;Ok(())}

Note that this method alters the content of the underlying file, eventhough it takes&self rather than&mut self.

Queries metadata about the underlying file.

§Examples

usestd::fs::File;fnmain() -> std::io::Result<()> {letmutf = File::open("foo.txt")?;letmetadata = f.metadata()?;Ok(())}

Creates a newFile instance that shares the same underlying file handleas the existingFile instance. Reads, writes, and seeks will affectbothFile instances simultaneously.

§Examples

Creates two handles for a file namedfoo.txt:

usestd::fs::File;fnmain() -> std::io::Result<()> {letmutfile = File::open("foo.txt")?;letfile_copy = file.try_clone()?;Ok(())}

Assuming there’s a file namedfoo.txt with contentsabcdef\n, createtwo handles, seek one of them, and read the remaining bytes from theother handle:

usestd::fs::File;usestd::io::SeekFrom;usestd::io::prelude::*;fnmain() -> std::io::Result<()> {letmutfile = File::open("foo.txt")?;letmutfile_copy = file.try_clone()?;    file.seek(SeekFrom::Start(3))?;letmutcontents =vec![];    file_copy.read_to_end(&mutcontents)?;assert_eq!(contents,b"def\n");Ok(())}

Changes the permissions on the underlying file.

§Platform-specific behavior

This function currently corresponds to thefchmod function on Unix andtheSetFileInformationByHandle function on Windows. Note that, thismay change in the future.

§Errors

This function will return an error if the user lacks permission changeattributes on the underlying file. It may also return an error in otheros-specific unspecified cases.

§Examples

fnmain() -> std::io::Result<()> {usestd::fs::File;letfile = File::open("foo.txt")?;letmutperms = file.metadata()?.permissions();    perms.set_readonly(true);    file.set_permissions(perms)?;Ok(())}

Note that this method alters the permissions of the underlying file,even though it takes&self rather than&mut self.

Changes the timestamps of the underlying file.

§Platform-specific behavior

This function currently corresponds to thefutimens function on Unix (falling back tofutimes on macOS before 10.13) and theSetFileTime function on Windows. Note that thismay change in the future.

§Errors

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

This function may return an error if the operating system lacks support to change one ormore of the timestamps set in theFileTimes structure.

§Examples

fnmain() -> std::io::Result<()> {usestd::fs::{self, File, FileTimes};letsrc = fs::metadata("src")?;letdest = File::options().write(true).open("dest")?;lettimes = FileTimes::new()        .set_accessed(src.accessed()?)        .set_modified(src.modified()?);    dest.set_times(times)?;Ok(())}

Changes the modification time of the underlying file.

This is an alias forset_times(FileTimes::new().set_modified(time)).

Takes ownership of aFile’s underlying file descriptor.

Takes ownership of aFile’s underlying file handle.

Converts aFile into aStdio.

§Examples

File will be converted toStdio usingStdio::from under the hood.

usestd::fs::File;usestd::process::Command;// With the `foo.txt` file containing "Hello, world!"letfile = File::open("foo.txt")?;letreverse = Command::new("rev")    .stdin(file)// Implicit File conversion into a Stdio.output()?;assert_eq!(reverse.stdout,b"!dlrow ,olleH");

Returns aFile that takes ownership of the givenfile descriptor.

Returns aFile that takes ownership of the given handle.

Reads some bytes from the file.

SeeRead::read docs for more info.

§Platform-specific behavior

This function currently corresponds to theread function on Unix andtheNtReadFile function on Windows. Note that thismay change inthe future.

Likeread, except that it reads into a slice of buffers.

SeeRead::read_vectored docs for more info.

§Platform-specific behavior

This function currently corresponds to thereadv function on Unix andfalls back to theread implementation on Windows. Note that thismay change in the future.

Determines ifFile has an efficientread_vectored implementation.

SeeRead::is_read_vectored docs for more info.

§Platform-specific behavior

This function currently returnstrue on Unix anfalse on Windows.Note that thismay change in the future.

Writes some bytes to the file.

SeeWrite::write docs for more info.

§Platform-specific behavior

This function currently corresponds to thewrite function on Unix andtheNtWriteFile function on Windows. Note that thismay change inthe future.

Likewrite, except that it writes into a slice of buffers.

SeeWrite::write_vectored docs for more info.

§Platform-specific behavior

This function currently corresponds to thewritev function on Unixand falls back to thewrite implementation on Windows. Note that thismay change in the future.

Determines ifFile has an efficientwrite_vectored implementation.

SeeWrite::is_write_vectored docs for more info.

§Platform-specific behavior

This function currently returnstrue on Unix anfalse on Windows.Note that thismay change in the future.

Flushes the file, ensuring that all intermediately buffered contentsreach their destination.

SeeWrite::flush docs for more info.

§Platform-specific behavior

Since aFile structure doesn’t contain any buffers, this function iscurrently a no-op on Unix and Windows. Note that thismay change inthe future.

Returns the argument unchanged.

CallsU::from(self).

That is, this conversion is whatever the implementation ofFrom<T> for U chooses to do.