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 }