diff --git a/src/libcore/rt/io/extensions.rs b/src/libcore/rt/io/extensions.rs
index 665b8a578e3..1c68934e80b 100644
--- a/src/libcore/rt/io/extensions.rs
+++ b/src/libcore/rt/io/extensions.rs
@@ -114,434 +114,208 @@ pub trait ReaderByteConversions {
     /// Reads `n` little-endian unsigned integer bytes.
     ///
     /// `n` must be between 1 and 8, inclusive.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_uint_n(&mut self, nbytes: uint) -> u64;
 
     /// Reads `n` little-endian signed integer bytes.
     ///
     /// `n` must be between 1 and 8, inclusive.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_int_n(&mut self, nbytes: uint) -> i64;
 
     /// Reads `n` big-endian unsigned integer bytes.
     ///
     /// `n` must be between 1 and 8, inclusive.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_uint_n(&mut self, nbytes: uint) -> u64;
 
     /// Reads `n` big-endian signed integer bytes.
     ///
     /// `n` must be between 1 and 8, inclusive.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_int_n(&mut self, nbytes: uint) -> i64;
 
     /// Reads a little-endian unsigned integer.
     ///
     /// The number of bytes returned is system-dependant.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_uint(&mut self) -> uint;
 
     /// Reads a little-endian integer.
     ///
     /// The number of bytes returned is system-dependant.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_int(&mut self) -> int;
 
     /// Reads a big-endian unsigned integer.
     ///
     /// The number of bytes returned is system-dependant.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_uint(&mut self) -> uint;
 
     /// Reads a big-endian integer.
     ///
     /// The number of bytes returned is system-dependant.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_int(&mut self) -> int;
 
     /// Reads a big-endian `u64`.
     ///
     /// `u64`s are 8 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_u64(&mut self) -> u64;
 
     /// Reads a big-endian `u32`.
     ///
     /// `u32`s are 4 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_u32(&mut self) -> u32;
 
     /// Reads a big-endian `u16`.
     ///
     /// `u16`s are 2 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_u16(&mut self) -> u16;
 
     /// Reads a big-endian `i64`.
     ///
     /// `i64`s are 8 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_i64(&mut self) -> i64;
 
     /// Reads a big-endian `i32`.
     ///
     /// `i32`s are 4 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_i32(&mut self) -> i32;
 
     /// Reads a big-endian `i16`.
     ///
     /// `i16`s are 2 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_i16(&mut self) -> i16;
 
     /// Reads a big-endian `f64`.
     ///
     /// `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_f64(&mut self) -> f64;
 
     /// Reads a big-endian `f32`.
     ///
     /// `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_be_f32(&mut self) -> f32;
 
     /// Reads a little-endian `u64`.
     ///
     /// `u64`s are 8 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_u64(&mut self) -> u64;
 
     /// Reads a little-endian `u32`.
     ///
     /// `u32`s are 4 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_u32(&mut self) -> u32;
 
     /// Reads a little-endian `u16`.
     ///
     /// `u16`s are 2 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_u16(&mut self) -> u16;
 
     /// Reads a little-endian `i64`.
     ///
     /// `i64`s are 8 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_i64(&mut self) -> i64;
 
     /// Reads a little-endian `i32`.
     ///
     /// `i32`s are 4 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_i32(&mut self) -> i32;
 
     /// Reads a little-endian `i16`.
     ///
     /// `i16`s are 2 bytes long.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_i16(&mut self) -> i16;
 
     /// Reads a little-endian `f64`.
     ///
     /// `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_f64(&mut self) -> f64;
 
     /// Reads a little-endian `f32`.
     ///
     /// `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_le_f32(&mut self) -> f32;
 
     /// Read a u8.
     ///
     /// `u8`s are 1 byte.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_u8(&mut self) -> u8;
 
     /// Read an i8.
     ///
     /// `i8`s are 1 byte.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error. Returns `0` if
-    /// the condition is handled.
     fn read_i8(&mut self) -> i8;
 
 }
 
 pub trait WriterByteConversions {
     /// Write the result of passing n through `int::to_str_bytes`.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_int(&mut self, n: int);
 
     /// Write the result of passing n through `uint::to_str_bytes`.
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_uint(&mut self, n: uint);
 
     /// Write a little-endian uint (number of bytes depends on system).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_uint(&mut self, n: uint);
 
     /// Write a little-endian int (number of bytes depends on system).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_int(&mut self, n: int);
 
     /// Write a big-endian uint (number of bytes depends on system).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_uint(&mut self, n: uint);
 
     /// Write a big-endian int (number of bytes depends on system).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_int(&mut self, n: int);
 
     /// Write a big-endian u64 (8 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_u64(&mut self, n: u64);
 
     /// Write a big-endian u32 (4 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_u32(&mut self, n: u32);
 
     /// Write a big-endian u16 (2 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_u16(&mut self, n: u16);
 
     /// Write a big-endian i64 (8 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_i64(&mut self, n: i64);
 
     /// Write a big-endian i32 (4 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_i32(&mut self, n: i32);
 
     /// Write a big-endian i16 (2 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_i16(&mut self, n: i16);
 
     /// Write a big-endian IEEE754 double-precision floating-point (8 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_f64(&mut self, f: f64);
 
     /// Write a big-endian IEEE754 single-precision floating-point (4 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_be_f32(&mut self, f: f32);
 
     /// Write a little-endian u64 (8 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_u64(&mut self, n: u64);
 
     /// Write a little-endian u32 (4 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_u32(&mut self, n: u32);
 
     /// Write a little-endian u16 (2 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_u16(&mut self, n: u16);
 
     /// Write a little-endian i64 (8 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_i64(&mut self, n: i64);
 
     /// Write a little-endian i32 (4 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_i32(&mut self, n: i32);
 
     /// Write a little-endian i16 (2 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_i16(&mut self, n: i16);
 
     /// Write a little-endian IEEE754 double-precision floating-point
     /// (8 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_f64(&mut self, f: f64);
 
     /// Write a litten-endian IEEE754 single-precision floating-point
     /// (4 bytes).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_le_f32(&mut self, f: f32);
 
     /// Write a u8 (1 byte).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_u8(&mut self, n: u8);
 
     /// Write a i8 (1 byte).
-    ///
-    /// # Failure
-    ///
-    /// Raises the `io_error` condition on error.
     fn write_i8(&mut self, n: i8);
 }
 
