io

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 5, 2026 License: BSD-3-Clause Imports: 4 Imported by: 0

Documentation

Overview

Package io provides basic interfaces to I/O primitives. Its primary job is to wrap existing implementations of such primitives, such as those in package os, into shared public interfaces that abstract the functionality, plus some other related primitives.

Because these interfaces and primitives wrap lower-level operations with various implementations, unless otherwise informed clients should not assume they are safe for parallel execution.

Based on the io package, with fewer features.

Index

Constants

View Source 
const (
	SeekStart   = 0 // seek relative to the origin of the file
	SeekCurrent = 1 // seek relative to the current offset
	SeekEnd     = 2 // seek relative to the end
)

Seek whence values.

Variables

View Source 
var EOF = errors.New("EOF")

EOF is the error returned by Read when no more input is available. (Read must return EOF itself, not an error wrapping EOF, because callers will test for EOF using ==.) 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.

View Source 
var ErrClosedPipe = errors.New("io: read/write on closed pipe")

ErrClosedPipe is the error used for read or write operations on a closed pipe.

View Source 
var ErrInvalidWrite = errors.New("io: Write returned impossible count")

ErrInvalidWrite means that a write returned an impossible count.

View Source 
var ErrNegativeRead = errors.New("io: Read returned negative count")

ErrNegativeRead means that a read returned a negative count.

View Source 
var ErrNoProgress = errors.New("io: multiple Read calls return no data or error")

ErrNoProgress is returned by some clients of a Reader when many calls to Read have failed to return any data or error, usually the sign of a broken Reader implementation.

View Source 
var ErrOffset = errors.New("io: invalid offset")

ErrOffset is returned by seek functions when the offset argument is invalid.

View Source 
var ErrShortBuffer = errors.New("io: short buffer")

ErrShortBuffer means that a read required a longer buffer than was provided.

View Source 
var ErrShortWrite = errors.New("io: short write")

ErrShortWrite means that a write accepted fewer bytes than requested but failed to return an explicit error.

View Source 
var ErrUnexpectedEOF = errors.New("io: unexpected EOF")

ErrUnexpectedEOF means that EOF was encountered in the middle of reading a fixed-size block or data structure.

View Source 
var ErrUnread = errors.New("io: cannot unread previous read operation")

ErrUnread is returned by unread operations when they can't perform for some reason.

View Source 
var ErrWhence = errors.New("io: invalid whence")

ErrWhence is returned by seek functions when the whence argument is invalid.

Functions

func Copy 

func Copy(dst Writer, src Reader) (int64, error)

Copy copies from src to dst until either EOF is reached 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 == 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.

Copy allocates a buffer on the stack to hold data during the copy.

func CopyN 

func CopyN(dst Writer, src Reader, n int64) (int64, error)

CopyN copies n bytes (or until an error) from src to dst. It returns the number of bytes copied and the earliest error encountered while copying. On return, written == n if and only if err == nil.

Allocates a buffer on the stack to hold data during the copy.

func ReadAll 

func ReadAll(a mem.Allocator, r Reader) ([]byte, error)

ReadAll reads from r until an error or EOF and returns the data it read. A successful call returns err == nil, not err == EOF. Because ReadAll is defined to read from src until EOF, it does not treat an EOF from Read as an error to be reported.

If the allocator is nil, uses the system allocator. The returned slice is allocated; the caller owns it.

func ReadFull 

func ReadFull(r Reader, buf []byte) (int, error)

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 EOF only if no bytes were read. If an EOF happens after reading some but not all the bytes, ReadFull returns ErrUnexpectedEOF. On return, n == len(buf) if and only if err == nil. If r returns an error having read at least len(buf) bytes, the error is dropped.

func WriteString 

func WriteString(w Writer, s string) (int, error)

WriteString writes the contents of the string s to w, which accepts a slice of bytes. [Writer.Write] is called exactly once.

Types

type ByteReader 

