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