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.
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.
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.
20 // Seek whence values.
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
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")
31 // errInvalidWrite means that a write returned an impossible count.
32 var errInvalidWrite
= errors
.New("invalid write result")
34 // ErrShortBuffer means that a read required a longer buffer than was provided.
35 var ErrShortBuffer
= errors
.New("short buffer")
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")
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")
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")
55 // Reader is the interface that wraps the basic Read method.
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.
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
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.
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.
82 // Implementations must not retain p.
83 type Reader
interface {
84 Read(p
[]byte) (n
int, err error
)
87 // Writer is the interface that wraps the basic Write method.
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.
95 // Implementations must not retain p.
96 type Writer
interface {
97 Write(p
[]byte) (n
int, err error
)
100 // Closer is the interface that wraps the basic Close method.
102 // The behavior of Close after the first call is undefined.
103 // Specific implementations may document their own behavior.
104 type Closer
interface {
108 // Seeker is the interface that wraps the basic Seek method.
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.
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
)
125 // ReadWriter is the interface that groups the basic Read and Write methods.
126 type ReadWriter
interface {
131 // ReadCloser is the interface that groups the basic Read and Close methods.
132 type ReadCloser
interface {
137 // WriteCloser is the interface that groups the basic Write and Close methods.
138 type WriteCloser
interface {
143 // ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.
144 type ReadWriteCloser
interface {
150 // ReadSeeker is the interface that groups the basic Read and Seek methods.
151 type ReadSeeker
interface {
156 // ReadSeekCloser is the interface that groups the basic Read, Seek and Close
158 type ReadSeekCloser
interface {
164 // WriteSeeker is the interface that groups the basic Write and Seek methods.
165 type WriteSeeker
interface {
170 // ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.
171 type ReadWriteSeeker
interface {
177 // ReaderFrom is the interface that wraps the ReadFrom method.
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.
183 // The Copy function uses ReaderFrom if available.
184 type ReaderFrom
interface {
185 ReadFrom(r Reader
) (n
int64, err error
)
188 // WriterTo is the interface that wraps the WriteTo method.
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.
194 // The Copy function uses WriterTo if available.
195 type WriterTo
interface {
196 WriteTo(w Writer
) (n
int64, err error
)
199 // ReaderAt is the interface that wraps the basic ReadAt method.
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.
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.
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.
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.
217 // If ReadAt is reading from an input source with a seek offset,
218 // ReadAt should not affect nor be affected by the underlying
221 // Clients of ReadAt can execute parallel ReadAt calls on the
222 // same input source.
224 // Implementations must not retain p.
225 type ReaderAt
interface {
226 ReadAt(p
[]byte, off
int64) (n
int, err error
)
229 // WriterAt is the interface that wraps the basic WriteAt method.
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).
236 // If WriteAt is writing to a destination with a seek offset,
237 // WriteAt should not affect nor be affected by the underlying
240 // Clients of WriteAt can execute parallel WriteAt calls on the same
241 // destination if the ranges do not overlap.
243 // Implementations must not retain p.
244 type WriterAt
interface {
245 WriteAt(p
[]byte, off
int64) (n
int, err error
)
248 // ByteReader is the interface that wraps the ReadByte method.
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.
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
)
261 // ByteScanner is the interface that adds the UnreadByte method to the
262 // basic ReadByte method.
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
268 type ByteScanner
interface {
273 // ByteWriter is the interface that wraps the WriteByte method.
274 type ByteWriter
interface {
275 WriteByte(c
byte) error
278 // RuneReader is the interface that wraps the ReadRune method.
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
)
287 // RuneScanner is the interface that adds the UnreadRune method to the
288 // basic ReadRune method.
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
294 type RuneScanner
interface {
299 // StringWriter is the interface that wraps the WriteString method.
300 type StringWriter
interface {
301 WriteString(s
string) (n
int, err error
)
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
)
311 return w
.Write([]byte(s
))
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
) {
324 return 0, ErrShortBuffer
326 for n
< min
&& err
== nil {
328 nn
, err
= r
.Read(buf
[n
:])
333 } else if n
> 0 && err
== EOF
{
334 err
= ErrUnexpectedEOF
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
))
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.
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
))
362 if written
< n
&& err
== nil {
363 // src stopped early; must have been EOF.
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.
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.
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)
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.
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")
396 return copyBuffer(dst
, src
, buf
)
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
)
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
)
413 if l
, ok
:= src
.(*LimitedReader
); ok
&& int64(size
) > l
.N
{
420 buf
= make([]byte, size
)
423 nr
, er
:= src
.Read(buf
)
425 nw
, ew
:= dst
.Write(buf
[0:nr
])
426 if nw
< 0 || nr
< nw
{
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
} }
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
466 func (l
*LimitedReader
) Read(p
[]byte) (n
int, err error
) {
470 if int64(len(p
)) > l
.N
{
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
}
484 // SectionReader implements Read, Seek, and ReadAt on a section
485 // of an underlying ReaderAt.
486 type SectionReader
struct {
493 func (s
*SectionReader
) Read(p
[]byte) (n
int, err error
) {
494 if s
.off
>= s
.limit
{
497 if max
:= s
.limit
- s
.off
; int64(len(p
)) > max
{
500 n
, err
= s
.r
.ReadAt(p
, s
.off
)
505 var errWhence
= errors
.New("Seek: invalid whence")
506 var errOffset
= errors
.New("Seek: invalid offset")
508 func (s
*SectionReader
) Seek(offset
int64, whence
int) (int64, error
) {
523 return offset
- s
.base
, nil
526 func (s
*SectionReader
) ReadAt(p
[]byte, off
int64) (n
int, err error
) {
527 if off
< 0 || off
>= s
.limit
-s
.base
{
531 if max
:= s
.limit
- off
; int64(len(p
)) > max
{
533 n
, err
= s
.r
.ReadAt(p
, off
)
539 return s
.r
.ReadAt(p
, off
)
542 // Size returns the size of the section in bytes.
543 func (s
*SectionReader
) Size() int64 { return s
.limit
- s
.base
}
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
}
554 type teeReader
struct {
559 func (t
*teeReader
) Read(p
[]byte) (n
int, err error
) {
562 if n
, err
:= t
.w
.Write(p
[:n
]); err
!= nil {
569 // Discard is an Writer on which all Write calls succeed
570 // without doing anything.
571 var Discard Writer
= discard
{}
573 type discard
struct{}
575 // discard implements ReaderFrom as an optimization so Copy to
576 // io.Discard can avoid doing unnecessary work.
577 var _ ReaderFrom
= discard
{}
579 func (discard
) Write(p
[]byte) (int, error
) {
583 func (discard
) WriteString(s
string) (int, error
) {
587 var blackHolePool
= sync
.Pool
{
588 New
: func() interface{} {
589 b
:= make([]byte, 8192)
594 func (discard
) ReadFrom(r Reader
) (n
int64, err error
) {
595 bufp
:= blackHolePool
.Get().(*[]byte)
598 readSize
, err
= r
.Read(*bufp
)
601 blackHolePool
.Put(bufp
)
610 // NopCloser returns a ReadCloser with a no-op Close method wrapping
611 // the provided Reader r.
612 func NopCloser(r Reader
) ReadCloser
{
616 type nopCloser
struct {
620 func (nopCloser
) Close() error
{ return nil }
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)
629 if len(b
) == cap(b
) {
630 // Add more capacity (let append pick how much).
631 b
= append(b
, 0)[:len(b
)]
633 n
, err
:= r
.Read(b
[len(b
):cap(b
)])