type ByteReader interface {
	ReadByte() (byte, error)
}

ByteReader is the interface that wraps the ReadByte method.

ReadByte reads and returns the next byte from the input or any error encountered. If ReadByte returns an error, no input byte was consumed, and the returned byte value is undefined.

ReadByte provides an efficient interface for byte-at-time processing. A Reader that does not implement ByteReader can be wrapped using bufio.NewReader to add this method.

type ByteScanner 

type ByteScanner interface {
	ReadByte() (byte, error)
	UnreadByte() error
}

ByteScanner is the interface that adds the UnreadByte method to the basic ReadByte method.

UnreadByte causes the next call to ReadByte to return the last byte read. If the last operation was not a successful call to ReadByte, UnreadByte may return an error, unread the last byte read (or the byte prior to the last-unread byte), or (in implementations that support the Seeker interface) seek to one byte before the current offset.

type ByteWriter 

type ByteWriter interface {
	WriteByte(c byte) error
}

ByteWriter is the interface that wraps the WriteByte method.

type Closer 

type Closer interface {
	Close() error
}

Closer is the interface that wraps the basic Close method.

The behavior of Close after the first call is undefined. Specific implementations may document their own behavior.

type DiscardWriter 

type DiscardWriter struct{}

A DiscardWriter provides Write methods that succeed without doing anything.

func (*DiscardWriter) Write 

func (*DiscardWriter) Write(p []byte) (int, error)

func (*DiscardWriter) WriteString 

func (*DiscardWriter) WriteString(s string) (int, error)

type LimitedReader 

type LimitedReader struct {
	R Reader // underlying reader
	N int64  // max bytes remaining
}

A LimitedReader reads from R but limits the amount of data returned to just N bytes. Each call to Read updates N to reflect the new amount remaining. Read returns EOF when N <= 0 or when the underlying R returns EOF.

func LimitReader 

func LimitReader(r Reader, n int64) LimitedReader

LimitReader returns a LimitedReader that reads from r but stops with EOF after n bytes.

func (*LimitedReader) Read 

func (l *LimitedReader) Read(p []byte) (int, error)

type MultiReader 

type MultiReader struct {
	// contains filtered or unexported fields
}

func NewMultiReader 

func NewMultiReader(readers ...Reader) MultiReader

NewMultiReader returns a Reader that's the logical concatenation of the provided input readers. They're read sequentially. Once all inputs have returned EOF, Read will return EOF. If any of the readers return a non-nil, non-EOF error, Read will return that error.

func (*MultiReader) Read 

func (mr *MultiReader) Read(p []byte) (int, error)

func (*MultiReader) WriteTo 

func (mr *MultiReader) WriteTo(w Writer) (int64, error)

type MultiWriter 

type MultiWriter struct {
	// contains filtered or unexported fields
}

func NewMultiWriter 

func NewMultiWriter(writers ...Writer) MultiWriter

NewMultiWriter creates a writer that duplicates its writes to all the provided writers, similar to the Unix tee(1) command.

Each write is written to each listed writer, one at a time. If a listed writer returns an error, that overall write operation stops and returns the error; it does not continue down the list.

func (*MultiWriter) Write 

func (t *MultiWriter) Write(p []byte) (int, error)

func (*MultiWriter) WriteString 

func (t *MultiWriter) WriteString(s string) (int, error)

type NopCloser 

type NopCloser struct {
	// contains filtered or unexported fields
}

A NopCloser is a ReadCloser with a no-op Close method wrapping the provided Reader r.

func NewNopCloser 

func NewNopCloser(r Reader) NopCloser

NewNopCloser returns a NopCloser wrapping r.

func (*NopCloser) Close 

func (*NopCloser) Close() error

func (*NopCloser) Read 

func (n *NopCloser) Read(p []byte) (int, error)

type ReadCloser 

type ReadCloser interface {
	Read(p []byte) (n int, err error)
	Close() error
}

ReadCloser is the interface that groups the basic Read and Close methods.

