// abstract the functionality, plus some other related primitives.
package io
-import "os"
-
// Error represents an unexpected I/O behavior.
type Error struct {
ErrorString string
}
-func (err *Error) String() string { return err.ErrorString }
+func (err *Error) Error() string { return err.ErrorString }
// ErrShortWrite means that a write accepted fewer bytes than requested
// but failed to return an explicit error.
-var ErrShortWrite os.Error = &Error{"short write"}
+var ErrShortWrite error = &Error{"short write"}
// ErrShortBuffer means that a read required a longer buffer than was provided.
-var ErrShortBuffer os.Error = &Error{"short buffer"}
+var ErrShortBuffer error = &Error{"short buffer"}
+
+// EOF is the error returned by Read when no more input is available.
+// Functions should return EOF only to signal a graceful end of input.
+// If the EOF occurs unexpectedly in a structured data stream,
+// the appropriate error is either ErrUnexpectedEOF or some other error
+// giving more detail.
+var EOF error = &Error{"EOF"}
-// ErrUnexpectedEOF means that os.EOF was encountered in the
+// ErrUnexpectedEOF means that EOF was encountered in the
// middle of reading a fixed-size block or data structure.
-var ErrUnexpectedEOF os.Error = &Error{"unexpected EOF"}
+var ErrUnexpectedEOF error = &Error{"unexpected EOF"}
// Reader is the interface that wraps the basic Read method.
//
// or return the error (and n == 0) from a subsequent call.
// An instance of this general case is that a Reader returning
// a non-zero number of bytes at the end of the input stream may
-// return either err == os.EOF or err == nil. The next Read should
-// return 0, os.EOF regardless.
+// return either err == EOF or err == nil. The next Read should
+// return 0, EOF regardless.
//
// Callers should always process the n > 0 bytes returned before
// considering the error err. Doing so correctly handles I/O errors
// that happen after reading some bytes and also both of the
// allowed EOF behaviors.
type Reader interface {
- Read(p []byte) (n int, err os.Error)
+ Read(p []byte) (n int, err error)
}
// Writer is the interface that wraps the basic Write method.
// and any error encountered that caused the write to stop early.
// Write must return a non-nil error if it returns n < len(p).
type Writer interface {
- Write(p []byte) (n int, err os.Error)
+ Write(p []byte) (n int, err error)
}
// Closer is the interface that wraps the basic Close method.
type Closer interface {
- Close() os.Error
+ Close() error
}
// Seeker is the interface that wraps the basic Seek method.
// relative to the end. Seek returns the new offset and an Error, if
// any.
type Seeker interface {
- Seek(offset int64, whence int) (ret int64, err os.Error)
+ Seek(offset int64, whence int) (ret int64, err error)
}
// ReadWriter is the interface that groups the basic Read and Write methods.
// ReaderFrom is the interface that wraps the ReadFrom method.
type ReaderFrom interface {
- ReadFrom(r Reader) (n int64, err os.Error)
+ ReadFrom(r Reader) (n int64, err error)
}
// WriterTo is the interface that wraps the WriteTo method.
type WriterTo interface {
- WriteTo(w Writer) (n int64, err os.Error)
+ WriteTo(w Writer) (n int64, err error)
}
// ReaderAt is the interface that wraps the basic ReadAt method.
// In this respect ReadAt is different from Read.
//
// If the n = len(p) bytes returned by ReadAt are at the end of the
-// input source, ReadAt may return either err == os.EOF or err == nil.
+// input source, ReadAt may return either err == EOF or err == nil.
//
// If ReadAt is reading from an input source with a seek offset,
// ReadAt should not affect nor be affected by the underlying
// seek offset.
type ReaderAt interface {
- ReadAt(p []byte, off int64) (n int, err os.Error)
+ ReadAt(p []byte, off int64) (n int, err error)
}
// WriterAt is the interface that wraps the basic WriteAt method.
// and any error encountered that caused the write to stop early.
// WriteAt must return a non-nil error if it returns n < len(p).
type WriterAt interface {
- WriteAt(p []byte, off int64) (n int, err os.Error)
+ WriteAt(p []byte, off int64) (n int, err error)
}
// ByteReader is the interface that wraps the ReadByte method.
// ReadByte reads and returns the next byte from the input.
// If no byte is available, err will be set.
type ByteReader interface {
- ReadByte() (c byte, err os.Error)
+ ReadByte() (c byte, err error)
}
// ByteScanner is the interface that adds the UnreadByte method to the
// call to ReadByte.
type ByteScanner interface {
ByteReader
- UnreadByte() os.Error
+ UnreadByte() error
}
// RuneReader is the interface that wraps the ReadRune method.
// and returns the rune and its size in bytes. If no character is
// available, err will be set.
type RuneReader interface {
- ReadRune() (r rune, size int, err os.Error)
+ ReadRune() (r rune, size int, err error)
}
// RuneScanner is the interface that adds the UnreadRune method to the
// call to ReadRune.
type RuneScanner interface {
RuneReader
- UnreadRune() os.Error
+ UnreadRune() error
}
// stringWriter is the interface that wraps the WriteString method.
type stringWriter interface {
- WriteString(s string) (n int, err os.Error)
+ WriteString(s string) (n int, err error)
}
// WriteString writes the contents of the string s to w, which accepts an array of bytes.
-func WriteString(w Writer, s string) (n int, err os.Error) {
+func WriteString(w Writer, s string) (n int, err error) {
if sw, ok := w.(stringWriter); ok {
return sw.WriteString(s)
}
// ReadAtLeast reads from r into buf until it has read at least min bytes.
// It returns the number of bytes copied and an error if fewer bytes were read.
-// The error is os.EOF only if no bytes were read.
+// The error is EOF only if no bytes were read.
// If an EOF happens after reading fewer than min bytes,
// ReadAtLeast returns ErrUnexpectedEOF.
// If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer.
-func ReadAtLeast(r Reader, buf []byte, min int) (n int, err os.Error) {
+func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error) {
if len(buf) < min {
return 0, ErrShortBuffer
}
nn, err = r.Read(buf[n:])
n += nn
}
- if err == os.EOF {
+ if err == EOF {
if n >= min {
err = nil
} else if n > 0 {
// ReadFull reads exactly len(buf) bytes from r into buf.
// It returns the number of bytes copied and an error if fewer bytes were read.
-// The error is os.EOF only if no bytes were read.
+// The error is EOF only if no bytes were read.
// If an EOF happens after reading some but not all the bytes,
// ReadFull returns ErrUnexpectedEOF.
-func ReadFull(r Reader, buf []byte) (n int, err os.Error) {
+func ReadFull(r Reader, buf []byte) (n int, err error) {
return ReadAtLeast(r, buf, len(buf))
}
// It returns the number of bytes copied and the earliest
// error encountered while copying. Because Read can
// return the full amount requested as well as an error
-// (including os.EOF), so can CopyN.
+// (including EOF), so can CopyN.
//
// If dst implements the ReaderFrom interface,
// the copy is implemented by calling dst.ReadFrom(src).
-func CopyN(dst Writer, src Reader, n int64) (written int64, err os.Error) {
+func CopyN(dst Writer, src Reader, n int64) (written int64, err error) {
// If the writer has a ReadFrom method, use it to do the copy.
// Avoids a buffer allocation and a copy.
if rt, ok := dst.(ReaderFrom); ok {
written, err = rt.ReadFrom(LimitReader(src, n))
if written < n && err == nil {
// rt stopped early; must have been EOF.
- err = os.EOF
+ err = EOF
}
return
}
// on src or an error occurs. It returns the number of bytes
// copied and the first error encountered while copying, if any.
//
-// A successful Copy returns err == nil, not err == os.EOF.
+// A successful Copy returns err == nil, not err == EOF.
// Because Copy is defined to read from src until EOF, it does
// not treat an EOF from Read as an error to be reported.
//
// the copy is implemented by calling dst.ReadFrom(src).
// Otherwise, if src implements the WriterTo interface,
// the copy is implemented by calling src.WriteTo(dst).
-func Copy(dst Writer, src Reader) (written int64, err os.Error) {
+func Copy(dst Writer, src Reader) (written int64, err error) {
// If the writer has a ReadFrom method, use it to do the copy.
// Avoids an allocation and a copy.
if rt, ok := dst.(ReaderFrom); ok {
break
}
}
- if er == os.EOF {
+ if er == EOF {
break
}
if er != nil {
}
// LimitReader returns a Reader that reads from r
-// but stops with os.EOF after n bytes.
+// but stops with EOF after n bytes.
// The underlying implementation is a *LimitedReader.
func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }
N int64 // max bytes remaining
}
-func (l *LimitedReader) Read(p []byte) (n int, err os.Error) {
+func (l *LimitedReader) Read(p []byte) (n int, err error) {
if l.N <= 0 {
- return 0, os.EOF
+ return 0, EOF
}
if int64(len(p)) > l.N {
p = p[0:l.N]
}
// NewSectionReader returns a SectionReader that reads from r
-// starting at offset off and stops with os.EOF after n bytes.
+// starting at offset off and stops with EOF after n bytes.
func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader {
return &SectionReader{r, off, off, off + n}
}
limit int64
}
-func (s *SectionReader) Read(p []byte) (n int, err os.Error) {
+func (s *SectionReader) Read(p []byte) (n int, err error) {
if s.off >= s.limit {
- return 0, os.EOF
+ return 0, EOF
}
if max := s.limit - s.off; int64(len(p)) > max {
p = p[0:max]
return
}
-func (s *SectionReader) Seek(offset int64, whence int) (ret int64, err os.Error) {
+var errWhence = &Error{"Seek: invalid whence"}
+var errOffset = &Error{"Seek: invalid offset"}
+
+func (s *SectionReader) Seek(offset int64, whence int) (ret int64, err error) {
switch whence {
default:
- return 0, os.EINVAL
+ return 0, errWhence
case 0:
offset += s.base
case 1:
offset += s.limit
}
if offset < s.base || offset > s.limit {
- return 0, os.EINVAL
+ return 0, errOffset
}
s.off = offset
return offset - s.base, nil
}
-func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err os.Error) {
+func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error) {
if off < 0 || off >= s.limit-s.base {
- return 0, os.EOF
+ return 0, EOF
}
off += s.base
if max := s.limit - off; int64(len(p)) > max {
w Writer
}
-func (t *teeReader) Read(p []byte) (n int, err os.Error) {
+func (t *teeReader) Read(p []byte) (n int, err error) {
n, err = t.r.Read(p)
if n > 0 {
if n, err := t.w.Write(p[:n]); err != nil {
import (
"bytes"
. "io"
- "os"
"strings"
"testing"
)
w Writer
}
-func (w *noReadFrom) Write(p []byte) (n int, err os.Error) {
+func (w *noReadFrom) Write(p []byte) (n int, err error) {
return w.w.Write(p)
}
}
n, err = CopyN(&noReadFrom{b}, strings.NewReader("foo"), 4)
- if n != 3 || err != os.EOF {
+ if n != 3 || err != EOF {
t.Errorf("CopyN(noReadFrom, foo, 4) = %d, %v; want 3, EOF", n, err)
}
}
n, err = CopyN(b, strings.NewReader("foo"), 4) // b has read from
- if n != 3 || err != os.EOF {
+ if n != 3 || err != EOF {
t.Errorf("CopyN(bytes.Buffer, foo, 4) = %d, %v; want 3, EOF", n, err)
}
}
testReadAtLeast(t, &rb)
}
-// A version of bytes.Buffer that returns n > 0, os.EOF on Read
+// A version of bytes.Buffer that returns n > 0, EOF on Read
// when the input is exhausted.
type dataAndEOFBuffer struct {
bytes.Buffer
}
-func (r *dataAndEOFBuffer) Read(p []byte) (n int, err os.Error) {
+func (r *dataAndEOFBuffer) Read(p []byte) (n int, err error) {
n, err = r.Buffer.Read(p)
if n > 0 && r.Buffer.Len() == 0 && err == nil {
- err = os.EOF
+ err = EOF
}
return
}
t.Errorf("expected to have read 2 bytes, got %v", n)
}
n, err = ReadAtLeast(rb, buf, 2)
- if err != os.EOF {
+ if err != EOF {
t.Errorf("expected EOF, got %v", err)
}
if n != 0 {
if !bytes.Equal(wb.Bytes(), src) {
t.Errorf("bytes written = %q want %q", wb.Bytes(), src)
}
- if n, err := r.Read(dst); n != 0 || err != os.EOF {
+ if n, err := r.Read(dst); n != 0 || err != EOF {
t.Errorf("r.Read at EOF = %d, %v want 0, EOF", n, err)
}
rb = bytes.NewBuffer(src)
pr, pw := Pipe()
pr.Close()
r = TeeReader(rb, pw)
- if n, err := ReadFull(r, dst); n != 0 || err != os.EPIPE {
+ if n, err := ReadFull(r, dst); n != 0 || err != ErrClosedPipe {
t.Errorf("closed tee: ReadFull(r, dst) = %d, %v; want 0, EPIPE", n, err)
}
}
package io
-import (
- "os"
- "sync"
-)
+import "sync"
+
+// ErrClosedPipe is the error used for read or write operations on a closed pipe.
+var ErrClosedPipe = &Error{"io: read/write on closed pipe"}
type pipeResult struct {
n int
- err os.Error
+ err error
}
// A pipe is the shared pipe structure underlying PipeReader and PipeWriter.
data []byte // data remaining in pending write
rwait sync.Cond // waiting reader
wwait sync.Cond // waiting writer
- rerr os.Error // if reader closed, error to give writes
- werr os.Error // if writer closed, error to give reads
+ rerr error // if reader closed, error to give writes
+ werr error // if writer closed, error to give reads
}
-func (p *pipe) read(b []byte) (n int, err os.Error) {
+func (p *pipe) read(b []byte) (n int, err error) {
// One reader at a time.
p.rl.Lock()
defer p.rl.Unlock()
defer p.l.Unlock()
for {
if p.rerr != nil {
- return 0, os.EINVAL
+ return 0, ErrClosedPipe
}
if p.data != nil {
break
var zero [0]byte
-func (p *pipe) write(b []byte) (n int, err os.Error) {
+func (p *pipe) write(b []byte) (n int, err error) {
// pipe uses nil to mean not available
if b == nil {
b = zero[:]
break
}
if p.werr != nil {
- err = os.EINVAL
+ err = ErrClosedPipe
}
p.wwait.Wait()
}
return
}
-func (p *pipe) rclose(err os.Error) {
+func (p *pipe) rclose(err error) {
if err == nil {
- err = os.EPIPE
+ err = ErrClosedPipe
}
p.l.Lock()
defer p.l.Unlock()
p.wwait.Signal()
}
-func (p *pipe) wclose(err os.Error) {
+func (p *pipe) wclose(err error) {
if err == nil {
- err = os.EOF
+ err = EOF
}
p.l.Lock()
defer p.l.Unlock()
// it reads data from the pipe, blocking until a writer
// arrives or the write end is closed.
// If the write end is closed with an error, that error is
-// returned as err; otherwise err is os.EOF.
-func (r *PipeReader) Read(data []byte) (n int, err os.Error) {
+// returned as err; otherwise err is EOF.
+func (r *PipeReader) Read(data []byte) (n int, err error) {
return r.p.read(data)
}
// Close closes the reader; subsequent writes to the
-// write half of the pipe will return the error os.EPIPE.
-func (r *PipeReader) Close() os.Error {
+// write half of the pipe will return the error ErrClosedPipe.
+func (r *PipeReader) Close() error {
return r.CloseWithError(nil)
}
// CloseWithError closes the reader; subsequent writes
// to the write half of the pipe will return the error err.
-func (r *PipeReader) CloseWithError(err os.Error) os.Error {
+func (r *PipeReader) CloseWithError(err error) error {
r.p.rclose(err)
return nil
}
// it writes data to the pipe, blocking until readers
// have consumed all the data or the read end is closed.
// If the read end is closed with an error, that err is
-// returned as err; otherwise err is os.EPIPE.
-func (w *PipeWriter) Write(data []byte) (n int, err os.Error) {
+// returned as err; otherwise err is ErrClosedPipe.
+func (w *PipeWriter) Write(data []byte) (n int, err error) {
return w.p.write(data)
}
// Close closes the writer; subsequent reads from the
-// read half of the pipe will return no bytes and os.EOF.
-func (w *PipeWriter) Close() os.Error {
+// read half of the pipe will return no bytes and EOF.
+func (w *PipeWriter) Close() error {
return w.CloseWithError(nil)
}
// CloseWithError closes the writer; subsequent reads from the
// read half of the pipe will return no bytes and the error err.
-func (w *PipeWriter) CloseWithError(err os.Error) os.Error {
+func (w *PipeWriter) CloseWithError(err error) error {
w.p.wclose(err)
return nil
}