Open a file at path in the mode specified by the mode and access arguments

Example

use std::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) => fail!("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 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)

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

use std::io::File;

let contents = File::open(&Path::new("foo.txt")).read_to_end();

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

use std::io::File;

let mut f = File::create(&Path::new("foo.txt"));
f.write(bytes!("This is a sample file"));

Returns the original path which was used to open this file.

Synchronizes all modifications to this file to its permanent storage device. This will flush any internal buffers necessary to perform this operation.

This function is similar to fsync, except that it may not synchronize file metadata to the filesystem. This is intended for use case which must synchronize content, but don't need the metadata on disk. The goal of this method is to reduce disk operations.

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.

Tests whether this stream has reached EOF.

If true, then this file will no longer continue to return data via read.

Read bytes, up to the length of buf and place them in buf. Returns the number of bytes read. The number of bytes read my be less than the number requested, even 0. Returns Err on EOF.

Error

If an error occurs during this I/O operation, then it is returned as Err(IoError). Note that end-of-file is considered an error, and can be inspected for in the error's kind field. Also note that reading 0 bytes is not considered an error in all circumstances

Reads a single byte. Returns Err on EOF.

Fills the provided slice with bytes from this reader

This will continue to call read until the slice has been completely filled with bytes.

Error

If an error occurs at any point, that error is returned, and no further bytes are read.

Reads exactly len bytes and appends them to a vector.

May push fewer than the requested number of bytes on error or EOF. If Ok(()) is returned, then all of the requested bytes were pushed on to the vector, otherwise the amount len bytes couldn't be read (an error was encountered), and the error is returned.

Reads exactly len bytes and gives you back a new vector of length len

Error

Fails with the same conditions as read. Additionally returns error on EOF. Note that if an error is returned, then some number of bytes may have already been consumed from the underlying reader, and they are lost (not returned as part of the error). If this is unacceptable, then it is recommended to use the push_exact or read methods.

Reads all remaining bytes from the stream.

Error

Returns any non-EOF error immediately. Previously read bytes are discarded when an error is returned.

When EOF is encountered, all bytes read up to that point are returned.

Reads all of the remaining bytes of this stream, interpreting them as a UTF-8 encoded stream. The corresponding string is returned.

Error

This function returns all of the same errors as read_to_end with an additional error if the reader's contents are not a valid sequence of UTF-8 bytes.

Create an iterator that reads a single byte on each iteration, until EOF.

Error

Any error other than EndOfFile that is produced by the underlying Reader is returned by the iterator and should be handled by the caller.

Reads n little-endian unsigned integer bytes.

n must be between 1 and 8, inclusive.

Reads n little-endian signed integer bytes.

n must be between 1 and 8, inclusive.

Reads n big-endian unsigned integer bytes.

n must be between 1 and 8, inclusive.

Reads n big-endian signed integer bytes.

n must be between 1 and 8, inclusive.

Reads a little-endian unsigned integer.

The number of bytes returned is system-dependant.

Reads a little-endian integer.

The number of bytes returned is system-dependant.

Reads a big-endian unsigned integer.

The number of bytes returned is system-dependant.

Reads a big-endian integer.

The number of bytes returned is system-dependant.

Reads a big-endian u64.

u64s are 8 bytes long.

Reads a big-endian u32.

u32s are 4 bytes long.

Reads a big-endian u16.

u16s are 2 bytes long.

Reads a big-endian i64.

i64s are 8 bytes long.

Reads a big-endian i32.

i32s are 4 bytes long.

Reads a big-endian i16.

i16s are 2 bytes long.

Reads a big-endian f64.

f64s are 8 byte, IEEE754 double-precision floating point numbers.

Reads a big-endian f32.

f32s are 4 byte, IEEE754 single-precision floating point numbers.

Reads a little-endian u64.

u64s are 8 bytes long.

Reads a little-endian u32.

u32s are 4 bytes long.

Reads a little-endian u16.

u16s are 2 bytes long.

Reads a little-endian i64.

i64s are 8 bytes long.

Reads a little-endian i32.

i32s are 4 bytes long.

Reads a little-endian i16.

i16s are 2 bytes long.

Reads a little-endian f64.

f64s are 8 byte, IEEE754 double-precision floating point numbers.

Reads a little-endian f32.

f32s are 4 byte, IEEE754 single-precision floating point numbers.

Read a u8.

u8s are 1 byte.

Read an i8.

i8s are 1 byte.

Creates a wrapper around a mutable reference to the reader.

This is useful to allow applying adaptors while still retaining ownership of the original value.

Write the entirety of a given buffer

Errors

If an error happens during the I/O operation, the error is returned as Err. Note that it is considered an error if the entire buffer could not be written, and if an error is returned then it is unknown how much data (if any) was actually written.

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

This is by default a no-op and implementers of the Writer trait should decide whether their stream needs to be buffered or not.

Write a rust string into this sink.

The bytes written will be the UTF-8 encoded version of the input string. If other encodings are desired, it is recommended to compose this stream with another performing the conversion, or to use write with a converted byte-array instead.

Writes a string into this sink, and then writes a literal newline (\n) byte afterwards. Note that the writing of the newline is not atomic in the sense that the call to write is invoked twice (once with the string and once with a newline character).

If other encodings or line ending flavors are desired, it is recommended that the write method is used specifically instead.

Write a single char, encoded as UTF-8.

Write the result of passing n through int::to_str_bytes.

Write the result of passing n through uint::to_str_bytes.

Write a little-endian uint (number of bytes depends on system).

Write a little-endian int (number of bytes depends on system).

Write a big-endian uint (number of bytes depends on system).

Write a big-endian int (number of bytes depends on system).

Write a big-endian u64 (8 bytes).

Write a big-endian u32 (4 bytes).

Write a big-endian u16 (2 bytes).

Write a big-endian i64 (8 bytes).

Write a big-endian i32 (4 bytes).

Write a big-endian i16 (2 bytes).

Write a big-endian IEEE754 double-precision floating-point (8 bytes).

Write a big-endian IEEE754 single-precision floating-point (4 bytes).

Write a little-endian u64 (8 bytes).

Write a little-endian u32 (4 bytes).

Write a little-endian u16 (2 bytes).

Write a little-endian i64 (8 bytes).

Write a little-endian i32 (4 bytes).

Write a little-endian i16 (2 bytes).

Write a little-endian IEEE754 double-precision floating-point (8 bytes).

Write a little-endian IEEE754 single-precision floating-point (4 bytes).

Write a u8 (1 byte).

Write a i8 (1 byte).

Creates a wrapper around a mutable reference to the writer.

This is useful to allow applying wrappers while still retaining ownership of the original value.

Return position of file cursor in the stream

Seek to an offset in a stream

A successful seek clears the EOF indicator. Seeking beyond EOF is allowed, but seeking before position 0 is not allowed.

Errors

• Seeking to a negative offset is considered an error
• Seeking past the end of the stream does not modify the underlying stream, but the next write may cause the previous data to be filled in with a bit pattern.