type ReadSeekCloser 

type ReadSeekCloser interface {
	Read(p []byte) (n int, err error)
	Seek(offset int64, whence int) (int64, error)
	Close() error
}

ReadSeekCloser is the interface that groups the basic Read, Seek and Close methods.

type ReadSeeker 

type ReadSeeker interface {
	Read(p []byte) (n int, err error)
	Seek(offset int64, whence int) (int64, error)
}

ReadSeeker is the interface that groups the basic Read and Seek methods.

type ReadWriteCloser 

type ReadWriteCloser interface {
	Read(p []byte) (n int, err error)
	Write(p []byte) (n int, err error)
	Close() error
}

ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.

type ReadWriteSeeker 

type ReadWriteSeeker interface {
	Read(p []byte) (n int, err error)
	Write(p []byte) (n int, err error)
	Seek(offset int64, whence int) (int64, error)
}

ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.

type ReadWriter 

type ReadWriter interface {
	Read(p []byte) (n int, err error)
	Write(p []byte) (n int, err error)
}

ReadWriter is the interface that groups the basic Read and Write methods.

type Reader 

type Reader interface {
	Read(p []byte) (n int, err error)
}

Reader is the interface that wraps the basic Read method.

Read reads up to len(p) bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered. Even if Read returns n < len(p), it may use all of p as scratch space during the call. If some data is available but not len(p) bytes, Read conventionally returns what is available instead of waiting for more.

When Read encounters an error or end-of-file condition after successfully reading n > 0 bytes, it returns the number of bytes read. It may return the (non-nil) error from the same call 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 == EOF or err == nil. The next Read should return 0, EOF.

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.

If len(p) == 0, Read should always return n == 0. It may return a non-nil error if some error condition is known, such as EOF.

Implementations of Read are discouraged from returning a zero byte count with a nil error, except when len(p) == 0. Callers should treat a return of 0 and nil as indicating that nothing happened; in particular it does not indicate EOF.

Implementations must not retain p.

type ReaderAt 

type ReaderAt interface {
	ReadAt(p []byte, off int64) (n int, err error)
}

ReaderAt is the interface that wraps the basic ReadAt method.

ReadAt reads len(p) bytes into p starting at offset off in the underlying input source. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered.

When ReadAt returns n < len(p), it returns a non-nil error explaining why more bytes were not returned. In this respect, ReadAt is stricter than Read.

Even if ReadAt returns n < len(p), it may use all of p as scratch space during the call. If some data is available but not len(p) bytes, ReadAt blocks until either all the data is available or an error occurs. 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 == 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.

Clients of ReadAt can execute parallel ReadAt calls on the same input source.

Implementations must not retain p.

type ReaderAtOffset 

type ReaderAtOffset struct {
	R   ReaderAt
	Off int64
	N   int64
}

ReaderAtOffset represents the underlying ReaderAt and offsets for a section.

type ReaderFrom 

type ReaderFrom interface {
	ReadFrom(r Reader) (n int64, err error)
}

ReaderFrom is the interface that wraps the ReadFrom method.

ReadFrom reads data from r until EOF or error. The return value n is the number of bytes read. Any error except EOF encountered during the read is also returned.

type RuneReader 

type RuneReader interface {
	ReadRune() RuneSizeResult
}

RuneReader is the interface that wraps the ReadRune method.

ReadRune reads a single encoded Unicode character and returns the rune and its size in bytes. If no character is available, err will be set.

type RuneScanner 

type RuneScanner interface {
	ReadRune() RuneSizeResult
	UnreadRune() error
}

RuneScanner is the interface that adds the UnreadRune method to the basic ReadRune method.

UnreadRune causes the next call to ReadRune to return the last rune read. If the last operation was not a successful call to ReadRune, UnreadRune may return an error, unread the last rune read (or the rune prior to the last-unread rune), or (in implementations that support the Seeker interface) seek to the start of the rune before the current offset.

type RuneSizeResult 