@@ -552,7 +326,7 @@ mod test {
     use cell::Cell;
     use rt::io::mem::MemReader;
     use rt::io::mock::*;
-    use rt::io::{io_error, placeholder_error};
+    use rt::io::{read_error, placeholder_error};
 
     #[test]
     fn read_byte() {
@@ -592,10 +366,10 @@ mod test {
     fn read_byte_error() {
         let mut reader = MockReader::new();
         reader.read = |_| {
-            io_error::cond.raise(placeholder_error());
+            read_error::cond.raise(placeholder_error());
             None
         };
-        do io_error::cond.trap(|_| {
+        do read_error::cond.trap(|_| {
         }).in {
             let byte = reader.read_byte();
             assert!(byte == None);
@@ -681,13 +455,13 @@ mod test {
                     buf[0] = 10;
                     Some(1)
                 } else {
-                    io_error::cond.raise(placeholder_error());
+                    read_error::cond.raise(placeholder_error());
                     None
                 }
             }
         };
         let mut buf = ~[8, 9];
-        do io_error::cond.trap(|_| { } ).in {
+        do read_error::cond.trap(|_| { } ).in {
             assert!(!reader.push_bytes(&mut buf, 4));
         }
         assert!(buf == ~[8, 9, 10]);
@@ -710,7 +484,7 @@ mod test {
                     buf[0] = 10;
                     Some(1)
                 } else {
-                    io_error::cond.raise(placeholder_error());
+                    read_error::cond.raise(placeholder_error());
                     None
                 }
             }
diff --git a/src/libcore/rt/io/mod.rs b/src/libcore/rt/io/mod.rs
index f3b0cd22c17..4ec5e83c382 100644
--- a/src/libcore/rt/io/mod.rs
+++ b/src/libcore/rt/io/mod.rs
@@ -350,17 +350,31 @@ condition! {
     /*pub*/ io_error: super::IoError -> ();
 }
 
+// XXX: Can't put doc comments on macros
+// Raised by `read` on error
+condition! {
+    // FIXME (#6009): uncomment `pub` after expansion support lands.
+    /*pub*/ read_error: super::IoError -> ();
+}
+
 pub trait Reader {
     /// Read bytes, up to the length of `buf` and place them in `buf`.
-    /// Returns the number of bytes read, or `None` on EOF. The number
-    /// of bytes read my be less than the number requested, even 0.
+    /// Returns the number of bytes read. The number of bytes read my
+    /// be less than the number requested, even 0. Returns `None` on EOF.
     ///
     /// # Failure
     ///
-    /// Raises the `io_error` condition on error, then returns `None`.
+    /// Raises the `read_error` condition on error. If the condition
+    /// is handled then no guarantee is made about the number of bytes
+    /// read and the contents of `buf`. If the condition is handled
+    /// returns `None` (XXX see below).
     ///
     /// # XXX
     ///
+    /// * Should raise error on eof
+    /// * If the condition is handled it should still return the bytes read,
+    ///   in which case there's no need to return Option
+    ///
     /// This doesn't take a `len` argument like the old `read`.
     /// Will people often need to slice their vectors to call this
     /// and will that be annoying?
diff --git a/src/libcore/rt/io/net/tcp.rs b/src/libcore/rt/io/net/tcp.rs
index 4a25334a2fc..f5b3c20f651 100644
--- a/src/libcore/rt/io/net/tcp.rs
+++ b/src/libcore/rt/io/net/tcp.rs
@@ -13,7 +13,7 @@ use result::{Ok, Err};
 use rt::sched::local_sched::unsafe_borrow_io;
 use rt::io::net::ip::IpAddr;
 use rt::io::{Reader, Writer, Listener};
-use rt::io::{io_error, EndOfFile};
+use rt::io::{io_error, read_error, EndOfFile};
 use rt::rtio::{IoFactory,
                RtioTcpListener, RtioTcpListenerObject,
                RtioTcpStream, RtioTcpStreamObject};
@@ -58,7 +58,7 @@ impl Reader for TcpStream {
             Err(ioerr) => {
                 // EOF is indicated by returning None
                 if ioerr.kind != EndOfFile {
-                    io_error::cond.raise(ioerr);
+                    read_error::cond.raise(ioerr);
                 }
                 return None;
             }
diff --git a/src/libcore/rt/io/option.rs b/src/libcore/rt/io/option.rs
index 95f8711cb5b..6ae747f8b4b 100644
--- a/src/libcore/rt/io/option.rs
+++ b/src/libcore/rt/io/option.rs
@@ -18,7 +18,7 @@
 
 use option::*;
 use super::{Reader, Writer, Listener};
-use super::{standard_error, PreviousIoError, io_error, IoError};
+use super::{standard_error, PreviousIoError, io_error, read_error, IoError};
 
 fn prev_io_error() -> IoError {
     standard_error(PreviousIoError)
@@ -45,7 +45,7 @@ impl<R: Reader> Reader for Option<R> {
         match *self {
             Some(ref mut reader) => reader.read(buf),
             None => {
-                io_error::cond.raise(prev_io_error());
+                read_error::cond.raise(prev_io_error());
                 None
             }
         }
@@ -79,7 +79,7 @@ mod test {
     use option::*;
     use super::super::mem::*;
     use rt::test::*;
-    use super::super::{PreviousIoError, io_error};
+    use super::super::{PreviousIoError, io_error, read_error};
 
     #[test]
     fn test_option_writer() {
@@ -133,7 +133,7 @@ mod test {
         let mut buf = [];
 
         let mut called = false;
-        do io_error::cond.trap(|err| {
+        do read_error::cond.trap(|err| {
             assert!(err.kind == PreviousIoError);
             called = true;
         }).in {