Struct std::old_io::fs::FileUnstable
[-] [+]
[src]
pub struct File { // some fields omitted }
Unconstrained file access type that exposes read and write operations
Can be constructed via File::open()
, File::create()
, and
File::open_mode()
.
Error
This type will return errors as an IoResult<T>
if operations are
attempted against it for which its underlying file descriptor was not
configured at creation time, via the FileAccess
parameter to
File::open_mode()
.
Methods
impl File
fn open_mode(path: &Path, mode: FileMode, access: FileAccess) -> IoResult<File>
Open a file at path
in the mode specified by the mode
and access
arguments
Example
fn main() { use std::old_io::{File, Open, ReadWrite}; let p = Path::new("/some/file/path.txt"); let file = match File::open_mode(&p, Open, ReadWrite) { Ok(f) => f, Err(e) => panic!("file error: {}", e), }; // do some stuff with that file // the file will be closed at the end of this block }use std::old_io::{File, Open, ReadWrite}; let p = Path::new("/some/file/path.txt"); let file = match File::open_mode(&p, Open, ReadWrite) { Ok(f) => f, Err(e) => panic!("file error: {}", e), }; // do some stuff with that file // the file will be closed at the end of this block
FileMode
and FileAccess
provide information about the permissions
context in which a given stream is created. More information about them
can be found in std::io
's docs. If a file is opened with Write
or ReadWrite
access, then it will be created if it does not already
exist.
Note that, with this function, a File
is returned regardless of the
access-limitations indicated by FileAccess
(e.g. calling write
on a
File
opened as Read
will return an error at runtime).
Error
This function will return an error under a number of different circumstances, to include but not limited to:
- Opening a file that does not exist with
Read
access. - Attempting to open a file with a
FileAccess
that the user lacks permissions for - Filesystem-level errors (full disk, etc)
fn open(path: &Path) -> IoResult<File>
Attempts to open a file in read-only mode. This function is equivalent to
File::open_mode(path, Open, Read)
, and will raise all of the same
errors that File::open_mode
does.
For more information, see the File::open_mode
function.
Example
fn main() { use std::old_io::File; let contents = File::open(&Path::new("foo.txt")).read_to_end(); }use std::old_io::File; let contents = File::open(&Path::new("foo.txt")).read_to_end();
fn create(path: &Path) -> IoResult<File>
Attempts to create a file in write-only mode. This function is
equivalent to File::open_mode(path, Truncate, Write)
, and will
raise all of the same errors that File::open_mode
does.
For more information, see the File::open_mode
function.
Example
fn main() { #![allow(unused_must_use)] use std::old_io::File; let mut f = File::create(&Path::new("foo.txt")); f.write(b"This is a sample file"); drop(f); ::std::old_io::fs::unlink(&Path::new("foo.txt")); }use std::old_io::File; let mut f = File::create(&Path::new("foo.txt")); f.write(b"This is a sample file");
fn path<'a>(&'a self) -> &'a Path
Returns the original path that was used to open this file.
fn fsync(&mut self) -> IoResult<()>
Synchronizes all modifications to this file to its permanent storage device. This will flush any internal buffers necessary to perform this operation.
fn datasync(&mut self) -> IoResult<()>
This function is similar to fsync
, 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.
fn truncate(&mut self, size: i64) -> IoResult<()>
Either truncates or extends the underlying file, updating the size of
this file to become size
. This is equivalent to unix's truncate
function.
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.
fn eof(&self) -> bool
Returns true if the stream has reached the end of the file.
If true, then this file will no longer continue to return data via
read
.
Note that the operating system will not return an EOF
indicator
until you have attempted to read past the end of the file, so if
you've read exactly the number of bytes in the file, this will
return false
, not true
.
fn stat(&self) -> IoResult<FileStat>
Queries information about the underlying file.