1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 // FIXME: cover these topics:
12 // path, reader, writer, stream, raii (close not needed),
13 // stdio, print!, println!, file access, process spawning,
17 /*! I/O, including files, networking, timers, and processes
19 `std::io` provides Rust's basic I/O types,
20 for reading and writing to files, TCP, UDP,
21 and other types of sockets and pipes,
22 manipulating the file system, spawning processes and signal handling.
26 Some examples of obvious things you might want to do
28 * Read lines from stdin
33 for line in io::stdin().lines() {
34 print!("{}", line.unwrap());
38 * Read a complete file
43 let contents = File::open(&Path::new("message.txt")).read_to_end();
46 * Write a line to a file
49 # #![allow(unused_must_use)]
52 let mut file = File::create(&Path::new("message.txt"));
53 file.write(bytes!("hello, file!\n"));
55 # ::std::io::fs::unlink(&Path::new("message.txt"));
58 * Iterate over the lines of a file
61 use std::io::BufferedReader;
64 let path = Path::new("message.txt");
65 let mut file = BufferedReader::new(File::open(&path));
66 for line in file.lines() {
67 print!("{}", line.unwrap());
71 * Pull the lines of a file into a vector of strings
74 use std::io::BufferedReader;
77 let path = Path::new("message.txt");
78 let mut file = BufferedReader::new(File::open(&path));
79 let lines: Vec<String> = file.lines().map(|x| x.unwrap()).collect();
82 * Make a simple TCP client connection and request
85 # #![allow(unused_must_use)]
86 use std::io::net::tcp::TcpStream;
88 # // connection doesn't fail if a server is running on 8080
89 # // locally, we still want to be type checking this code, so lets
90 # // just stop it running (#11576)
92 let mut socket = TcpStream::connect("127.0.0.1", 8080).unwrap();
93 socket.write(bytes!("GET / HTTP/1.0\n\n"));
94 let response = socket.read_to_end();
98 * Make a simple TCP server
103 # #![allow(dead_code)]
104 use std::io::{TcpListener, TcpStream};
105 use std::io::{Acceptor, Listener};
107 let listener = TcpListener::bind("127.0.0.1", 80);
109 // bind the listener to the specified address
110 let mut acceptor = listener.listen();
112 fn handle_client(mut stream: TcpStream) {
114 # &mut stream; // silence unused mutability/variable warning
116 // accept connections and process them, spawning a new tasks for each one
117 for stream in acceptor.incoming() {
119 Err(e) => { /* connection failed */ }
120 Ok(stream) => spawn(proc() {
121 // connection succeeded
122 handle_client(stream)
127 // close the socket server
135 I/O is an area where nearly every operation can result in unexpected
136 errors. Errors should be painfully visible when they happen, and handling them
137 should be easy to work with. It should be convenient to handle specific I/O
138 errors, and it should also be convenient to not deal with I/O errors.
140 Rust's I/O employs a combination of techniques to reduce boilerplate
141 while still providing feedback about errors. The basic strategy:
143 * All I/O operations return `IoResult<T>` which is equivalent to
144 `Result<T, IoError>`. The `Result` type is defined in the `std::result`
146 * If the `Result` type goes unused, then the compiler will by default emit a
147 warning about the unused result. This is because `Result` has the
148 `#[must_use]` attribute.
149 * Common traits are implemented for `IoResult`, e.g.
150 `impl<R: Reader> Reader for IoResult<R>`, so that error values do not have
151 to be 'unwrapped' before use.
153 These features combine in the API to allow for expressions like
154 `File::create(&Path::new("diary.txt")).write(bytes!("Met a girl.\n"))`
155 without having to worry about whether "diary.txt" exists or whether
156 the write succeeds. As written, if either `new` or `write_line`
157 encounters an error then the result of the entire expression will
160 If you wanted to handle the error though you might write:
163 # #![allow(unused_must_use)]
166 match File::create(&Path::new("diary.txt")).write(bytes!("Met a girl.\n")) {
167 Ok(()) => (), // succeeded
168 Err(e) => println!("failed to write to my diary: {}", e),
171 # ::std::io::fs::unlink(&Path::new("diary.txt"));
174 So what actually happens if `create` encounters an error?
175 It's important to know that what `new` returns is not a `File`
176 but an `IoResult<File>`. If the file does not open, then `new` will simply
177 return `Err(..)`. Because there is an implementation of `Writer` (the trait
178 required ultimately required for types to implement `write_line`) there is no
179 need to inspect or unwrap the `IoResult<File>` and we simply call `write_line`
180 on it. If `new` returned an `Err(..)` then the followup call to `write_line`
181 will also return an error.
185 Explicit pattern matching on `IoResult`s can get quite verbose, especially
186 when performing many I/O operations. Some examples (like those above) are
187 alleviated with extra methods implemented on `IoResult`, but others have more
188 complex interdependencies among each I/O operation.
190 The `try!` macro from `std::macros` is provided as a method of early-return
191 inside `Result`-returning functions. It expands to an early-return on `Err`
192 and otherwise unwraps the contained `Ok` value.
194 If you wanted to read several `u32`s from a file and return their product:
197 use std::io::{File, IoResult};
199 fn file_product(p: &Path) -> IoResult<u32> {
200 let mut f = File::open(p);
201 let x1 = try!(f.read_le_u32());
202 let x2 = try!(f.read_le_u32());
207 match file_product(&Path::new("numbers.bin")) {
208 Ok(x) => println!("{}", x),
209 Err(e) => println!("Failed to read numbers!")
213 With `try!` in `file_product`, each `read_le_u32` need not be directly
214 concerned with error handling; instead its caller is responsible for
215 responding to errors that may occur while attempting to read the numbers.
219 #![deny(unused_must_use)]
222 use collections::Collection;
228 use ops::{BitOr, BitAnd, Sub, Not};
229 use option::{Option, Some, None};
232 use result::{Ok, Err, Result};
234 use slice::{Vector, MutableVector, ImmutableVector};
235 use str::{Str, StrSlice, StrAllocating};
242 pub use self::stdio::stdin;
243 pub use self::stdio::stdout;
244 pub use self::stdio::stderr;
245 pub use self::stdio::print;
246 pub use self::stdio::println;
248 pub use self::fs::File;
249 pub use self::timer::Timer;
250 pub use self::net::ip::IpAddr;
251 pub use self::net::tcp::TcpListener;
252 pub use self::net::tcp::TcpStream;
253 pub use self::net::udp::UdpStream;
254 pub use self::pipe::PipeStream;
255 pub use self::process::{Process, Command};
256 pub use self::tempfile::TempDir;
258 pub use self::mem::{MemReader, BufReader, MemWriter, BufWriter};
259 pub use self::buffered::{BufferedReader, BufferedWriter, BufferedStream,
261 pub use self::comm_adapters::{ChanReader, ChanWriter};
263 // this comes first to get the iotest! macro
281 /// The default buffer size for various I/O operations
282 // libuv recommends 64k buffers to maximize throughput
283 // https://groups.google.com/forum/#!topic/libuv/oQO1HJAIDdA
284 static DEFAULT_BUF_SIZE: uint = 1024 * 64;
286 /// A convenient typedef of the return value of any I/O action.
287 pub type IoResult<T> = Result<T, IoError>;
289 /// The type passed to I/O condition handlers to indicate error
293 /// Is something like this sufficient? It's kind of archaic
294 #[deriving(PartialEq, Clone)]
296 /// An enumeration which can be matched against for determining the flavor
298 pub kind: IoErrorKind,
299 /// A human-readable description about the error
300 pub desc: &'static str,
301 /// Detailed information about this error, not always available
302 pub detail: Option<String>
306 /// Convert an `errno` value into an `IoError`.
308 /// If `detail` is `true`, the `detail` field of the `IoError`
309 /// struct is filled with an allocated string describing the error
310 /// in more detail, retrieved from the operating system.
311 pub fn from_errno(errno: uint, detail: bool) -> IoError {
314 fn get_err(errno: i32) -> (IoErrorKind, &'static str) {
316 libc::EOF => (EndOfFile, "end of file"),
317 libc::ERROR_NO_DATA => (BrokenPipe, "the pipe is being closed"),
318 libc::ERROR_FILE_NOT_FOUND => (FileNotFound, "file not found"),
319 libc::ERROR_INVALID_NAME => (InvalidInput, "invalid file name"),
320 libc::WSAECONNREFUSED => (ConnectionRefused, "connection refused"),
321 libc::WSAECONNRESET => (ConnectionReset, "connection reset"),
322 libc::ERROR_ACCESS_DENIED | libc::WSAEACCES =>
323 (PermissionDenied, "permission denied"),
324 libc::WSAEWOULDBLOCK => {
325 (ResourceUnavailable, "resource temporarily unavailable")
327 libc::WSAENOTCONN => (NotConnected, "not connected"),
328 libc::WSAECONNABORTED => (ConnectionAborted, "connection aborted"),
329 libc::WSAEADDRNOTAVAIL => (ConnectionRefused, "address not available"),
330 libc::WSAEADDRINUSE => (ConnectionRefused, "address in use"),
331 libc::ERROR_BROKEN_PIPE => (EndOfFile, "the pipe has ended"),
332 libc::ERROR_OPERATION_ABORTED =>
333 (TimedOut, "operation timed out"),
334 libc::WSAEINVAL => (InvalidInput, "invalid argument"),
335 libc::ERROR_CALL_NOT_IMPLEMENTED =>
336 (IoUnavailable, "function not implemented"),
337 libc::ERROR_INVALID_HANDLE =>
338 (MismatchedFileTypeForOperation,
339 "invalid handle provided to function"),
340 libc::ERROR_NOTHING_TO_TERMINATE =>
341 (InvalidInput, "no process to kill"),
343 // libuv maps this error code to EISDIR. we do too. if it is found
344 // to be incorrect, we can add in some more machinery to only
345 // return this message when ERROR_INVALID_FUNCTION after certain
347 libc::ERROR_INVALID_FUNCTION => (InvalidInput,
348 "illegal operation on a directory"),
350 _ => (OtherIoError, "unknown error")
355 fn get_err(errno: i32) -> (IoErrorKind, &'static str) {
356 // FIXME: this should probably be a bit more descriptive...
358 libc::EOF => (EndOfFile, "end of file"),
359 libc::ECONNREFUSED => (ConnectionRefused, "connection refused"),
360 libc::ECONNRESET => (ConnectionReset, "connection reset"),
361 libc::EPERM | libc::EACCES =>
362 (PermissionDenied, "permission denied"),
363 libc::EPIPE => (BrokenPipe, "broken pipe"),
364 libc::ENOTCONN => (NotConnected, "not connected"),
365 libc::ECONNABORTED => (ConnectionAborted, "connection aborted"),
366 libc::EADDRNOTAVAIL => (ConnectionRefused, "address not available"),
367 libc::EADDRINUSE => (ConnectionRefused, "address in use"),
368 libc::ENOENT => (FileNotFound, "no such file or directory"),
369 libc::EISDIR => (InvalidInput, "illegal operation on a directory"),
370 libc::ENOSYS => (IoUnavailable, "function not implemented"),
371 libc::EINVAL => (InvalidInput, "invalid argument"),
373 (MismatchedFileTypeForOperation,
374 "file descriptor is not a TTY"),
375 libc::ETIMEDOUT => (TimedOut, "operation timed out"),
376 libc::ECANCELED => (TimedOut, "operation aborted"),
378 // These two constants can have the same value on some systems,
379 // but different values on others, so we can't use a match
381 x if x == libc::EAGAIN || x == libc::EWOULDBLOCK =>
382 (ResourceUnavailable, "resource temporarily unavailable"),
384 _ => (OtherIoError, "unknown error")
388 let (kind, desc) = get_err(errno as i32);
392 detail: if detail && kind == OtherIoError {
393 Some(os::error_string(errno).as_slice().chars().map(|c| c.to_lowercase()).collect())
400 /// Retrieve the last error to occur as a (detailed) IoError.
402 /// This uses the OS `errno`, and so there should not be any task
403 /// descheduling or migration (other than that performed by the
404 /// operating system) between the call(s) for which errors are
405 /// being checked and the call of this function.
406 pub fn last_error() -> IoError {
407 IoError::from_errno(os::errno() as uint, true)
410 fn from_rtio_error(err: rtio::IoError) -> IoError {
411 let rtio::IoError { code, extra, detail } = err;
412 let mut ioerr = IoError::from_errno(code, false);
413 ioerr.detail = detail;
414 ioerr.kind = match ioerr.kind {
415 TimedOut if extra > 0 => ShortWrite(extra),
422 impl fmt::Show for IoError {
423 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
425 IoError { kind: OtherIoError, desc: "unknown error", detail: Some(ref detail) } =>
426 write!(fmt, "{}", detail),
427 IoError { detail: None, desc, .. } =>
428 write!(fmt, "{}", desc),
429 IoError { detail: Some(ref detail), desc, .. } =>
430 write!(fmt, "{} ({})", desc, detail)
435 /// A list specifying general categories of I/O error.
436 #[deriving(PartialEq, Clone, Show)]
437 pub enum IoErrorKind {
438 /// Any I/O error not part of this list.
440 /// The operation could not complete because end of file was reached.
442 /// The file was not found.
444 /// The file permissions disallowed access to this file.
446 /// A network connection failed for some reason not specified in this list.
448 /// The network operation failed because the network connection was closed.
450 /// The connection was refused by the remote server.
452 /// The connection was reset by the remote server.
454 /// The connection was aborted (terminated) by the remote server.
456 /// The network operation failed because it was not connected yet.
458 /// The operation failed because a pipe was closed.
460 /// A file already existed with that name.
462 /// No file exists at that location.
464 /// The path did not specify the type of file that this operation required. For example,
465 /// attempting to copy a directory with the `fs::copy()` operation will fail with this error.
466 MismatchedFileTypeForOperation,
467 /// The operation temporarily failed (for example, because a signal was received), and retrying
470 /// No I/O functionality is available for this task.
472 /// A parameter was incorrect in a way that caused an I/O error not part of this list.
474 /// The I/O operation's timeout expired, causing it to be canceled.
476 /// This write operation failed to write all of its data.
478 /// Normally the write() method on a Writer guarantees that all of its data
479 /// has been written, but some operations may be terminated after only
480 /// partially writing some data. An example of this is a timed out write
481 /// which successfully wrote a known number of bytes, but bailed out after
484 /// The payload contained as part of this variant is the number of bytes
485 /// which are known to have been successfully written.
487 /// The Reader returned 0 bytes from `read()` too many times.
491 /// A trait that lets you add a `detail` to an IoError easily
492 trait UpdateIoError<T> {
493 /// Returns an IoError with updated description and detail
494 fn update_err(self, desc: &'static str, detail: |&IoError| -> String) -> Self;
496 /// Returns an IoError with updated detail
497 fn update_detail(self, detail: |&IoError| -> String) -> Self;
499 /// Returns an IoError with update description
500 fn update_desc(self, desc: &'static str) -> Self;
503 impl<T> UpdateIoError<T> for IoResult<T> {
504 fn update_err(self, desc: &'static str, detail: |&IoError| -> String) -> IoResult<T> {
505 self.map_err(|mut e| {
506 let detail = detail(&e);
508 e.detail = Some(detail);
513 fn update_detail(self, detail: |&IoError| -> String) -> IoResult<T> {
514 self.map_err(|mut e| { e.detail = Some(detail(&e)); e })
517 fn update_desc(self, desc: &'static str) -> IoResult<T> {
518 self.map_err(|mut e| { e.desc = desc; e })
522 static NO_PROGRESS_LIMIT: uint = 1000;
524 /// A trait for objects which are byte-oriented streams. Readers are defined by
525 /// one method, `read`. This function will block until data is available,
526 /// filling in the provided buffer with any data read.
528 /// Readers are intended to be composable with one another. Many objects
529 /// throughout the I/O and related libraries take and provide types which
530 /// implement the `Reader` trait.
533 // Only method which need to get implemented for this trait
535 /// Read bytes, up to the length of `buf` and place them in `buf`.
536 /// Returns the number of bytes read. The number of bytes read may
537 /// be less than the number requested, even 0. Returns `Err` on EOF.
541 /// If an error occurs during this I/O operation, then it is returned as
542 /// `Err(IoError)`. Note that end-of-file is considered an error, and can be
543 /// inspected for in the error's `kind` field. Also note that reading 0
544 /// bytes is not considered an error in all circumstances
546 /// # Implementation Note
548 /// When implementing this method on a new Reader, you are strongly encouraged
549 /// not to return 0 if you can avoid it.
550 fn read(&mut self, buf: &mut [u8]) -> IoResult<uint>;
552 // Convenient helper methods based on the above methods
554 /// Reads at least `min` bytes and places them in `buf`.
555 /// Returns the number of bytes read.
557 /// This will continue to call `read` until at least `min` bytes have been
558 /// read. If `read` returns 0 too many times, `NoProgress` will be
563 /// If an error occurs at any point, that error is returned, and no further
565 fn read_at_least(&mut self, min: uint, buf: &mut [u8]) -> IoResult<uint> {
568 detail: Some("the buffer is too short".to_string()),
569 ..standard_error(InvalidInput)
576 match self.read(buf.mut_slice_from(read)) {
579 if zeroes >= NO_PROGRESS_LIMIT {
580 return Err(standard_error(NoProgress));
587 err@Err(_) => return err
594 /// Reads a single byte. Returns `Err` on EOF.
595 fn read_byte(&mut self) -> IoResult<u8> {
597 try!(self.read_at_least(1, buf));
601 /// Reads up to `len` bytes and appends them to a vector.
602 /// Returns the number of bytes read. The number of bytes read may be
603 /// less than the number requested, even 0. Returns Err on EOF.
607 /// If an error occurs during this I/O operation, then it is returned
608 /// as `Err(IoError)`. See `read()` for more details.
609 fn push(&mut self, len: uint, buf: &mut Vec<u8>) -> IoResult<uint> {
610 let start_len = buf.len();
611 buf.reserve_additional(len);
614 let s = unsafe { slice_vec_capacity(buf, start_len, start_len + len) };
617 unsafe { buf.set_len(start_len + n) };
621 /// Reads at least `min` bytes, but no more than `len`, and appends them to
623 /// Returns the number of bytes read.
625 /// This will continue to call `read` until at least `min` bytes have been
626 /// read. If `read` returns 0 too many times, `NoProgress` will be
631 /// If an error occurs at any point, that error is returned, and no further
633 fn push_at_least(&mut self, min: uint, len: uint, buf: &mut Vec<u8>) -> IoResult<uint> {
636 detail: Some("the buffer is too short".to_string()),
637 ..standard_error(InvalidInput)
641 let start_len = buf.len();
642 buf.reserve_additional(len);
644 // we can't just use self.read_at_least(min, slice) because we need to push
645 // successful reads onto the vector before any returned errors.
650 let s = unsafe { slice_vec_capacity(buf, start_len + read, start_len + len) };
651 try!(self.read_at_least(1, s))
653 unsafe { buf.set_len(start_len + read) };
658 /// Reads exactly `len` bytes and gives you back a new vector of length
663 /// Fails with the same conditions as `read`. Additionally returns error
664 /// on EOF. Note that if an error is returned, then some number of bytes may
665 /// have already been consumed from the underlying reader, and they are lost
666 /// (not returned as part of the error). If this is unacceptable, then it is
667 /// recommended to use the `push_at_least` or `read` methods.
668 fn read_exact(&mut self, len: uint) -> IoResult<Vec<u8>> {
669 let mut buf = Vec::with_capacity(len);
670 match self.push_at_least(len, len, &mut buf) {
676 /// Reads all remaining bytes from the stream.
680 /// Returns any non-EOF error immediately. Previously read bytes are
681 /// discarded when an error is returned.
683 /// When EOF is encountered, all bytes read up to that point are returned.
684 fn read_to_end(&mut self) -> IoResult<Vec<u8>> {
685 let mut buf = Vec::with_capacity(DEFAULT_BUF_SIZE);
687 match self.push_at_least(1, DEFAULT_BUF_SIZE, &mut buf) {
689 Err(ref e) if e.kind == EndOfFile => break,
690 Err(e) => return Err(e)
696 /// Reads all of the remaining bytes of this stream, interpreting them as a
697 /// UTF-8 encoded stream. The corresponding string is returned.
701 /// This function returns all of the same errors as `read_to_end` with an
702 /// additional error if the reader's contents are not a valid sequence of
704 fn read_to_str(&mut self) -> IoResult<String> {
705 self.read_to_end().and_then(|s| {
706 match str::from_utf8(s.as_slice()) {
707 Some(s) => Ok(s.to_string()),
708 None => Err(standard_error(InvalidInput)),
713 /// Create an iterator that reads a single byte on
714 /// each iteration, until EOF.
718 /// Any error other than `EndOfFile` that is produced by the underlying Reader
719 /// is returned by the iterator and should be handled by the caller.
720 fn bytes<'r>(&'r mut self) -> extensions::Bytes<'r, Self> {
721 extensions::Bytes::new(self)
724 // Byte conversion helpers
726 /// Reads `n` little-endian unsigned integer bytes.
728 /// `n` must be between 1 and 8, inclusive.
729 fn read_le_uint_n(&mut self, nbytes: uint) -> IoResult<u64> {
730 assert!(nbytes > 0 && nbytes <= 8);
736 val += (try!(self.read_u8()) as u64) << pos;
743 /// Reads `n` little-endian signed integer bytes.
745 /// `n` must be between 1 and 8, inclusive.
746 fn read_le_int_n(&mut self, nbytes: uint) -> IoResult<i64> {
747 self.read_le_uint_n(nbytes).map(|i| extend_sign(i, nbytes))
750 /// Reads `n` big-endian unsigned integer bytes.
752 /// `n` must be between 1 and 8, inclusive.
753 fn read_be_uint_n(&mut self, nbytes: uint) -> IoResult<u64> {
754 assert!(nbytes > 0 && nbytes <= 8);
760 val += (try!(self.read_u8()) as u64) << i * 8;
765 /// Reads `n` big-endian signed integer bytes.
767 /// `n` must be between 1 and 8, inclusive.
768 fn read_be_int_n(&mut self, nbytes: uint) -> IoResult<i64> {
769 self.read_be_uint_n(nbytes).map(|i| extend_sign(i, nbytes))
772 /// Reads a little-endian unsigned integer.
774 /// The number of bytes returned is system-dependent.
775 fn read_le_uint(&mut self) -> IoResult<uint> {
776 self.read_le_uint_n(uint::BYTES).map(|i| i as uint)
779 /// Reads a little-endian integer.
781 /// The number of bytes returned is system-dependent.
782 fn read_le_int(&mut self) -> IoResult<int> {
783 self.read_le_int_n(int::BYTES).map(|i| i as int)
786 /// Reads a big-endian unsigned integer.
788 /// The number of bytes returned is system-dependent.
789 fn read_be_uint(&mut self) -> IoResult<uint> {
790 self.read_be_uint_n(uint::BYTES).map(|i| i as uint)
793 /// Reads a big-endian integer.
795 /// The number of bytes returned is system-dependent.
796 fn read_be_int(&mut self) -> IoResult<int> {
797 self.read_be_int_n(int::BYTES).map(|i| i as int)
800 /// Reads a big-endian `u64`.
802 /// `u64`s are 8 bytes long.
803 fn read_be_u64(&mut self) -> IoResult<u64> {
804 self.read_be_uint_n(8)
807 /// Reads a big-endian `u32`.
809 /// `u32`s are 4 bytes long.
810 fn read_be_u32(&mut self) -> IoResult<u32> {
811 self.read_be_uint_n(4).map(|i| i as u32)
814 /// Reads a big-endian `u16`.
816 /// `u16`s are 2 bytes long.
817 fn read_be_u16(&mut self) -> IoResult<u16> {
818 self.read_be_uint_n(2).map(|i| i as u16)
821 /// Reads a big-endian `i64`.
823 /// `i64`s are 8 bytes long.
824 fn read_be_i64(&mut self) -> IoResult<i64> {
825 self.read_be_int_n(8)
828 /// Reads a big-endian `i32`.
830 /// `i32`s are 4 bytes long.
831 fn read_be_i32(&mut self) -> IoResult<i32> {
832 self.read_be_int_n(4).map(|i| i as i32)
835 /// Reads a big-endian `i16`.
837 /// `i16`s are 2 bytes long.
838 fn read_be_i16(&mut self) -> IoResult<i16> {
839 self.read_be_int_n(2).map(|i| i as i16)
842 /// Reads a big-endian `f64`.
844 /// `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
845 fn read_be_f64(&mut self) -> IoResult<f64> {
846 self.read_be_u64().map(|i| unsafe {
847 transmute::<u64, f64>(i)
851 /// Reads a big-endian `f32`.
853 /// `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
854 fn read_be_f32(&mut self) -> IoResult<f32> {
855 self.read_be_u32().map(|i| unsafe {
856 transmute::<u32, f32>(i)
860 /// Reads a little-endian `u64`.
862 /// `u64`s are 8 bytes long.
863 fn read_le_u64(&mut self) -> IoResult<u64> {
864 self.read_le_uint_n(8)
867 /// Reads a little-endian `u32`.
869 /// `u32`s are 4 bytes long.
870 fn read_le_u32(&mut self) -> IoResult<u32> {
871 self.read_le_uint_n(4).map(|i| i as u32)
874 /// Reads a little-endian `u16`.
876 /// `u16`s are 2 bytes long.
877 fn read_le_u16(&mut self) -> IoResult<u16> {
878 self.read_le_uint_n(2).map(|i| i as u16)
881 /// Reads a little-endian `i64`.
883 /// `i64`s are 8 bytes long.
884 fn read_le_i64(&mut self) -> IoResult<i64> {
885 self.read_le_int_n(8)
888 /// Reads a little-endian `i32`.
890 /// `i32`s are 4 bytes long.
891 fn read_le_i32(&mut self) -> IoResult<i32> {
892 self.read_le_int_n(4).map(|i| i as i32)
895 /// Reads a little-endian `i16`.
897 /// `i16`s are 2 bytes long.
898 fn read_le_i16(&mut self) -> IoResult<i16> {
899 self.read_le_int_n(2).map(|i| i as i16)
902 /// Reads a little-endian `f64`.
904 /// `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
905 fn read_le_f64(&mut self) -> IoResult<f64> {
906 self.read_le_u64().map(|i| unsafe {
907 transmute::<u64, f64>(i)
911 /// Reads a little-endian `f32`.
913 /// `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
914 fn read_le_f32(&mut self) -> IoResult<f32> {
915 self.read_le_u32().map(|i| unsafe {
916 transmute::<u32, f32>(i)
922 /// `u8`s are 1 byte.
923 fn read_u8(&mut self) -> IoResult<u8> {
929 /// `i8`s are 1 byte.
930 fn read_i8(&mut self) -> IoResult<i8> {
931 self.read_byte().map(|i| i as i8)
934 /// Creates a wrapper around a mutable reference to the reader.
936 /// This is useful to allow applying adaptors while still
937 /// retaining ownership of the original value.
938 fn by_ref<'a>(&'a mut self) -> RefReader<'a, Self> {
939 RefReader { inner: self }
943 impl Reader for Box<Reader> {
944 fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> { self.read(buf) }
947 impl<'a> Reader for &'a mut Reader {
948 fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> { self.read(buf) }
951 /// Returns a slice of `v` between `start` and `end`.
953 /// Similar to `slice()` except this function only bounds the slice on the
954 /// capacity of `v`, not the length.
958 /// Fails when `start` or `end` point outside the capacity of `v`, or when
960 // Private function here because we aren't sure if we want to expose this as
961 // API yet. If so, it should be a method on Vec.
962 unsafe fn slice_vec_capacity<'a, T>(v: &'a mut Vec<T>, start: uint, end: uint) -> &'a mut [T] {
966 assert!(start <= end);
967 assert!(end <= v.capacity());
969 data: v.as_ptr().offset(start as int),
974 /// A `RefReader` is a struct implementing `Reader` which contains a reference
975 /// to another reader. This is often useful when composing streams.
981 /// # fn process_input<R: Reader>(r: R) {}
984 /// use std::io::util::LimitReader;
986 /// let mut stream = io::stdin();
988 /// // Only allow the function to process at most one kilobyte of input
990 /// let stream = LimitReader::new(stream.by_ref(), 1024);
991 /// process_input(stream);
994 /// // 'stream' is still available for use here
998 pub struct RefReader<'a, R> {
999 /// The underlying reader which this is referencing
1003 impl<'a, R: Reader> Reader for RefReader<'a, R> {
1004 fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> { self.inner.read(buf) }
1007 impl<'a, R: Buffer> Buffer for RefReader<'a, R> {
1008 fn fill_buf<'a>(&'a mut self) -> IoResult<&'a [u8]> { self.inner.fill_buf() }
1009 fn consume(&mut self, amt: uint) { self.inner.consume(amt) }
1012 fn extend_sign(val: u64, nbytes: uint) -> i64 {
1013 let shift = (8 - nbytes) * 8;
1014 (val << shift) as i64 >> shift
1017 /// A trait for objects which are byte-oriented streams. Writers are defined by
1018 /// one method, `write`. This function will block until the provided buffer of
1019 /// bytes has been entirely written, and it will return any failures which occur.
1021 /// Another commonly overridden method is the `flush` method for writers such as
1022 /// buffered writers.
1024 /// Writers are intended to be composable with one another. Many objects
1025 /// throughout the I/O and related libraries take and provide types which
1026 /// implement the `Writer` trait.
1028 /// Write the entirety of a given buffer
1032 /// If an error happens during the I/O operation, the error is returned as
1033 /// `Err`. Note that it is considered an error if the entire buffer could
1034 /// not be written, and if an error is returned then it is unknown how much
1035 /// data (if any) was actually written.
1036 fn write(&mut self, buf: &[u8]) -> IoResult<()>;
1038 /// Flush this output stream, ensuring that all intermediately buffered
1039 /// contents reach their destination.
1041 /// This is by default a no-op and implementers of the `Writer` trait should
1042 /// decide whether their stream needs to be buffered or not.
1043 fn flush(&mut self) -> IoResult<()> { Ok(()) }
1045 /// Writes a formatted string into this writer, returning any error
1048 /// This method is primarily used to interface with the `format_args!`
1049 /// macro, but it is rare that this should explicitly be called. The
1050 /// `write!` macro should be favored to invoke this method instead.
1054 /// This function will return any I/O error reported while formatting.
1055 fn write_fmt(&mut self, fmt: &fmt::Arguments) -> IoResult<()> {
1056 // Create a shim which translates a Writer to a FormatWriter and saves
1057 // off I/O errors. instead of discarding them
1058 struct Adaptor<'a, T> {
1060 error: IoResult<()>,
1062 impl<'a, T: Writer> fmt::FormatWriter for Adaptor<'a, T> {
1063 fn write(&mut self, bytes: &[u8]) -> fmt::Result {
1064 match self.inner.write(bytes) {
1067 self.error = Err(e);
1068 Err(fmt::WriteError)
1074 let mut output = Adaptor { inner: self, error: Ok(()) };
1075 match fmt::write(&mut output, fmt) {
1077 Err(..) => output.error
1081 /// Write a rust string into this sink.
1083 /// The bytes written will be the UTF-8 encoded version of the input string.
1084 /// If other encodings are desired, it is recommended to compose this stream
1085 /// with another performing the conversion, or to use `write` with a
1086 /// converted byte-array instead.
1087 fn write_str(&mut self, s: &str) -> IoResult<()> {
1088 self.write(s.as_bytes())
1091 /// Writes a string into this sink, and then writes a literal newline (`\n`)
1092 /// byte afterwards. Note that the writing of the newline is *not* atomic in
1093 /// the sense that the call to `write` is invoked twice (once with the
1094 /// string and once with a newline character).
1096 /// If other encodings or line ending flavors are desired, it is recommended
1097 /// that the `write` method is used specifically instead.
1098 fn write_line(&mut self, s: &str) -> IoResult<()> {
1099 self.write_str(s).and_then(|()| self.write(['\n' as u8]))
1102 /// Write a single char, encoded as UTF-8.
1103 fn write_char(&mut self, c: char) -> IoResult<()> {
1104 let mut buf = [0u8, ..4];
1105 let n = c.encode_utf8(buf.as_mut_slice());
1106 self.write(buf.slice_to(n))
1109 /// Write the result of passing n through `int::to_str_bytes`.
1110 fn write_int(&mut self, n: int) -> IoResult<()> {
1111 write!(self, "{:d}", n)
1114 /// Write the result of passing n through `uint::to_str_bytes`.
1115 fn write_uint(&mut self, n: uint) -> IoResult<()> {
1116 write!(self, "{:u}", n)
1119 /// Write a little-endian uint (number of bytes depends on system).
1120 fn write_le_uint(&mut self, n: uint) -> IoResult<()> {
1121 extensions::u64_to_le_bytes(n as u64, uint::BYTES, |v| self.write(v))
1124 /// Write a little-endian int (number of bytes depends on system).
1125 fn write_le_int(&mut self, n: int) -> IoResult<()> {
1126 extensions::u64_to_le_bytes(n as u64, int::BYTES, |v| self.write(v))
1129 /// Write a big-endian uint (number of bytes depends on system).
1130 fn write_be_uint(&mut self, n: uint) -> IoResult<()> {
1131 extensions::u64_to_be_bytes(n as u64, uint::BYTES, |v| self.write(v))
1134 /// Write a big-endian int (number of bytes depends on system).
1135 fn write_be_int(&mut self, n: int) -> IoResult<()> {
1136 extensions::u64_to_be_bytes(n as u64, int::BYTES, |v| self.write(v))
1139 /// Write a big-endian u64 (8 bytes).
1140 fn write_be_u64(&mut self, n: u64) -> IoResult<()> {
1141 extensions::u64_to_be_bytes(n, 8u, |v| self.write(v))
1144 /// Write a big-endian u32 (4 bytes).
1145 fn write_be_u32(&mut self, n: u32) -> IoResult<()> {
1146 extensions::u64_to_be_bytes(n as u64, 4u, |v| self.write(v))
1149 /// Write a big-endian u16 (2 bytes).
1150 fn write_be_u16(&mut self, n: u16) -> IoResult<()> {
1151 extensions::u64_to_be_bytes(n as u64, 2u, |v| self.write(v))
1154 /// Write a big-endian i64 (8 bytes).
1155 fn write_be_i64(&mut self, n: i64) -> IoResult<()> {
1156 extensions::u64_to_be_bytes(n as u64, 8u, |v| self.write(v))
1159 /// Write a big-endian i32 (4 bytes).
1160 fn write_be_i32(&mut self, n: i32) -> IoResult<()> {
1161 extensions::u64_to_be_bytes(n as u64, 4u, |v| self.write(v))
1164 /// Write a big-endian i16 (2 bytes).
1165 fn write_be_i16(&mut self, n: i16) -> IoResult<()> {
1166 extensions::u64_to_be_bytes(n as u64, 2u, |v| self.write(v))
1169 /// Write a big-endian IEEE754 double-precision floating-point (8 bytes).
1170 fn write_be_f64(&mut self, f: f64) -> IoResult<()> {
1172 self.write_be_u64(transmute(f))
1176 /// Write a big-endian IEEE754 single-precision floating-point (4 bytes).
1177 fn write_be_f32(&mut self, f: f32) -> IoResult<()> {
1179 self.write_be_u32(transmute(f))
1183 /// Write a little-endian u64 (8 bytes).
1184 fn write_le_u64(&mut self, n: u64) -> IoResult<()> {
1185 extensions::u64_to_le_bytes(n, 8u, |v| self.write(v))
1188 /// Write a little-endian u32 (4 bytes).
1189 fn write_le_u32(&mut self, n: u32) -> IoResult<()> {
1190 extensions::u64_to_le_bytes(n as u64, 4u, |v| self.write(v))
1193 /// Write a little-endian u16 (2 bytes).
1194 fn write_le_u16(&mut self, n: u16) -> IoResult<()> {
1195 extensions::u64_to_le_bytes(n as u64, 2u, |v| self.write(v))
1198 /// Write a little-endian i64 (8 bytes).
1199 fn write_le_i64(&mut self, n: i64) -> IoResult<()> {
1200 extensions::u64_to_le_bytes(n as u64, 8u, |v| self.write(v))
1203 /// Write a little-endian i32 (4 bytes).
1204 fn write_le_i32(&mut self, n: i32) -> IoResult<()> {
1205 extensions::u64_to_le_bytes(n as u64, 4u, |v| self.write(v))
1208 /// Write a little-endian i16 (2 bytes).
1209 fn write_le_i16(&mut self, n: i16) -> IoResult<()> {
1210 extensions::u64_to_le_bytes(n as u64, 2u, |v| self.write(v))
1213 /// Write a little-endian IEEE754 double-precision floating-point
1215 fn write_le_f64(&mut self, f: f64) -> IoResult<()> {
1217 self.write_le_u64(transmute(f))
1221 /// Write a little-endian IEEE754 single-precision floating-point
1223 fn write_le_f32(&mut self, f: f32) -> IoResult<()> {
1225 self.write_le_u32(transmute(f))
1229 /// Write a u8 (1 byte).
1230 fn write_u8(&mut self, n: u8) -> IoResult<()> {
1234 /// Write an i8 (1 byte).
1235 fn write_i8(&mut self, n: i8) -> IoResult<()> {
1236 self.write([n as u8])
1239 /// Creates a wrapper around a mutable reference to the writer.
1241 /// This is useful to allow applying wrappers while still
1242 /// retaining ownership of the original value.
1243 fn by_ref<'a>(&'a mut self) -> RefWriter<'a, Self> {
1244 RefWriter { inner: self }
1248 impl Writer for Box<Writer> {
1249 fn write(&mut self, buf: &[u8]) -> IoResult<()> { self.write(buf) }
1250 fn flush(&mut self) -> IoResult<()> { self.flush() }
1253 impl<'a> Writer for &'a mut Writer {
1254 fn write(&mut self, buf: &[u8]) -> IoResult<()> { self.write(buf) }
1255 fn flush(&mut self) -> IoResult<()> { self.flush() }
1258 /// A `RefWriter` is a struct implementing `Writer` which contains a reference
1259 /// to another writer. This is often useful when composing streams.
1265 /// # fn process_input<R: Reader>(r: R) {}
1267 /// use std::io::util::TeeReader;
1268 /// use std::io::{stdin, MemWriter};
1270 /// let mut output = MemWriter::new();
1273 /// // Don't give ownership of 'output' to the 'tee'. Instead we keep a
1274 /// // handle to it in the outer scope
1275 /// let mut tee = TeeReader::new(stdin(), output.by_ref());
1276 /// process_input(tee);
1279 /// println!("input processed: {}", output.unwrap());
1282 pub struct RefWriter<'a, W> {
1283 /// The underlying writer which this is referencing
1287 impl<'a, W: Writer> Writer for RefWriter<'a, W> {
1288 fn write(&mut self, buf: &[u8]) -> IoResult<()> { self.inner.write(buf) }
1289 fn flush(&mut self) -> IoResult<()> { self.inner.flush() }
1293 /// A Stream is a readable and a writable object. Data written is typically
1294 /// received by the object which reads receive data from.
1295 pub trait Stream: Reader + Writer { }
1297 impl<T: Reader + Writer> Stream for T {}
1299 /// An iterator that reads a line on each iteration,
1300 /// until `.read_line()` encounters `EndOfFile`.
1302 /// # Notes about the Iteration Protocol
1304 /// The `Lines` may yield `None` and thus terminate
1305 /// an iteration, but continue to yield elements if iteration
1306 /// is attempted again.
1310 /// Any error other than `EndOfFile` that is produced by the underlying Reader
1311 /// is returned by the iterator and should be handled by the caller.
1312 pub struct Lines<'r, T> {
1316 impl<'r, T: Buffer> Iterator<IoResult<String>> for Lines<'r, T> {
1317 fn next(&mut self) -> Option<IoResult<String>> {
1318 match self.buffer.read_line() {
1319 Ok(x) => Some(Ok(x)),
1320 Err(IoError { kind: EndOfFile, ..}) => None,
1321 Err(y) => Some(Err(y))
1326 /// An iterator that reads a utf8-encoded character on each iteration,
1327 /// until `.read_char()` encounters `EndOfFile`.
1329 /// # Notes about the Iteration Protocol
1331 /// The `Chars` may yield `None` and thus terminate
1332 /// an iteration, but continue to yield elements if iteration
1333 /// is attempted again.
1337 /// Any error other than `EndOfFile` that is produced by the underlying Reader
1338 /// is returned by the iterator and should be handled by the caller.
1339 pub struct Chars<'r, T> {
1343 impl<'r, T: Buffer> Iterator<IoResult<char>> for Chars<'r, T> {
1344 fn next(&mut self) -> Option<IoResult<char>> {
1345 match self.buffer.read_char() {
1346 Ok(x) => Some(Ok(x)),
1347 Err(IoError { kind: EndOfFile, ..}) => None,
1348 Err(y) => Some(Err(y))
1353 /// A Buffer is a type of reader which has some form of internal buffering to
1354 /// allow certain kinds of reading operations to be more optimized than others.
1355 /// This type extends the `Reader` trait with a few methods that are not
1356 /// possible to reasonably implement with purely a read interface.
1357 pub trait Buffer: Reader {
1358 /// Fills the internal buffer of this object, returning the buffer contents.
1359 /// Note that none of the contents will be "read" in the sense that later
1360 /// calling `read` may return the same contents.
1362 /// The `consume` function must be called with the number of bytes that are
1363 /// consumed from this buffer returned to ensure that the bytes are never
1368 /// This function will return an I/O error if the underlying reader was
1369 /// read, but returned an error. Note that it is not an error to return a
1370 /// 0-length buffer.
1371 fn fill_buf<'a>(&'a mut self) -> IoResult<&'a [u8]>;
1373 /// Tells this buffer that `amt` bytes have been consumed from the buffer,
1374 /// so they should no longer be returned in calls to `read`.
1375 fn consume(&mut self, amt: uint);
1377 /// Reads the next line of input, interpreted as a sequence of UTF-8
1378 /// encoded unicode codepoints. If a newline is encountered, then the
1379 /// newline is contained in the returned string.
1386 /// let mut reader = io::stdin();
1387 /// let input = reader.read_line().ok().unwrap_or("nothing".to_string());
1392 /// This function has the same error semantics as `read_until`:
1394 /// * All non-EOF errors will be returned immediately
1395 /// * If an error is returned previously consumed bytes are lost
1396 /// * EOF is only returned if no bytes have been read
1397 /// * Reach EOF may mean that the delimiter is not present in the return
1400 /// Additionally, this function can fail if the line of input read is not a
1401 /// valid UTF-8 sequence of bytes.
1402 fn read_line(&mut self) -> IoResult<String> {
1403 self.read_until('\n' as u8).and_then(|line|
1404 match str::from_utf8(line.as_slice()) {
1405 Some(s) => Ok(s.to_string()),
1406 None => Err(standard_error(InvalidInput)),
1411 /// Create an iterator that reads a line on each iteration until EOF.
1415 /// Any error other than `EndOfFile` that is produced by the underlying Reader
1416 /// is returned by the iterator and should be handled by the caller.
1417 fn lines<'r>(&'r mut self) -> Lines<'r, Self> {
1418 Lines { buffer: self }
1421 /// Reads a sequence of bytes leading up to a specified delimiter. Once the
1422 /// specified byte is encountered, reading ceases and the bytes up to and
1423 /// including the delimiter are returned.
1427 /// If any I/O error is encountered other than EOF, the error is immediately
1428 /// returned. Note that this may discard bytes which have already been read,
1429 /// and those bytes will *not* be returned. It is recommended to use other
1430 /// methods if this case is worrying.
1432 /// If EOF is encountered, then this function will return EOF if 0 bytes
1433 /// have been read, otherwise the pending byte buffer is returned. This
1434 /// is the reason that the byte buffer returned may not always contain the
1436 fn read_until(&mut self, byte: u8) -> IoResult<Vec<u8>> {
1437 let mut res = Vec::new();
1442 let available = match self.fill_buf() {
1444 Err(ref e) if res.len() > 0 && e.kind == EndOfFile => {
1448 Err(e) => return Err(e)
1450 match available.iter().position(|&b| b == byte) {
1452 res.push_all(available.slice_to(i + 1));
1457 res.push_all(available);
1458 used = available.len();
1468 /// Reads the next utf8-encoded character from the underlying stream.
1472 /// If an I/O error occurs, or EOF, then this function will return `Err`.
1473 /// This function will also return error if the stream does not contain a
1474 /// valid utf-8 encoded codepoint as the next few bytes in the stream.
1475 fn read_char(&mut self) -> IoResult<char> {
1476 let first_byte = try!(self.read_byte());
1477 let width = str::utf8_char_width(first_byte);
1478 if width == 1 { return Ok(first_byte as char) }
1479 if width == 0 { return Err(standard_error(InvalidInput)) } // not utf8
1480 let mut buf = [first_byte, 0, 0, 0];
1483 while start < width {
1484 match try!(self.read(buf.mut_slice(start, width))) {
1485 n if n == width - start => break,
1486 n if n < width - start => { start += n; }
1487 _ => return Err(standard_error(InvalidInput)),
1491 match str::from_utf8(buf.slice_to(width)) {
1492 Some(s) => Ok(s.char_at(0)),
1493 None => Err(standard_error(InvalidInput))
1497 /// Create an iterator that reads a utf8-encoded character on each iteration
1502 /// Any error other than `EndOfFile` that is produced by the underlying Reader
1503 /// is returned by the iterator and should be handled by the caller.
1504 fn chars<'r>(&'r mut self) -> Chars<'r, Self> {
1505 Chars { buffer: self }
1509 /// When seeking, the resulting cursor is offset from a base by the offset given
1510 /// to the `seek` function. The base used is specified by this enumeration.
1511 pub enum SeekStyle {
1512 /// Seek from the beginning of the stream
1514 /// Seek from the end of the stream
1516 /// Seek from the current position
1520 /// An object implementing `Seek` internally has some form of cursor which can
1521 /// be moved within a stream of bytes. The stream typically has a fixed size,
1522 /// allowing seeking relative to either end.
1524 /// Return position of file cursor in the stream
1525 fn tell(&self) -> IoResult<u64>;
1527 /// Seek to an offset in a stream
1529 /// A successful seek clears the EOF indicator. Seeking beyond EOF is
1530 /// allowed, but seeking before position 0 is not allowed.
1534 /// * Seeking to a negative offset is considered an error
1535 /// * Seeking past the end of the stream does not modify the underlying
1536 /// stream, but the next write may cause the previous data to be filled in
1537 /// with a bit pattern.
1538 fn seek(&mut self, pos: i64, style: SeekStyle) -> IoResult<()>;
1541 /// A listener is a value that can consume itself to start listening for
1544 /// Doing so produces some sort of Acceptor.
1545 pub trait Listener<T, A: Acceptor<T>> {
1546 /// Spin up the listener and start queuing incoming connections
1550 /// Returns `Err` if this listener could not be bound to listen for
1551 /// connections. In all cases, this listener is consumed.
1552 fn listen(self) -> IoResult<A>;
1555 /// An acceptor is a value that presents incoming connections
1556 pub trait Acceptor<T> {
1557 /// Wait for and accept an incoming connection
1561 /// Returns `Err` if an I/O error is encountered.
1562 fn accept(&mut self) -> IoResult<T>;
1564 /// Create an iterator over incoming connection attempts.
1566 /// Note that I/O errors will be yielded by the iterator itself.
1567 fn incoming<'r>(&'r mut self) -> IncomingConnections<'r, Self> {
1568 IncomingConnections { inc: self }
1572 /// An infinite iterator over incoming connection attempts.
1573 /// Calling `next` will block the task until a connection is attempted.
1575 /// Since connection attempts can continue forever, this iterator always returns
1576 /// `Some`. The `Some` contains the `IoResult` representing whether the
1577 /// connection attempt was successful. A successful connection will be wrapped
1578 /// in `Ok`. A failed connection is represented as an `Err`.
1579 pub struct IncomingConnections<'a, A> {
1583 impl<'a, T, A: Acceptor<T>> Iterator<IoResult<T>> for IncomingConnections<'a, A> {
1584 fn next(&mut self) -> Option<IoResult<T>> {
1585 Some(self.inc.accept())
1589 /// Creates a standard error for a commonly used flavor of error. The `detail`
1590 /// field of the returned error will always be `None`.
1597 /// let eof = io::standard_error(io::EndOfFile);
1598 /// let einval = io::standard_error(io::InvalidInput);
1600 pub fn standard_error(kind: IoErrorKind) -> IoError {
1601 let desc = match kind {
1602 EndOfFile => "end of file",
1603 IoUnavailable => "I/O is unavailable",
1604 InvalidInput => "invalid input",
1605 OtherIoError => "unknown I/O error",
1606 FileNotFound => "file not found",
1607 PermissionDenied => "permission denied",
1608 ConnectionFailed => "connection failed",
1609 Closed => "stream is closed",
1610 ConnectionRefused => "connection refused",
1611 ConnectionReset => "connection reset",
1612 ConnectionAborted => "connection aborted",
1613 NotConnected => "not connected",
1614 BrokenPipe => "broken pipe",
1615 PathAlreadyExists => "file already exists",
1616 PathDoesntExist => "no such file",
1617 MismatchedFileTypeForOperation => "mismatched file type",
1618 ResourceUnavailable => "resource unavailable",
1619 TimedOut => "operation timed out",
1620 ShortWrite(..) => "short write",
1621 NoProgress => "no progress",
1630 /// A mode specifies how a file should be opened or created. These modes are
1631 /// passed to `File::open_mode` and are used to control where the file is
1632 /// positioned when it is initially opened.
1634 /// Opens a file positioned at the beginning.
1636 /// Opens a file positioned at EOF.
1638 /// Opens a file, truncating it if it already exists.
1642 /// Access permissions with which the file should be opened. `File`s
1643 /// opened with `Read` will return an error if written to.
1644 pub enum FileAccess {
1645 /// Read-only access, requests to write will result in an error
1647 /// Write-only access, requests to read will result in an error
1649 /// Read-write access, no requests are denied by default
1653 /// Different kinds of files which can be identified by a call to stat
1654 #[deriving(PartialEq, Show, Hash)]
1656 /// This is a normal file, corresponding to `S_IFREG`
1659 /// This file is a directory, corresponding to `S_IFDIR`
1662 /// This file is a named pipe, corresponding to `S_IFIFO`
1665 /// This file is a block device, corresponding to `S_IFBLK`
1668 /// This file is a symbolic link to another file, corresponding to `S_IFLNK`
1671 /// The type of this file is not recognized as one of the other categories
1675 /// A structure used to describe metadata information about a file. This
1676 /// structure is created through the `stat` method on a `Path`.
1683 /// let info = match Path::new("foo.txt").stat() {
1684 /// Ok(stat) => stat,
1685 /// Err(e) => fail!("couldn't read foo.txt: {}", e),
1688 /// println!("byte size: {}", info.size);
1692 pub struct FileStat {
1693 /// The size of the file, in bytes
1695 /// The kind of file this path points to (directory, file, pipe, etc.)
1697 /// The file permissions currently on the file
1698 pub perm: FilePermission,
1700 // FIXME(#10301): These time fields are pretty useless without an actual
1701 // time representation, what are the milliseconds relative
1704 /// The time that the file was created at, in platform-dependent
1707 /// The time that this file was last modified, in platform-dependent
1710 /// The time that this file was last accessed, in platform-dependent
1714 /// Information returned by stat() which is not guaranteed to be
1715 /// platform-independent. This information may be useful on some platforms,
1716 /// but it may have different meanings or no meaning at all on other
1719 /// Usage of this field is discouraged, but if access is desired then the
1720 /// fields are located here.
1722 pub unstable: UnstableFileStat,
1725 /// This structure represents all of the possible information which can be
1726 /// returned from a `stat` syscall which is not contained in the `FileStat`
1727 /// structure. This information is not necessarily platform independent, and may
1728 /// have different meanings or no meaning at all on some platforms.
1731 pub struct UnstableFileStat {
1732 /// The ID of the device containing the file.
1734 /// The file serial number.
1738 /// The number of hard links to this file.
1740 /// The user ID of the file.
1742 /// The group ID of the file.
1744 /// The optimal block size for I/O.
1746 /// The blocks allocated for this file.
1748 /// User-defined flags for the file.
1750 /// The file generation number.
1755 #[doc="A set of permissions for a file or directory is represented
1756 by a set of flags which are or'd together."]
1759 flags FilePermission: u32 {
1760 static UserRead = 0o400,
1761 static UserWrite = 0o200,
1762 static UserExecute = 0o100,
1763 static GroupRead = 0o040,
1764 static GroupWrite = 0o020,
1765 static GroupExecute = 0o010,
1766 static OtherRead = 0o004,
1767 static OtherWrite = 0o002,
1768 static OtherExecute = 0o001,
1770 static UserRWX = UserRead.bits | UserWrite.bits | UserExecute.bits,
1771 static GroupRWX = GroupRead.bits | GroupWrite.bits | GroupExecute.bits,
1772 static OtherRWX = OtherRead.bits | OtherWrite.bits | OtherExecute.bits,
1774 #[doc="Permissions for user owned files, equivalent to 0644 on
1775 unix-like systems."]
1776 static UserFile = UserRead.bits | UserWrite.bits | GroupRead.bits | OtherRead.bits,
1778 #[doc="Permissions for user owned directories, equivalent to 0755 on
1779 unix-like systems."]
1780 static UserDir = UserRWX.bits | GroupRead.bits | GroupExecute.bits |
1781 OtherRead.bits | OtherExecute.bits,
1783 #[doc="Permissions for user owned executables, equivalent to 0755
1784 on unix-like systems."]
1785 static UserExec = UserDir.bits,
1787 #[doc="All possible permissions enabled."]
1788 static AllPermissions = UserRWX.bits | GroupRWX.bits | OtherRWX.bits
1794 use super::{IoResult, Reader, MemReader, NoProgress, InvalidInput};
1798 #[deriving(Clone, PartialEq, Show)]
1799 enum BadReaderBehavior {
1804 struct BadReader<T> {
1806 behavior: Vec<BadReaderBehavior>,
1809 impl<T: Reader> BadReader<T> {
1810 fn new(r: T, behavior: Vec<BadReaderBehavior>) -> BadReader<T> {
1811 BadReader { behavior: behavior, r: r }
1815 impl<T: Reader> Reader for BadReader<T> {
1816 fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> {
1817 let BadReader { ref mut behavior, ref mut r } = *self;
1819 if behavior.is_empty() {
1820 // fall back on good
1823 match behavior.as_mut_slice()[0] {
1824 GoodBehavior(0) => (),
1825 GoodBehavior(ref mut x) => {
1829 BadBehavior(0) => (),
1830 BadBehavior(ref mut x) => {
1841 fn test_read_at_least() {
1842 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1843 Vec::from_slice([GoodBehavior(uint::MAX)]));
1844 let mut buf = [0u8, ..5];
1845 assert!(r.read_at_least(1, buf).unwrap() >= 1);
1846 assert!(r.read_exact(5).unwrap().len() == 5); // read_exact uses read_at_least
1847 assert!(r.read_at_least(0, buf).is_ok());
1849 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1850 Vec::from_slice([BadBehavior(50), GoodBehavior(uint::MAX)]));
1851 assert!(r.read_at_least(1, buf).unwrap() >= 1);
1853 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1854 Vec::from_slice([BadBehavior(1), GoodBehavior(1),
1855 BadBehavior(50), GoodBehavior(uint::MAX)]));
1856 assert!(r.read_at_least(1, buf).unwrap() >= 1);
1857 assert!(r.read_at_least(1, buf).unwrap() >= 1);
1859 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1860 Vec::from_slice([BadBehavior(uint::MAX)]));
1861 assert_eq!(r.read_at_least(1, buf).unwrap_err().kind, NoProgress);
1863 let mut r = MemReader::new(Vec::from_slice(bytes!("hello, world!")));
1864 assert_eq!(r.read_at_least(5, buf).unwrap(), 5);
1865 assert_eq!(r.read_at_least(6, buf).unwrap_err().kind, InvalidInput);
1869 fn test_push_at_least() {
1870 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1871 Vec::from_slice([GoodBehavior(uint::MAX)]));
1872 let mut buf = Vec::new();
1873 assert!(r.push_at_least(1, 5, &mut buf).unwrap() >= 1);
1874 assert!(r.push_at_least(0, 5, &mut buf).is_ok());
1876 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1877 Vec::from_slice([BadBehavior(50), GoodBehavior(uint::MAX)]));
1878 assert!(r.push_at_least(1, 5, &mut buf).unwrap() >= 1);
1880 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1881 Vec::from_slice([BadBehavior(1), GoodBehavior(1),
1882 BadBehavior(50), GoodBehavior(uint::MAX)]));
1883 assert!(r.push_at_least(1, 5, &mut buf).unwrap() >= 1);
1884 assert!(r.push_at_least(1, 5, &mut buf).unwrap() >= 1);
1886 let mut r = BadReader::new(MemReader::new(Vec::from_slice(bytes!("hello, world!"))),
1887 Vec::from_slice([BadBehavior(uint::MAX)]));
1888 assert_eq!(r.push_at_least(1, 5, &mut buf).unwrap_err().kind, NoProgress);
1890 let mut r = MemReader::new(Vec::from_slice(bytes!("hello, world!")));
1891 assert_eq!(r.push_at_least(5, 1, &mut buf).unwrap_err().kind, InvalidInput);