Source file src/pkg/io/io.go
1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package io provides basic interfaces to I/O primitives. 6 // Its primary job is to wrap existing implementations of such primitives, 7 // such as those in package os, into shared public interfaces that 8 // abstract the functionality, plus some other related primitives. 9 package io 10 11 import "os" 12 13 // Error represents an unexpected I/O behavior. 14 type Error struct { 15 ErrorString string 16 } 17 18 func (err *Error) String() string { return err.ErrorString } 19 20 // ErrShortWrite means that a write accepted fewer bytes than requested 21 // but failed to return an explicit error. 22 var ErrShortWrite os.Error = &Error{"short write"} 23 24 // ErrShortBuffer means that a read required a longer buffer than was provided. 25 var ErrShortBuffer os.Error = &Error{"short buffer"} 26 27 // ErrUnexpectedEOF means that os.EOF was encountered in the 28 // middle of reading a fixed-size block or data structure. 29 var ErrUnexpectedEOF os.Error = &Error{"unexpected EOF"} 30 31 // Reader is the interface that wraps the basic Read method. 32 // 33 // Read reads up to len(p) bytes into p. It returns the number of bytes 34 // read (0 <= n <= len(p)) and any error encountered. Even if Read 35 // returns n < len(p), it may use all of p as scratch space during the call. 36 // If some data is available but not len(p) bytes, Read conventionally 37 // returns what is available instead of waiting for more. 38 // 39 // When Read encounters an error or end-of-file condition after 40 // successfully reading n > 0 bytes, it returns the number of 41 // bytes read. It may return the (non-nil) error from the same call 42 // or return the error (and n == 0) from a subsequent call. 43 // An instance of this general case is that a Reader returning 44 // a non-zero number of bytes at the end of the input stream may 45 // return either err == os.EOF or err == nil. The next Read should 46 // return 0, os.EOF regardless. 47 // 48 // Callers should always process the n > 0 bytes returned before 49 // considering the error err. Doing so correctly handles I/O errors 50 // that happen after reading some bytes and also both of the 51 // allowed EOF behaviors. 52 type Reader interface { 53 Read(p []byte) (n int, err os.Error) 54 } 55 56 // Writer is the interface that wraps the basic Write method. 57 // 58 // Write writes len(p) bytes from p to the underlying data stream. 59 // It returns the number of bytes written from p (0 <= n <= len(p)) 60 // and any error encountered that caused the write to stop early. 61 // Write must return a non-nil error if it returns n < len(p). 62 type Writer interface { 63 Write(p []byte) (n int, err os.Error) 64 } 65 66 // Closer is the interface that wraps the basic Close method. 67 type Closer interface { 68 Close() os.Error 69 } 70 71 // Seeker is the interface that wraps the basic Seek method. 72 // 73 // Seek sets the offset for the next Read or Write to offset, 74 // interpreted according to whence: 0 means relative to the origin of 75 // the file, 1 means relative to the current offset, and 2 means 76 // relative to the end. Seek returns the new offset and an Error, if 77 // any. 78 type Seeker interface { 79 Seek(offset int64, whence int) (ret int64, err os.Error) 80 } 81 82 // ReadWriter is the interface that groups the basic Read and Write methods. 83 type ReadWriter interface { 84 Reader 85 Writer 86 } 87 88 // ReadCloser is the interface that groups the basic Read and Close methods. 89 type ReadCloser interface { 90 Reader 91 Closer 92 } 93 94 // WriteCloser is the interface that groups the basic Write and Close methods. 95 type WriteCloser interface { 96 Writer 97 Closer 98 } 99 100 // ReadWriteCloser is the interface that groups the basic Read, Write and Close methods. 101 type ReadWriteCloser interface { 102 Reader 103 Writer 104 Closer 105 } 106 107 // ReadSeeker is the interface that groups the basic Read and Seek methods. 108 type ReadSeeker interface { 109 Reader 110 Seeker 111 } 112 113 // WriteSeeker is the interface that groups the basic Write and Seek methods. 114 type WriteSeeker interface { 115 Writer 116 Seeker 117 } 118 119 // ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods. 120 type ReadWriteSeeker interface { 121 Reader 122 Writer 123 Seeker 124 } 125 126 // ReaderFrom is the interface that wraps the ReadFrom method. 127 type ReaderFrom interface { 128 ReadFrom(r Reader) (n int64, err os.Error) 129 } 130 131 // WriterTo is the interface that wraps the WriteTo method. 132 type WriterTo interface { 133 WriteTo(w Writer) (n int64, err os.Error) 134 } 135 136 // ReaderAt is the interface that wraps the basic ReadAt method. 137 // 138 // ReadAt reads len(p) bytes into p starting at offset off in the 139 // underlying input source. It returns the number of bytes 140 // read (0 <= n <= len(p)) and any error encountered. 141 // 142 // When ReadAt returns n < len(p), it returns a non-nil error 143 // explaining why more bytes were not returned. In this respect, 144 // ReadAt is stricter than Read. 145 // 146 // Even if ReadAt returns n < len(p), it may use all of p as scratch 147 // space during the call. If some data is available but not len(p) bytes, 148 // ReadAt blocks until either all the data is available or an error occurs. 149 // In this respect ReadAt is different from Read. 150 // 151 // If the n = len(p) bytes returned by ReadAt are at the end of the 152 // input source, ReadAt may return either err == os.EOF or err == nil. 153 // 154 // If ReadAt is reading from an input source with a seek offset, 155 // ReadAt should not affect nor be affected by the underlying 156 // seek offset. 157 type ReaderAt interface { 158 ReadAt(p []byte, off int64) (n int, err os.Error) 159 } 160 161 // WriterAt is the interface that wraps the basic WriteAt method. 162 // 163 // WriteAt writes len(p) bytes from p to the underlying data stream 164 // at offset off. It returns the number of bytes written from p (0 <= n <= len(p)) 165 // and any error encountered that caused the write to stop early. 166 // WriteAt must return a non-nil error if it returns n < len(p). 167 type WriterAt interface { 168 WriteAt(p []byte, off int64) (n int, err os.Error) 169 } 170 171 // ByteReader is the interface that wraps the ReadByte method. 172 // 173 // ReadByte reads and returns the next byte from the input. 174 // If no byte is available, err will be set. 175 type ByteReader interface { 176 ReadByte() (c byte, err os.Error) 177 } 178 179 // ByteScanner is the interface that adds the UnreadByte method to the 180 // basic ReadByte method. 181 // 182 // UnreadByte causes the next call to ReadByte to return the same byte 183 // as the previous call to ReadByte. 184 // It may be an error to call UnreadByte twice without an intervening 185 // call to ReadByte. 186 type ByteScanner interface { 187 ByteReader 188 UnreadByte() os.Error 189 } 190 191 // RuneReader is the interface that wraps the ReadRune method. 192 // 193 // ReadRune reads a single UTF-8 encoded Unicode character 194 // and returns the rune and its size in bytes. If no character is 195 // available, err will be set. 196 type RuneReader interface { 197 ReadRune() (rune int, size int, err os.Error) 198 } 199 200 // RuneScanner is the interface that adds the UnreadRune method to the 201 // basic ReadRune method. 202 // 203 // UnreadRune causes the next call to ReadRune to return the same rune 204 // as the previous call to ReadRune. 205 // It may be an error to call UnreadRune twice without an intervening 206 // call to ReadRune. 207 type RuneScanner interface { 208 RuneReader 209 UnreadRune() os.Error 210 } 211 212 // stringWriter is the interface that wraps the WriteString method. 213 type stringWriter interface { 214 WriteString(s string) (n int, err os.Error) 215 } 216 217 // WriteString writes the contents of the string s to w, which accepts an array of bytes. 218 func WriteString(w Writer, s string) (n int, err os.Error) { 219 if sw, ok := w.(stringWriter); ok { 220 return sw.WriteString(s) 221 } 222 return w.Write([]byte(s)) 223 } 224 225 // ReadAtLeast reads from r into buf until it has read at least min bytes. 226 // It returns the number of bytes copied and an error if fewer bytes were read. 227 // The error is os.EOF only if no bytes were read. 228 // If an EOF happens after reading fewer than min bytes, 229 // ReadAtLeast returns ErrUnexpectedEOF. 230 // If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer. 231 func ReadAtLeast(r Reader, buf []byte, min int) (n int, err os.Error) { 232 if len(buf) < min { 233 return 0, ErrShortBuffer 234 } 235 for n < min && err == nil { 236 var nn int 237 nn, err = r.Read(buf[n:]) 238 n += nn 239 } 240 if err == os.EOF { 241 if n >= min { 242 err = nil 243 } else if n > 0 { 244 err = ErrUnexpectedEOF 245 } 246 } 247 return 248 } 249 250 // ReadFull reads exactly len(buf) bytes from r into buf. 251 // It returns the number of bytes copied and an error if fewer bytes were read. 252 // The error is os.EOF only if no bytes were read. 253 // If an EOF happens after reading some but not all the bytes, 254 // ReadFull returns ErrUnexpectedEOF. 255 func ReadFull(r Reader, buf []byte) (n int, err os.Error) { 256 return ReadAtLeast(r, buf, len(buf)) 257 } 258 259 // Copyn copies n bytes (or until an error) from src to dst. 260 // It returns the number of bytes copied and the earliest 261 // error encountered while copying. Because Read can 262 // return the full amount requested as well as an error 263 // (including os.EOF), so can Copyn. 264 // 265 // If dst implements the ReaderFrom interface, 266 // the copy is implemented by calling dst.ReadFrom(src). 267 func Copyn(dst Writer, src Reader, n int64) (written int64, err os.Error) { 268 // If the writer has a ReadFrom method, use it to do the copy. 269 // Avoids a buffer allocation and a copy. 270 if rt, ok := dst.(ReaderFrom); ok { 271 written, err = rt.ReadFrom(LimitReader(src, n)) 272 if written < n && err == nil { 273 // rt stopped early; must have been EOF. 274 err = os.EOF 275 } 276 return 277 } 278 buf := make([]byte, 32*1024) 279 for written < n { 280 l := len(buf) 281 if d := n - written; d < int64(l) { 282 l = int(d) 283 } 284 nr, er := src.Read(buf[0:l]) 285 if nr > 0 { 286 nw, ew := dst.Write(buf[0:nr]) 287 if nw > 0 { 288 written += int64(nw) 289 } 290 if ew != nil { 291 err = ew 292 break 293 } 294 if nr != nw { 295 err = ErrShortWrite 296 break 297 } 298 } 299 if er != nil { 300 err = er 301 break 302 } 303 } 304 return written, err 305 } 306 307 // Copy copies from src to dst until either EOF is reached 308 // on src or an error occurs. It returns the number of bytes 309 // copied and the first error encountered while copying, if any. 310 // 311 // A successful Copy returns err == nil, not err == os.EOF. 312 // Because Copy is defined to read from src until EOF, it does 313 // not treat an EOF from Read as an error to be reported. 314 // 315 // If dst implements the ReaderFrom interface, 316 // the copy is implemented by calling dst.ReadFrom(src). 317 // Otherwise, if src implements the WriterTo interface, 318 // the copy is implemented by calling src.WriteTo(dst). 319 func Copy(dst Writer, src Reader) (written int64, err os.Error) { 320 // If the writer has a ReadFrom method, use it to do the copy. 321 // Avoids an allocation and a copy. 322 if rt, ok := dst.(ReaderFrom); ok { 323 return rt.ReadFrom(src) 324 } 325 // Similarly, if the reader has a WriteTo method, use it to do the copy. 326 if wt, ok := src.(WriterTo); ok { 327 return wt.WriteTo(dst) 328 } 329 buf := make([]byte, 32*1024) 330 for { 331 nr, er := src.Read(buf) 332 if nr > 0 { 333 nw, ew := dst.Write(buf[0:nr]) 334 if nw > 0 { 335 written += int64(nw) 336 } 337 if ew != nil { 338 err = ew 339 break 340 } 341 if nr != nw { 342 err = ErrShortWrite 343 break 344 } 345 } 346 if er == os.EOF { 347 break 348 } 349 if er != nil { 350 err = er 351 break 352 } 353 } 354 return written, err 355 } 356 357 // LimitReader returns a Reader that reads from r 358 // but stops with os.EOF after n bytes. 359 // The underlying implementation is a *LimitedReader. 360 func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} } 361 362 // A LimitedReader reads from R but limits the amount of 363 // data returned to just N bytes. Each call to Read 364 // updates N to reflect the new amount remaining. 365 type LimitedReader struct { 366 R Reader // underlying reader 367 N int64 // max bytes remaining 368 } 369 370 func (l *LimitedReader) Read(p []byte) (n int, err os.Error) { 371 if l.N <= 0 { 372 return 0, os.EOF 373 } 374 if int64(len(p)) > l.N { 375 p = p[0:l.N] 376 } 377 n, err = l.R.Read(p) 378 l.N -= int64(n) 379 return 380 } 381 382 // NewSectionReader returns a SectionReader that reads from r 383 // starting at offset off and stops with os.EOF after n bytes. 384 func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader { 385 return &SectionReader{r, off, off, off + n} 386 } 387 388 // SectionReader implements Read, Seek, and ReadAt on a section 389 // of an underlying ReaderAt. 390 type SectionReader struct { 391 r ReaderAt 392 base int64 393 off int64 394 limit int64 395 } 396 397 func (s *SectionReader) Read(p []byte) (n int, err os.Error) { 398 if s.off >= s.limit { 399 return 0, os.EOF 400 } 401 if max := s.limit - s.off; int64(len(p)) > max { 402 p = p[0:max] 403 } 404 n, err = s.r.ReadAt(p, s.off) 405 s.off += int64(n) 406 return 407 } 408 409 func (s *SectionReader) Seek(offset int64, whence int) (ret int64, err os.Error) { 410 switch whence { 411 default: 412 return 0, os.EINVAL 413 case 0: 414 offset += s.base 415 case 1: 416 offset += s.off 417 case 2: 418 offset += s.limit 419 } 420 if offset < s.base || offset > s.limit { 421 return 0, os.EINVAL 422 } 423 s.off = offset 424 return offset - s.base, nil 425 } 426 427 func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err os.Error) { 428 if off < 0 || off >= s.limit-s.base { 429 return 0, os.EOF 430 } 431 off += s.base 432 if max := s.limit - off; int64(len(p)) > max { 433 p = p[0:max] 434 } 435 return s.r.ReadAt(p, off) 436 } 437 438 // Size returns the size of the section in bytes. 439 func (s *SectionReader) Size() int64 { return s.limit - s.base }