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