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.
13package io
14
15import (
16	"errors"
17)
18
19// Seek whence values.
20const (
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.
28var ErrShortWrite = errors.New("short write")
29
30// ErrShortBuffer means that a read required a longer buffer than was provided.
31var 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.
38var 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.
42var 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.
47var 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.
77type 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.
90type 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.
98type 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.
115type 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.
120type ReadWriter interface {
121	Reader
122	Writer
123}
124
125// ReadCloser is the interface that groups the basic Read and Close methods.
126type ReadCloser interface {
127	Reader
128	Closer
129}
130
131// WriteCloser is the interface that groups the basic Write and Close methods.
132type WriteCloser interface {
133	Writer
134	Closer
135}
136
137// ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.
138type ReadWriteCloser interface {
139	Reader
140	Writer
141	Closer
142}
143
144// ReadSeeker is the interface that groups the basic Read and Seek methods.
145type ReadSeeker interface {
146	Reader
147	Seeker
148}
149
150// WriteSeeker is the interface that groups the basic Write and Seek methods.
151type WriteSeeker interface {
152	Writer
153	Seeker
154}
155
156// ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.
157type 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.
170type 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.
181type 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.
211type 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.
230type 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.
239type ByteReader interface {
240	ReadByte() (byte, error)
241}
242
243// ByteScanner is the interface that adds the UnreadByte method to the
244// basic ReadByte method.
245//
246// UnreadByte causes the next call to ReadByte to return the same byte
247// as the previous call to ReadByte.
248// It may be an error to call UnreadByte twice without an intervening
249// call to ReadByte.
250type ByteScanner interface {
251	ByteReader
252	UnreadByte() error
253}
254
255// ByteWriter is the interface that wraps the WriteByte method.
256type ByteWriter interface {
257	WriteByte(c byte) error
258}
259
260// RuneReader is the interface that wraps the ReadRune method.
261//
262// ReadRune reads a single UTF-8 encoded Unicode character
263// and returns the rune and its size in bytes. If no character is
264// available, err will be set.
265type RuneReader interface {
266	ReadRune() (r rune, size int, err error)
267}
268
269// RuneScanner is the interface that adds the UnreadRune method to the
270// basic ReadRune method.
271//
272// UnreadRune causes the next call to ReadRune to return the same rune
273// as the previous call to ReadRune.
274// It may be an error to call UnreadRune twice without an intervening
275// call to ReadRune.
276type RuneScanner interface {
277	RuneReader
278	UnreadRune() error
279}
280
281// StringWriter is the interface that wraps the WriteString method.
282type StringWriter interface {
283	WriteString(s string) (n int, err error)
284}
285
286// WriteString writes the contents of the string s to w, which accepts a slice of bytes.
287// If w implements StringWriter, its WriteString method is invoked directly.
288// Otherwise, w.Write is called exactly once.
289func WriteString(w Writer, s string) (n int, err error) {
290	if sw, ok := w.(StringWriter); ok {
291		return sw.WriteString(s)
292	}
293	return w.Write([]byte(s))
294}
295
296// ReadAtLeast reads from r into buf until it has read at least min bytes.
297// It returns the number of bytes copied and an error if fewer bytes were read.
298// The error is EOF only if no bytes were read.
299// If an EOF happens after reading fewer than min bytes,
300// ReadAtLeast returns ErrUnexpectedEOF.
301// If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer.
302// On return, n >= min if and only if err == nil.
303// If r returns an error having read at least min bytes, the error is dropped.
304func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error) {
305	if len(buf) < min {
306		return 0, ErrShortBuffer
307	}
308	for n < min && err == nil {
309		var nn int
310		nn, err = r.Read(buf[n:])
311		n += nn
312	}
313	if n >= min {
314		err = nil
315	} else if n > 0 && err == EOF {
316		err = ErrUnexpectedEOF
317	}
318	return
319}
320
321// ReadFull reads exactly len(buf) bytes from r into buf.
322// It returns the number of bytes copied and an error if fewer bytes were read.
323// The error is EOF only if no bytes were read.
324// If an EOF happens after reading some but not all the bytes,
325// ReadFull returns ErrUnexpectedEOF.
326// On return, n == len(buf) if and only if err == nil.
327// If r returns an error having read at least len(buf) bytes, the error is dropped.
328func ReadFull(r Reader, buf []byte) (n int, err error) {
329	return ReadAtLeast(r, buf, len(buf))
330}
331
332// CopyN copies n bytes (or until an error) from src to dst.
333// It returns the number of bytes copied and the earliest
334// error encountered while copying.
335// On return, written == n if and only if err == nil.
336//
337// If dst implements the ReaderFrom interface,
338// the copy is implemented using it.
339func CopyN(dst Writer, src Reader, n int64) (written int64, err error) {
340	written, err = Copy(dst, LimitReader(src, n))
341	if written == n {
342		return n, nil
343	}
344	if written < n && err == nil {
345		// src stopped early; must have been EOF.
346		err = EOF
347	}
348	return
349}
350
351// Copy copies from src to dst until either EOF is reached
352// on src or an error occurs. It returns the number of bytes
353// copied and the first error encountered while copying, if any.
354//
355// A successful Copy returns err == nil, not err == EOF.
356// Because Copy is defined to read from src until EOF, it does
357// not treat an EOF from Read as an error to be reported.
358//
359// If src implements the WriterTo interface,
360// the copy is implemented by calling src.WriteTo(dst).
361// Otherwise, if dst implements the ReaderFrom interface,
362// the copy is implemented by calling dst.ReadFrom(src).
363func Copy(dst Writer, src Reader) (written int64, err error) {
364	return copyBuffer(dst, src, nil)
365}
366
367// CopyBuffer is identical to Copy except that it stages through the
368// provided buffer (if one is required) rather than allocating a
369// temporary one. If buf is nil, one is allocated; otherwise if it has
370// zero length, CopyBuffer panics.
371func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
372	if buf != nil && len(buf) == 0 {
373		panic("empty buffer in io.CopyBuffer")
374	}
375	return copyBuffer(dst, src, buf)
376}
377
378// copyBuffer is the actual implementation of Copy and CopyBuffer.
379// if buf is nil, one is allocated.
380func copyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
381	// If the reader has a WriteTo method, use it to do the copy.
382	// Avoids an allocation and a copy.
383	if wt, ok := src.(WriterTo); ok {
384		return wt.WriteTo(dst)
385	}
386	// Similarly, if the writer has a ReadFrom method, use it to do the copy.
387	if rt, ok := dst.(ReaderFrom); ok {
388		return rt.ReadFrom(src)
389	}
390	if buf == nil {
391		size := 32 * 1024
392		if l, ok := src.(*LimitedReader); ok && int64(size) > l.N {
393			if l.N < 1 {
394				size = 1
395			} else {
396				size = int(l.N)
397			}
398		}
399		buf = make([]byte, size)
400	}
401	for {
402		nr, er := src.Read(buf)
403		if nr > 0 {
404			nw, ew := dst.Write(buf[0:nr])
405			if nw > 0 {
406				written += int64(nw)
407			}
408			if ew != nil {
409				err = ew
410				break
411			}
412			if nr != nw {
413				err = ErrShortWrite
414				break
415			}
416		}
417		if er != nil {
418			if er != EOF {
419				err = er
420			}
421			break
422		}
423	}
424	return written, err
425}
426
427// LimitReader returns a Reader that reads from r
428// but stops with EOF after n bytes.
429// The underlying implementation is a *LimitedReader.
430func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }
431
432// A LimitedReader reads from R but limits the amount of
433// data returned to just N bytes. Each call to Read
434// updates N to reflect the new amount remaining.
435// Read returns EOF when N <= 0 or when the underlying R returns EOF.
436type LimitedReader struct {
437	R Reader // underlying reader
438	N int64  // max bytes remaining
439}
440
441func (l *LimitedReader) Read(p []byte) (n int, err error) {
442	if l.N <= 0 {
443		return 0, EOF
444	}
445	if int64(len(p)) > l.N {
446		p = p[0:l.N]
447	}
448	n, err = l.R.Read(p)
449	l.N -= int64(n)
450	return
451}
452
453// NewSectionReader returns a SectionReader that reads from r
454// starting at offset off and stops with EOF after n bytes.
455func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader {
456	return &SectionReader{r, off, off, off + n}
457}
458
459// SectionReader implements Read, Seek, and ReadAt on a section
460// of an underlying ReaderAt.
461type SectionReader struct {
462	r     ReaderAt
463	base  int64
464	off   int64
465	limit int64
466}
467
468func (s *SectionReader) Read(p []byte) (n int, err error) {
469	if s.off >= s.limit {
470		return 0, EOF
471	}
472	if max := s.limit - s.off; int64(len(p)) > max {
473		p = p[0:max]
474	}
475	n, err = s.r.ReadAt(p, s.off)
476	s.off += int64(n)
477	return
478}
479
480var errWhence = errors.New("Seek: invalid whence")
481var errOffset = errors.New("Seek: invalid offset")
482
483func (s *SectionReader) Seek(offset int64, whence int) (int64, error) {
484	switch whence {
485	default:
486		return 0, errWhence
487	case SeekStart:
488		offset += s.base
489	case SeekCurrent:
490		offset += s.off
491	case SeekEnd:
492		offset += s.limit
493	}
494	if offset < s.base {
495		return 0, errOffset
496	}
497	s.off = offset
498	return offset - s.base, nil
499}
500
501func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error) {
502	if off < 0 || off >= s.limit-s.base {
503		return 0, EOF
504	}
505	off += s.base
506	if max := s.limit - off; int64(len(p)) > max {
507		p = p[0:max]
508		n, err = s.r.ReadAt(p, off)
509		if err == nil {
510			err = EOF
511		}
512		return n, err
513	}
514	return s.r.ReadAt(p, off)
515}
516
517// Size returns the size of the section in bytes.
518func (s *SectionReader) Size() int64 { return s.limit - s.base }
519
520// TeeReader returns a Reader that writes to w what it reads from r.
521// All reads from r performed through it are matched with
522// corresponding writes to w. There is no internal buffering -
523// the write must complete before the read completes.
524// Any error encountered while writing is reported as a read error.
525func TeeReader(r Reader, w Writer) Reader {
526	return &teeReader{r, w}
527}
528
529type teeReader struct {
530	r Reader
531	w Writer
532}
533
534func (t *teeReader) Read(p []byte) (n int, err error) {
535	n, err = t.r.Read(p)
536	if n > 0 {
537		if n, err := t.w.Write(p[:n]); err != nil {
538			return n, err
539		}
540	}
541	return
542}
543