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 // 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 // Reader is the interface that wraps the basic Read method. 38 // 39 // Read reads up to len(p) bytes into p. It returns the number of bytes 40 // read (0 <= n <= len(p)) and any error encountered. Even if Read 41 // returns n < len(p), it may use all of p as scratch space during the call. 42 // If some data is available but not len(p) bytes, Read conventionally 43 // returns what is available instead of waiting for more. 44 // 45 // When Read encounters an error or end-of-file condition after 46 // successfully reading n > 0 bytes, it returns the number of 47 // bytes read. It may return the (non-nil) error from the same call 48 // or return the error (and n == 0) from a subsequent call. 49 // An instance of this general case is that a Reader returning 50 // a non-zero number of bytes at the end of the input stream may 51 // return either err == EOF or err == nil. The next Read should 52 // return 0, EOF regardless. 53 // 54 // Callers should always process the n > 0 bytes returned before 55 // considering the error err. Doing so correctly handles I/O errors 56 // that happen after reading some bytes and also both of the 57 // allowed EOF behaviors. 58 type Reader interface { 59 Read(p []byte) (n int, err error) 60 } 61 62 // Writer is the interface that wraps the basic Write method. 63 // 64 // Write writes len(p) bytes from p to the underlying data stream. 65 // It returns the number of bytes written from p (0 <= n <= len(p)) 66 // and any error encountered that caused the write to stop early. 67 // Write must return a non-nil error if it returns n < len(p). 68 type Writer interface { 69 Write(p []byte) (n int, err error) 70 } 71 72 // Closer is the interface that wraps the basic Close method. 73 type Closer interface { 74 Close() error 75 } 76 77 // Seeker is the interface that wraps the basic Seek method. 78 // 79 // Seek sets the offset for the next Read or Write to offset, 80 // interpreted according to whence: 0 means relative to the origin of 81 // the file, 1 means relative to the current offset, and 2 means 82 // relative to the end. Seek returns the new offset and an Error, if 83 // any. 84 type Seeker interface { 85 Seek(offset int64, whence int) (ret int64, err error) 86 } 87 88 // ReadWriter is the interface that groups the basic Read and Write methods. 89 type ReadWriter interface { 90 Reader 91 Writer 92 } 93 94 // ReadCloser is the interface that groups the basic Read and Close methods. 95 type ReadCloser interface { 96 Reader 97 Closer 98 } 99 100 // WriteCloser is the interface that groups the basic Write and Close methods. 101 type WriteCloser interface { 102 Writer 103 Closer 104 } 105 106 // ReadWriteCloser is the interface that groups the basic Read, Write and Close methods. 107 type ReadWriteCloser interface { 108 Reader 109 Writer 110 Closer 111 } 112 113 // ReadSeeker is the interface that groups the basic Read and Seek methods. 114 type ReadSeeker interface { 115 Reader 116 Seeker 117 } 118 119 // WriteSeeker is the interface that groups the basic Write and Seek methods. 120 type WriteSeeker interface { 121 Writer 122 Seeker 123 } 124 125 // ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods. 126 type ReadWriteSeeker interface { 127 Reader 128 Writer 129 Seeker 130 } 131 132 // ReaderFrom is the interface that wraps the ReadFrom method. 133 type ReaderFrom interface { 134 ReadFrom(r Reader) (n int64, err error) 135 } 136 137 // WriterTo is the interface that wraps the WriteTo method. 138 type WriterTo interface { 139 WriteTo(w Writer) (n int64, err error) 140 } 141 142 // ReaderAt is the interface that wraps the basic ReadAt method. 143 // 144 // ReadAt reads len(p) bytes into p starting at offset off in the 145 // underlying input source. It returns the number of bytes 146 // read (0 <= n <= len(p)) and any error encountered. 147 // 148 // When ReadAt returns n < len(p), it returns a non-nil error 149 // explaining why more bytes were not returned. In this respect, 150 // ReadAt is stricter than Read. 151 // 152 // Even if ReadAt returns n < len(p), it may use all of p as scratch 153 // space during the call. If some data is available but not len(p) bytes, 154 // ReadAt blocks until either all the data is available or an error occurs. 155 // In this respect ReadAt is different from Read. 156 // 157 // If the n = len(p) bytes returned by ReadAt are at the end of the 158 // input source, ReadAt may return either err == EOF or err == nil. 159 // 160 // If ReadAt is reading from an input source with a seek offset, 161 // ReadAt should not affect nor be affected by the underlying 162 // seek offset. 163 // 164 // Clients of ReadAt can execute parallel ReadAt calls on the 165 // same input source. 166 type ReaderAt interface { 167 ReadAt(p []byte, off int64) (n int, err error) 168 } 169 170 // WriterAt is the interface that wraps the basic WriteAt method. 171 // 172 // WriteAt writes len(p) bytes from p to the underlying data stream 173 // at offset off. It returns the number of bytes written from p (0 <= n <= len(p)) 174 // and any error encountered that caused the write to stop early. 175 // WriteAt must return a non-nil error if it returns n < len(p). 176 // 177 // If WriteAt is writing to a destination with a seek offset, 178 // WriteAt should not affect nor be affected by the underlying 179 // seek offset. 180 // 181 // Clients of WriteAt can execute parallel WriteAt calls on the same 182 // destination if the ranges do not overlap. 183 type WriterAt interface { 184 WriteAt(p []byte, off int64) (n int, err error) 185 } 186 187 // ByteReader is the interface that wraps the ReadByte method. 188 // 189 // ReadByte reads and returns the next byte from the input. 190 // If no byte is available, err will be set. 191 type ByteReader interface { 192 ReadByte() (c byte, err error) 193 } 194 195 // ByteScanner is the interface that adds the UnreadByte method to the 196 // basic ReadByte method. 197 // 198 // UnreadByte causes the next call to ReadByte to return the same byte 199 // as the previous call to ReadByte. 200 // It may be an error to call UnreadByte twice without an intervening 201 // call to ReadByte. 202 type ByteScanner interface { 203 ByteReader 204 UnreadByte() error 205 } 206 207 // RuneReader is the interface that wraps the ReadRune method. 208 // 209 // ReadRune reads a single UTF-8 encoded Unicode character 210 // and returns the rune and its size in bytes. If no character is 211 // available, err will be set. 212 type RuneReader interface { 213 ReadRune() (r rune, size int, err error) 214 } 215 216 // RuneScanner is the interface that adds the UnreadRune method to the 217 // basic ReadRune method. 218 // 219 // UnreadRune causes the next call to ReadRune to return the same rune 220 // as the previous call to ReadRune. 221 // It may be an error to call UnreadRune twice without an intervening 222 // call to ReadRune. 223 type RuneScanner interface { 224 RuneReader 225 UnreadRune() error 226 } 227 228 // stringWriter is the interface that wraps the WriteString method. 229 type stringWriter interface { 230 WriteString(s string) (n int, err error) 231 } 232 233 // WriteString writes the contents of the string s to w, which accepts an array of bytes. 234 // If w already implements a WriteString method, it is invoked directly. 235 func WriteString(w Writer, s string) (n int, err error) { 236 if sw, ok := w.(stringWriter); ok { 237 return sw.WriteString(s) 238 } 239 return w.Write([]byte(s)) 240 } 241 242 // ReadAtLeast reads from r into buf until it has read at least min bytes. 243 // It returns the number of bytes copied and an error if fewer bytes were read. 244 // The error is EOF only if no bytes were read. 245 // If an EOF happens after reading fewer than min bytes, 246 // ReadAtLeast returns ErrUnexpectedEOF. 247 // If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer. 248 func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error) { 249 if len(buf) < min { 250 return 0, ErrShortBuffer 251 } 252 for n < min && err == nil { 253 var nn int 254 nn, err = r.Read(buf[n:]) 255 n += nn 256 } 257 if err == EOF { 258 if n >= min { 259 err = nil 260 } else if n > 0 { 261 err = ErrUnexpectedEOF 262 } 263 } 264 return 265 } 266 267 // ReadFull reads exactly len(buf) bytes from r into buf. 268 // It returns the number of bytes copied and an error if fewer bytes were read. 269 // The error is EOF only if no bytes were read. 270 // If an EOF happens after reading some but not all the bytes, 271 // ReadFull returns ErrUnexpectedEOF. 272 func ReadFull(r Reader, buf []byte) (n int, err error) { 273 return ReadAtLeast(r, buf, len(buf)) 274 } 275 276 // CopyN copies n bytes (or until an error) from src to dst. 277 // It returns the number of bytes copied and the earliest 278 // error encountered while copying. Because Read can 279 // return the full amount requested as well as an error 280 // (including EOF), so can CopyN. 281 // 282 // If dst implements the ReaderFrom interface, 283 // the copy is implemented using it. 284 func CopyN(dst Writer, src Reader, n int64) (written int64, err error) { 285 // If the writer has a ReadFrom method, use it to do the copy. 286 // Avoids a buffer allocation and a copy. 287 if rt, ok := dst.(ReaderFrom); ok { 288 written, err = rt.ReadFrom(LimitReader(src, n)) 289 if written < n && err == nil { 290 // rt stopped early; must have been EOF. 291 err = EOF 292 } 293 return 294 } 295 buf := make([]byte, 32*1024) 296 for written < n { 297 l := len(buf) 298 if d := n - written; d < int64(l) { 299 l = int(d) 300 } 301 nr, er := src.Read(buf[0:l]) 302 if nr > 0 { 303 nw, ew := dst.Write(buf[0:nr]) 304 if nw > 0 { 305 written += int64(nw) 306 } 307 if ew != nil { 308 err = ew 309 break 310 } 311 if nr != nw { 312 err = ErrShortWrite 313 break 314 } 315 } 316 if er != nil { 317 err = er 318 break 319 } 320 } 321 return written, err 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 } 455 return s.r.ReadAt(p, off) 456 } 457 458 // Size returns the size of the section in bytes. 459 func (s *SectionReader) Size() int64 { return s.limit - s.base } 460 461 // TeeReader returns a Reader that writes to w what it reads from r. 462 // All reads from r performed through it are matched with 463 // corresponding writes to w. There is no internal buffering - 464 // the write must complete before the read completes. 465 // Any error encountered while writing is reported as a read error. 466 func TeeReader(r Reader, w Writer) Reader { 467 return &teeReader{r, w} 468 } 469 470 type teeReader struct { 471 r Reader 472 w Writer 473 } 474 475 func (t *teeReader) Read(p []byte) (n int, err error) { 476 n, err = t.r.Read(p) 477 if n > 0 { 478 if n, err := t.w.Write(p[:n]); err != nil { 479 return n, err 480 } 481 } 482 return 483 }