Source file src/io/io.go
Documentation: io
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 // 10 // Because these interfaces and primitives wrap lower-level operations with 11 // various implementations, unless otherwise informed clients should not 12 // assume they are safe for parallel execution. 13 package io 14 15 import ( 16 "errors" 17 "sync" 18 ) 19 20 // Seek whence values. 21 const ( 22 SeekStart = 0 // seek relative to the origin of the file 23 SeekCurrent = 1 // seek relative to the current offset 24 SeekEnd = 2 // seek relative to the end 25 ) 26 27 // ErrShortWrite means that a write accepted fewer bytes than requested 28 // but failed to return an explicit error. 29 var ErrShortWrite = errors.New("short write") 30 31 // errInvalidWrite means that a write returned an impossible count. 32 var errInvalidWrite = errors.New("invalid write result") 33 34 // ErrShortBuffer means that a read required a longer buffer than was provided. 35 var ErrShortBuffer = errors.New("short buffer") 36 37 // EOF is the error returned by Read when no more input is available. 38 // (Read must return EOF itself, not an error wrapping EOF, 39 // because callers will test for EOF using ==.) 40 // Functions should return EOF only to signal a graceful end of input. 41 // If the EOF occurs unexpectedly in a structured data stream, 42 // the appropriate error is either ErrUnexpectedEOF or some other error 43 // giving more detail. 44 var EOF = errors.New("EOF") 45 46 // ErrUnexpectedEOF means that EOF was encountered in the 47 // middle of reading a fixed-size block or data structure. 48 var ErrUnexpectedEOF = errors.New("unexpected EOF") 49 50 // ErrNoProgress is returned by some clients of an Reader when 51 // many calls to Read have failed to return any data or error, 52 // usually the sign of a broken Reader implementation. 53 var ErrNoProgress = errors.New("multiple Read calls return no data or error") 54 55 // Reader is the interface that wraps the basic Read method. 56 // 57 // Read reads up to len(p) bytes into p. It returns the number of bytes 58 // read (0 <= n <= len(p)) and any error encountered. Even if Read 59 // returns n < len(p), it may use all of p as scratch space during the call. 60 // If some data is available but not len(p) bytes, Read conventionally 61 // returns what is available instead of waiting for more. 62 // 63 // When Read encounters an error or end-of-file condition after 64 // successfully reading n > 0 bytes, it returns the number of 65 // bytes read. It may return the (non-nil) error from the same call 66 // or return the error (and n == 0) from a subsequent call. 67 // An instance of this general case is that a Reader returning 68 // a non-zero number of bytes at the end of the input stream may 69 // return either err == EOF or err == nil. The next Read should 70 // return 0, EOF. 71 // 72 // Callers should always process the n > 0 bytes returned before 73 // considering the error err. Doing so correctly handles I/O errors 74 // that happen after reading some bytes and also both of the 75 // allowed EOF behaviors. 76 // 77 // Implementations of Read are discouraged from returning a 78 // zero byte count with a nil error, except when len(p) == 0. 79 // Callers should treat a return of 0 and nil as indicating that 80 // nothing happened; in particular it does not indicate EOF. 81 // 82 // Implementations must not retain p. 83 type Reader interface { 84 Read(p []byte) (n int, err error) 85 } 86 87 // Writer is the interface that wraps the basic Write method. 88 // 89 // Write writes len(p) bytes from p to the underlying data stream. 90 // It returns the number of bytes written from p (0 <= n <= len(p)) 91 // and any error encountered that caused the write to stop early. 92 // Write must return a non-nil error if it returns n < len(p). 93 // Write must not modify the slice data, even temporarily. 94 // 95 // Implementations must not retain p. 96 type Writer interface { 97 Write(p []byte) (n int, err error) 98 } 99 100 // Closer is the interface that wraps the basic Close method. 101 // 102 // The behavior of Close after the first call is undefined. 103 // Specific implementations may document their own behavior. 104 type Closer interface { 105 Close() error 106 } 107 108 // Seeker is the interface that wraps the basic Seek method. 109 // 110 // Seek sets the offset for the next Read or Write to offset, 111 // interpreted according to whence: 112 // SeekStart means relative to the start of the file, 113 // SeekCurrent means relative to the current offset, and 114 // SeekEnd means relative to the end. 115 // Seek returns the new offset relative to the start of the 116 // file and an error, if any. 117 // 118 // Seeking to an offset before the start of the file is an error. 119 // Seeking to any positive offset is legal, but the behavior of subsequent 120 // I/O operations on the underlying object is implementation-dependent. 121 type Seeker interface { 122 Seek(offset int64, whence int) (int64, error) 123 } 124 125 // ReadWriter is the interface that groups the basic Read and Write methods. 126 type ReadWriter interface { 127 Reader 128 Writer 129 } 130 131 // ReadCloser is the interface that groups the basic Read and Close methods. 132 type ReadCloser interface { 133 Reader 134 Closer 135 } 136 137 // WriteCloser is the interface that groups the basic Write and Close methods. 138 type WriteCloser interface { 139 Writer 140 Closer 141 } 142 143 // ReadWriteCloser is the interface that groups the basic Read, Write and Close methods. 144 type ReadWriteCloser interface { 145 Reader 146 Writer 147 Closer 148 } 149 150 // ReadSeeker is the interface that groups the basic Read and Seek methods. 151 type ReadSeeker interface { 152 Reader 153 Seeker 154 } 155 156 // ReadSeekCloser is the interface that groups the basic Read, Seek and Close 157 // methods. 158 type ReadSeekCloser interface { 159 Reader 160 Seeker 161 Closer 162 } 163 164 // WriteSeeker is the interface that groups the basic Write and Seek methods. 165 type WriteSeeker interface { 166 Writer 167 Seeker 168 } 169 170 // ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods. 171 type ReadWriteSeeker interface { 172 Reader 173 Writer 174 Seeker 175 } 176 177 // ReaderFrom is the interface that wraps the ReadFrom method. 178 // 179 // ReadFrom reads data from r until EOF or error. 180 // The return value n is the number of bytes read. 181 // Any error except EOF encountered during the read is also returned. 182 // 183 // The Copy function uses ReaderFrom if available. 184 type ReaderFrom interface { 185 ReadFrom(r Reader) (n int64, err error) 186 } 187 188 // WriterTo is the interface that wraps the WriteTo method. 189 // 190 // WriteTo writes data to w until there's no more data to write or 191 // when an error occurs. The return value n is the number of bytes 192 // written. Any error encountered during the write is also returned. 193 // 194 // The Copy function uses WriterTo if available. 195 type WriterTo interface { 196 WriteTo(w Writer) (n int64, err error) 197 } 198 199 // ReaderAt is the interface that wraps the basic ReadAt method. 200 // 201 // ReadAt reads len(p) bytes into p starting at offset off in the 202 // underlying input source. It returns the number of bytes 203 // read (0 <= n <= len(p)) and any error encountered. 204 // 205 // When ReadAt returns n < len(p), it returns a non-nil error 206 // explaining why more bytes were not returned. In this respect, 207 // ReadAt is stricter than Read. 208 // 209 // Even if ReadAt returns n < len(p), it may use all of p as scratch 210 // space during the call. If some data is available but not len(p) bytes, 211 // ReadAt blocks until either all the data is available or an error occurs. 212 // In this respect ReadAt is different from Read. 213 // 214 // If the n = len(p) bytes returned by ReadAt are at the end of the 215 // input source, ReadAt may return either err == EOF or err == nil. 216 // 217 // If ReadAt is reading from an input source with a seek offset, 218 // ReadAt should not affect nor be affected by the underlying 219 // seek offset. 220 // 221 // Clients of ReadAt can execute parallel ReadAt calls on the 222 // same input source. 223 // 224 // Implementations must not retain p. 225 type ReaderAt interface { 226 ReadAt(p []byte, off int64) (n int, err error) 227 } 228 229 // WriterAt is the interface that wraps the basic WriteAt method. 230 // 231 // WriteAt writes len(p) bytes from p to the underlying data stream 232 // at offset off. It returns the number of bytes written from p (0 <= n <= len(p)) 233 // and any error encountered that caused the write to stop early. 234 // WriteAt must return a non-nil error if it returns n < len(p). 235 // 236 // If WriteAt is writing to a destination with a seek offset, 237 // WriteAt should not affect nor be affected by the underlying 238 // seek offset. 239 // 240 // Clients of WriteAt can execute parallel WriteAt calls on the same 241 // destination if the ranges do not overlap. 242 // 243 // Implementations must not retain p. 244 type WriterAt interface { 245 WriteAt(p []byte, off int64) (n int, err error) 246 } 247 248 // ByteReader is the interface that wraps the ReadByte method. 249 // 250 // ReadByte reads and returns the next byte from the input or 251 // any error encountered. If ReadByte returns an error, no input 252 // byte was consumed, and the returned byte value is undefined. 253 // 254 // ReadByte provides an efficient interface for byte-at-time 255 // processing. A Reader that does not implement ByteReader 256 // can be wrapped using bufio.NewReader to add this method. 257 type ByteReader interface { 258 ReadByte() (byte, error) 259 } 260 261 // ByteScanner is the interface that adds the UnreadByte method to the 262 // basic ReadByte method. 263 // 264 // UnreadByte causes the next call to ReadByte to return the same byte 265 // as the previous call to ReadByte. 266 // It may be an error to call UnreadByte twice without an intervening 267 // call to ReadByte. 268 type ByteScanner interface { 269 ByteReader 270 UnreadByte() error 271 } 272 273 // ByteWriter is the interface that wraps the WriteByte method. 274 type ByteWriter interface { 275 WriteByte(c byte) error 276 } 277 278 // RuneReader is the interface that wraps the ReadRune method. 279 // 280 // ReadRune reads a single UTF-8 encoded Unicode character 281 // and returns the rune and its size in bytes. If no character is 282 // available, err will be set. 283 type RuneReader interface { 284 ReadRune() (r rune, size int, err error) 285 } 286 287 // RuneScanner is the interface that adds the UnreadRune method to the 288 // basic ReadRune method. 289 // 290 // UnreadRune causes the next call to ReadRune to return the same rune 291 // as the previous call to ReadRune. 292 // It may be an error to call UnreadRune twice without an intervening 293 // call to ReadRune. 294 type RuneScanner interface { 295 RuneReader 296 UnreadRune() error 297 } 298 299 // StringWriter is the interface that wraps the WriteString method. 300 type StringWriter interface { 301 WriteString(s string) (n int, err error) 302 } 303 304 // WriteString writes the contents of the string s to w, which accepts a slice of bytes. 305 // If w implements StringWriter, its WriteString method is invoked directly. 306 // Otherwise, w.Write is called exactly once. 307 func WriteString(w Writer, s string) (n int, err error) { 308 if sw, ok := w.(StringWriter); ok { 309 return sw.WriteString(s) 310 } 311 return w.Write([]byte(s)) 312 } 313 314 // ReadAtLeast reads from r into buf until it has read at least min bytes. 315 // It returns the number of bytes copied and an error if fewer bytes were read. 316 // The error is EOF only if no bytes were read. 317 // If an EOF happens after reading fewer than min bytes, 318 // ReadAtLeast returns ErrUnexpectedEOF. 319 // If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer. 320 // On return, n >= min if and only if err == nil. 321 // If r returns an error having read at least min bytes, the error is dropped. 322 func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error) { 323 if len(buf) < min { 324 return 0, ErrShortBuffer 325 } 326 for n < min && err == nil { 327 var nn int 328 nn, err = r.Read(buf[n:]) 329 n += nn 330 } 331 if n >= min { 332 err = nil 333 } else if n > 0 && err == EOF { 334 err = ErrUnexpectedEOF 335 } 336 return 337 } 338 339 // ReadFull reads exactly len(buf) bytes from r into buf. 340 // It returns the number of bytes copied and an error if fewer bytes were read. 341 // The error is EOF only if no bytes were read. 342 // If an EOF happens after reading some but not all the bytes, 343 // ReadFull returns ErrUnexpectedEOF. 344 // On return, n == len(buf) if and only if err == nil. 345 // If r returns an error having read at least len(buf) bytes, the error is dropped. 346 func ReadFull(r Reader, buf []byte) (n int, err error) { 347 return ReadAtLeast(r, buf, len(buf)) 348 } 349 350 // CopyN copies n bytes (or until an error) from src to dst. 351 // It returns the number of bytes copied and the earliest 352 // error encountered while copying. 353 // On return, written == n if and only if err == nil. 354 // 355 // If dst implements the ReaderFrom interface, 356 // the copy is implemented using it. 357 func CopyN(dst Writer, src Reader, n int64) (written int64, err error) { 358 written, err = Copy(dst, LimitReader(src, n)) 359 if written == n { 360 return n, nil 361 } 362 if written < n && err == nil { 363 // src stopped early; must have been EOF. 364 err = EOF 365 } 366 return 367 } 368 369 // Copy copies from src to dst until either EOF is reached 370 // on src or an error occurs. It returns the number of bytes 371 // copied and the first error encountered while copying, if any. 372 // 373 // A successful Copy returns err == nil, not err == EOF. 374 // Because Copy is defined to read from src until EOF, it does 375 // not treat an EOF from Read as an error to be reported. 376 // 377 // If src implements the WriterTo interface, 378 // the copy is implemented by calling src.WriteTo(dst). 379 // Otherwise, if dst implements the ReaderFrom interface, 380 // the copy is implemented by calling dst.ReadFrom(src). 381 func Copy(dst Writer, src Reader) (written int64, err error) { 382 return copyBuffer(dst, src, nil) 383 } 384 385 // CopyBuffer is identical to Copy except that it stages through the 386 // provided buffer (if one is required) rather than allocating a 387 // temporary one. If buf is nil, one is allocated; otherwise if it has 388 // zero length, CopyBuffer panics. 389 // 390 // If either src implements WriterTo or dst implements ReaderFrom, 391 // buf will not be used to perform the copy. 392 func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) { 393 if buf != nil && len(buf) == 0 { 394 panic("empty buffer in CopyBuffer") 395 } 396 return copyBuffer(dst, src, buf) 397 } 398 399 // copyBuffer is the actual implementation of Copy and CopyBuffer. 400 // if buf is nil, one is allocated. 401 func copyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) { 402 // If the reader has a WriteTo method, use it to do the copy. 403 // Avoids an allocation and a copy. 404 if wt, ok := src.(WriterTo); ok { 405 return wt.WriteTo(dst) 406 } 407 // Similarly, if the writer has a ReadFrom method, use it to do the copy. 408 if rt, ok := dst.(ReaderFrom); ok { 409 return rt.ReadFrom(src) 410 } 411 if buf == nil { 412 size := 32 * 1024 413 if l, ok := src.(*LimitedReader); ok && int64(size) > l.N { 414 if l.N < 1 { 415 size = 1 416 } else { 417 size = int(l.N) 418 } 419 } 420 buf = make([]byte, size) 421 } 422 for { 423 nr, er := src.Read(buf) 424 if nr > 0 { 425 nw, ew := dst.Write(buf[0:nr]) 426 if nw < 0 || nr < nw { 427 nw = 0 428 if ew == nil { 429 ew = errInvalidWrite 430 } 431 } 432 written += int64(nw) 433 if ew != nil { 434 err = ew 435 break 436 } 437 if nr != nw { 438 err = ErrShortWrite 439 break 440 } 441 } 442 if er != nil { 443 if er != EOF { 444 err = er 445 } 446 break 447 } 448 } 449 return written, err 450 } 451 452 // LimitReader returns a Reader that reads from r 453 // but stops with EOF after n bytes. 454 // The underlying implementation is a *LimitedReader. 455 func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} } 456 457 // A LimitedReader reads from R but limits the amount of 458 // data returned to just N bytes. Each call to Read 459 // updates N to reflect the new amount remaining. 460 // Read returns EOF when N <= 0 or when the underlying R returns EOF. 461 type LimitedReader struct { 462 R Reader // underlying reader 463 N int64 // max bytes remaining 464 } 465 466 func (l *LimitedReader) Read(p []byte) (n int, err error) { 467 if l.N <= 0 { 468 return 0, EOF 469 } 470 if int64(len(p)) > l.N { 471 p = p[0:l.N] 472 } 473 n, err = l.R.Read(p) 474 l.N -= int64(n) 475 return 476 } 477 478 // NewSectionReader returns a SectionReader that reads from r 479 // starting at offset off and stops with EOF after n bytes. 480 func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader { 481 return &SectionReader{r, off, off, off + n} 482 } 483 484 // SectionReader implements Read, Seek, and ReadAt on a section 485 // of an underlying ReaderAt. 486 type SectionReader struct { 487 r ReaderAt 488 base int64 489 off int64 490 limit int64 491 } 492 493 func (s *SectionReader) Read(p []byte) (n int, err error) { 494 if s.off >= s.limit { 495 return 0, EOF 496 } 497 if max := s.limit - s.off; int64(len(p)) > max { 498 p = p[0:max] 499 } 500 n, err = s.r.ReadAt(p, s.off) 501 s.off += int64(n) 502 return 503 } 504 505 var errWhence = errors.New("Seek: invalid whence") 506 var errOffset = errors.New("Seek: invalid offset") 507 508 func (s *SectionReader) Seek(offset int64, whence int) (int64, error) { 509 switch whence { 510 default: 511 return 0, errWhence 512 case SeekStart: 513 offset += s.base 514 case SeekCurrent: 515 offset += s.off 516 case SeekEnd: 517 offset += s.limit 518 } 519 if offset < s.base { 520 return 0, errOffset 521 } 522 s.off = offset 523 return offset - s.base, nil 524 } 525 526 func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error) { 527 if off < 0 || off >= s.limit-s.base { 528 return 0, EOF 529 } 530 off += s.base 531 if max := s.limit - off; int64(len(p)) > max { 532 p = p[0:max] 533 n, err = s.r.ReadAt(p, off) 534 if err == nil { 535 err = EOF 536 } 537 return n, err 538 } 539 return s.r.ReadAt(p, off) 540 } 541 542 // Size returns the size of the section in bytes. 543 func (s *SectionReader) Size() int64 { return s.limit - s.base } 544 545 // TeeReader returns a Reader that writes to w what it reads from r. 546 // All reads from r performed through it are matched with 547 // corresponding writes to w. There is no internal buffering - 548 // the write must complete before the read completes. 549 // Any error encountered while writing is reported as a read error. 550 func TeeReader(r Reader, w Writer) Reader { 551 return &teeReader{r, w} 552 } 553 554 type teeReader struct { 555 r Reader 556 w Writer 557 } 558 559 func (t *teeReader) Read(p []byte) (n int, err error) { 560 n, err = t.r.Read(p) 561 if n > 0 { 562 if n, err := t.w.Write(p[:n]); err != nil { 563 return n, err 564 } 565 } 566 return 567 } 568 569 // Discard is an Writer on which all Write calls succeed 570 // without doing anything. 571 var Discard Writer = discard{} 572 573 type discard struct{} 574 575 // discard implements ReaderFrom as an optimization so Copy to 576 // io.Discard can avoid doing unnecessary work. 577 var _ ReaderFrom = discard{} 578 579 func (discard) Write(p []byte) (int, error) { 580 return len(p), nil 581 } 582 583 func (discard) WriteString(s string) (int, error) { 584 return len(s), nil 585 } 586 587 var blackHolePool = sync.Pool{ 588 New: func() interface{} { 589 b := make([]byte, 8192) 590 return &b 591 }, 592 } 593 594 func (discard) ReadFrom(r Reader) (n int64, err error) { 595 bufp := blackHolePool.Get().(*[]byte) 596 readSize := 0 597 for { 598 readSize, err = r.Read(*bufp) 599 n += int64(readSize) 600 if err != nil { 601 blackHolePool.Put(bufp) 602 if err == EOF { 603 return n, nil 604 } 605 return 606 } 607 } 608 } 609 610 // NopCloser returns a ReadCloser with a no-op Close method wrapping 611 // the provided Reader r. 612 func NopCloser(r Reader) ReadCloser { 613 return nopCloser{r} 614 } 615 616 type nopCloser struct { 617 Reader 618 } 619 620 func (nopCloser) Close() error { return nil } 621 622 // ReadAll reads from r until an error or EOF and returns the data it read. 623 // A successful call returns err == nil, not err == EOF. Because ReadAll is 624 // defined to read from src until EOF, it does not treat an EOF from Read 625 // as an error to be reported. 626 func ReadAll(r Reader) ([]byte, error) { 627 b := make([]byte, 0, 512) 628 for { 629 if len(b) == cap(b) { 630 // Add more capacity (let append pick how much). 631 b = append(b, 0)[:len(b)] 632 } 633 n, err := r.Read(b[len(b):cap(b)]) 634 b = b[:len(b)+n] 635 if err != nil { 636 if err == EOF { 637 err = nil 638 } 639 return b, err 640 } 641 } 642 } 643