type RuneSizeResult struct {
	Rune rune
	Size int
	Err  error
}

RuneSizeResult is the result of a [RuneReader.ReadRune] operation: the rune read, its size in bytes, and any error encountered.

type SectionReader 

type SectionReader struct {
	// contains filtered or unexported fields
}

SectionReader implements Read, Seek, and ReadAt on a section of an underlying ReaderAt.

func NewSectionReader 

func NewSectionReader(r ReaderAt, off int64, n int64) SectionReader

NewSectionReader returns a SectionReader that reads from r starting at offset off and stops with EOF after n bytes.

func (*SectionReader) Outer 

func (s *SectionReader) Outer() ReaderAtOffset

Outer returns the underlying ReaderAt and offsets for the section.

The returned values are the same that were passed to NewSectionReader when the SectionReader was created.

func (*SectionReader) Read 

func (s *SectionReader) Read(p []byte) (int, error)

func (*SectionReader) ReadAt 

func (s *SectionReader) ReadAt(p []byte, off int64) (int, error)

func (*SectionReader) Seek 

func (s *SectionReader) Seek(offset int64, whence int) (int64, error)

func (*SectionReader) Size 

func (s *SectionReader) Size() int64

Size returns the size of the section in bytes.

type Seeker 

type Seeker interface {
	Seek(offset int64, whence int) (int64, error)
}

Seeker is the interface that wraps the basic Seek method.

Seek sets the offset for the next Read or Write to offset, interpreted according to whence: SeekStart means relative to the start of the file, SeekCurrent means relative to the current offset, and SeekEnd means relative to the end (for example, offset = -2 specifies the penultimate byte of the file). Seek returns the new offset relative to the start of the file or an error, if any.

Seeking to an offset before the start of the file is an error. Seeking to any positive offset may be allowed, but if the new offset exceeds the size of the underlying object the behavior of subsequent I/O operations is implementation-dependent.

type StringWriter 

type StringWriter interface {
	WriteString(s string) (n int, err error)
}

StringWriter is the interface that wraps the WriteString method.

type WriteCloser 

type WriteCloser interface {
	Write(p []byte) (n int, err error)
	Close() error
}

WriteCloser is the interface that groups the basic Write and Close methods.

type WriteSeeker 

type WriteSeeker interface {
	Write(p []byte) (n int, err error)
	Seek(offset int64, whence int) (int64, error)
}

WriteSeeker is the interface that groups the basic Write and Seek methods.

type Writer 

type Writer interface {
	Write(p []byte) (n int, err error)
}

Writer is the interface that wraps the basic Write method.

Write writes len(p) bytes from p to the underlying data stream. It returns the number of bytes written from p (0 <= n <= len(p)) and any error encountered that caused the write to stop early. Write must return a non-nil error if it returns n < len(p). Write must not modify the slice data, even temporarily.

Implementations must not retain p. 

var Discard Writer = &DiscardWriter{}

Discard is a Writer on which all Write calls succeed without doing anything.

type WriterAt 

type WriterAt interface {
	WriteAt(p []byte, off int64) (n int, err error)
}

WriterAt is the interface that wraps the basic WriteAt method.

WriteAt writes len(p) bytes from p to the underlying data stream at offset off. It returns the number of bytes written from p (0 <= n <= len(p)) and any error encountered that caused the write to stop early. WriteAt must return a non-nil error if it returns n < len(p).

If WriteAt is writing to a destination with a seek offset, WriteAt should not affect nor be affected by the underlying seek offset.

Clients of WriteAt can execute parallel WriteAt calls on the same destination if the ranges do not overlap.

Implementations must not retain p.

type WriterTo 

type WriterTo interface {
	WriteTo(w Writer) (n int64, err error)
}

WriterTo is the interface that wraps the WriteTo method.

WriteTo writes data to w until there's no more data to write or when an error occurs. The return value n is the number of bytes written. Any error encountered during the write is also returned.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.