...

Package io

import "io"
概览
索引
子目录

概览 ▾

io 包为I/O原语提供了基础的接口. 它主要包装了这些原语的已有实现,如 os 包中的那些,抽象成函数性的共享公共接口, 加上一些其它相关的原语。

由于这些接口和原语以不同的实现包装了低级操作,因此除非另行通知, 否则客户不应假定它们对于并行执行是安全的。

索引 ▾

变量
func Copy(dst Writer, src Reader) (written int64, err error)
func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error)
func CopyN(dst Writer, src Reader, n int64) (written int64, err error)
func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)
func ReadFull(r Reader, buf []byte) (n int, err error)
func WriteString(w Writer, s string) (n int, err error)
type ByteReader
type ByteScanner
type ByteWriter
type Closer
type LimitedReader
    func (l *LimitedReader) Read(p []byte) (n int, err error)
type PipeReader
    func Pipe() (*PipeReader, *PipeWriter)
    func (r *PipeReader) Close() error
    func (r *PipeReader) CloseWithError(err error) error
    func (r *PipeReader) Read(data []byte) (n int, err error)
type PipeWriter
    func (w *PipeWriter) Close() error
    func (w *PipeWriter) CloseWithError(err error) error
    func (w *PipeWriter) Write(data []byte) (n int, err error)
type ReadCloser
type ReadSeeker
type ReadWriteCloser
type ReadWriteSeeker
type ReadWriter
type Reader
    func LimitReader(r Reader, n int64) Reader
    func MultiReader(readers ...Reader) Reader
    func TeeReader(r Reader, w Writer) Reader
type ReaderAt
type ReaderFrom
type RuneReader
type RuneScanner
type SectionReader
    func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader
    func (s *SectionReader) Read(p []byte) (n int, err error)
    func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error)
    func (s *SectionReader) Seek(offset int64, whence int) (int64, error)
    func (s *SectionReader) Size() int64
type Seeker
type WriteCloser
type WriteSeeker
type Writer
    func MultiWriter(writers ...Writer) Writer
type WriterAt
type WriterTo

包文件

io.go multi.go pipe.go

变量

var EOF = errors.New("EOF")

EOF 是 Read 在没有更多输入可用时返回的错误。 函数应当只为标志出优雅的输入结束而返回 EOF。若 EOF 在结构化数据流中出现意外, 适当的错误不是 ErrUnexpectedEOF 就是一些其它能给出更多详情的错误。

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

ErrClosedPipe 错误用于在已关闭的管道上进行读取或写入操作。

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

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

var ErrShortBuffer = errors.New("short buffer")

ErrShortBuffer 意为所需读取的缓存比提供的长。

var ErrShortWrite = errors.New("short write")

ErrShortWrite 意为接受写入的字节比请求的少,但失败将返回一个明确的错误。

var ErrUnexpectedEOF = errors.New("unexpected EOF")

ErrUnexpectedEOF 意为在读取固定大小的块或数据结构过程中遇到EOF。

func Copy

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

Copy 将 src 复制到 dst,直到在 src 上到达 EOF 或发生错误。 它返回复制的字节数,如果有的话,还会返回在复制时遇到的第一个错误。

成功的 Copy 返回 err == nil,而非 err == EOF。由于 Copy 被定义为从 src 读取直到 EOF 为止,因此它不会将来自 Read 的 EOF 当做错误来报告。

若 src 实现了 WriterTo 接口,其复制操作可通过调用 src.WriteTo(dst) 实现。 否则,若 dst 实现了 ReaderFrom 接口,其复制操作可通过调用 dst.ReadFrom(src) 实现。

func CopyBuffer

func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error)

CopyBuffer is identical to Copy except that it stages through the provided buffer (if one is required) rather than allocating a temporary one. If buf is nil, one is allocated; otherwise if it has zero length, CopyBuffer panics.

func CopyN

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

CopyN 将 n 个字节从 src 复制到 dst。 它返回复制的字节数以及在复制时遇到的最早的错误。由于 Read 可以返回要求的全部数量及一个错误(包括 EOF),因此 CopyN 也能。

若 dst 实现了 ReaderFrom 接口,复制操作也就会使用它来实现。

func ReadAtLeast

func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)

ReadAtLeast 将 r 读取到 buf 中,直到读了最少 min 个字节为止。 它返回复制的字节数,如果读取的字节较少,还会返回一个错误。若没有读取字节, 错误就只是 EOF。如果一个 EOF 发生在读取了少于 min 个字节之后,ReadAtLeast 就会返回 ErrUnexpectedEOF。若 min 大于 buf 的长度,ReadAtLeast 就会返回 ErrShortBuffer。 对于返回值,当且仅当 err == nil 时,才有 n >= min。

func ReadFull

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

ReadFull 精确地从 r 中将 len(buf) 个字节读取到 buf 中。 它返回复制的字节数,如果读取的字节较少,还会返回一个错误。若没有读取字节, 错误就只是 EOF。如果一个 EOF 发生在读取了一些但不是所有的字节后,ReadFull 就会返回 ErrUnexpectedEOF。 对于返回值,当且仅当 err == nil 时,才有 n == len(buf)。

func WriteString

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

WriteString 将字符串 s 的内容写入 w 中,它接受一个字节数组。 若 w 已经实现了 WriteString 方法,就可以直接调用它。

type ByteReader

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

ByteReader 接口包装了 ReadByte 方法。

ReadByte 从输入中读取并返回下一个字节。若没有字节可用,就会置为 err。

type ByteScanner

type ByteScanner interface {
    ByteReader
    UnreadByte() error
}

ByteScanner 接口将 UnreadByte 方法添加到基本的 ReadByte 方法。

UnreadByte 使下一次调用 ReadByte 返回的字节与上一次调用 ReadByte 返回的相同。 调用 UnreadByte 两次而中间没有调用 ReadByte 的话就会返回错误。

type ByteWriter

type ByteWriter interface {
    WriteByte(c byte) error
}

ByteWriter 接口包装了 WriteByte 方法。

type Closer

type Closer interface {
    Close() error
}

Closer 接口包装了基本的 Close 方法。

Close 的行为在第一次调用后没有定义。具体实现可能有自己的行为描述。

type LimitedReader

type LimitedReader struct {
    R Reader // underlying reader   // 基本读取器
    N int64  // max bytes remaining // 最大剩余字节
}

LimitedReader 从 R 读取但将返回的数据量限制为 N 字节。每调用一次 Read 都将更新 N 来反射新的剩余数量。

func (*LimitedReader) Read

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

type PipeReader

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

PipeReader 是管道的读取端。

func Pipe

func Pipe() (*PipeReader, *PipeWriter)

Pipe 创建同步的内存管道。 它可用于将代码预期的 io.Reader 连接到代码预期的 io.Writer。 一端的读取匹配另一端的写入,直接在这两端之间复制数据;它没有内部缓存。 它对于并行调用 Read 和 Write 以及其它函数或 Close 来说都是安全的。 一旦等待的I/O结束,Close 就会完成。并行调用 Read 或并行调用 Write 也同样安全: 同种类的调用将按顺序进行控制。

func (*PipeReader) Close

func (r *PipeReader) Close() error

Close 关闭读取器;关闭后如果对管道的写入端进行写入操作,就会返回 ErrClosedPipe 错误。

func (*PipeReader) CloseWithError

func (r *PipeReader) CloseWithError(err error) error

CloseWithError 关闭读取器;关闭后如果对管道的写入端进行写入操作,就会返回 err 错误。

func (*PipeReader) Read

func (r *PipeReader) Read(data []byte) (n int, err error)

Read 实现了标准的 Read 接口: 它从管道中读取数据并阻塞,直到写入器开始写入或写入端被关闭。 若写入端带错误关闭,该错误将作为 err 返回;否则 err 为 EOF。

type PipeWriter

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

PipeReader 是管道的写入端。

func (*PipeWriter) Close

func (w *PipeWriter) Close() error

Close 关闭写入器;关闭后如果对管道的读取端进行读取操作,就会返回 EOF 而不返回字节。

func (*PipeWriter) CloseWithError

func (w *PipeWriter) CloseWithError(err error) error

CloseWithError 关闭写入器;关闭后如果对管道的读取端进行读取操作,就会返回错误 err 而不返回任何字节。

CloseWithError 总是返回 nil。

func (*PipeWriter) Write

func (w *PipeWriter) Write(data []byte) (n int, err error)

Write 实现了标准的 Write 接口: 它将数据写入到管道中并阻塞,直到读取器读完所有的数据或读取端被关闭。 若读取端带错误关闭,该错误将作为 err 返回;否则 err 为 ErrClosedPipe。

type ReadCloser

type ReadCloser interface {
    Reader
    Closer
}

ReadCloser 接口组合了基本的 Read 和 Close 方法。

type ReadSeeker

type ReadSeeker interface {
    Reader
    Seeker
}

ReadSeeker 接口组合了基本的 Read 和 Seek 方法。

type ReadWriteCloser

type ReadWriteCloser interface {
    Reader
    Writer
    Closer
}

ReadWriteCloser 接口组合了基本的 Read、Write 和 Close 方法。

type ReadWriteSeeker

type ReadWriteSeeker interface {
    Reader
    Writer
    Seeker
}

ReadWriteSeeker 接口组合了基本的 Read、Write 和 Seek 方法。

type ReadWriter

type ReadWriter interface {
    Reader
    Writer
}

ReadWriter 接口组合了基本的 Read 和 Write 方法。

type Reader

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

Reader 接口包装了基本的 Read 方法。

Read 将 len(p) 个字节读取到 p 中。它返回读取的字节数 n(0 <= n <= len(p)) 以及任何遇到的错误。即使 Read 返回的 n < len(p),它也会在调用过程中使用 p 的全部作为暂存空间。若一些数据可用但不到 len(p) 个字节,Read 会照例返回可用的东西, 而不是等待更多。

当 Read 在成功读取 n > 0 个字节后遇到一个错误或 EOF 情况,它就会返回读取的字节数。 它会从相同的调用中返回(非nil的)错误或从随后的调用中返回错误(和 n == 0)。 这种一般情况的一个例子就是 Reader 在输入流结束时会返回一个非零的字节数, 可能的返回不是 err == EOF 就是 err == nil。无论如何,下一个 Read 都应当返回 0, EOF。

调用者应当总在考虑到错误 err 前处理 n > 0 的字节。这样做可以在读取一些字节, 以及允许的 EOF 行为后正确地处理I/O错误。

Read 的实现在 len(p) == 0 以外的情况下会阻止返回零字节的计数和 nil 错误, 调用者应将返回 0 和 nil 视作什么也没有发生;特别是它并不表示 EOF。

实现必须不保留 p。

func LimitReader

func LimitReader(r Reader, n int64) Reader

LimitReader 返回一个 Reader,它从 r 中读取 n 个字节后以 EOF 停止。 其基本实现为 *LimitedReader。

func MultiReader

func MultiReader(readers ...Reader) Reader

MultiReader 返回一个 Reader,它是输入 readers 提供的的逻辑拼接。 它们按顺序读取。一旦所有的输入返回 EOF,Read 就会返回 EOF。 若任何 readers 返回了非 nil 或非 EOF 错误,Read 就会返回该错误。

func TeeReader

func TeeReader(r Reader, w Writer) Reader

TeeReader 返回一个 Reader,它将从 r 中读到的东西写入 w 中。 所有经由它处理的从 r 的读取都匹配于对应的对 w 的写入。它没有内部缓存, 即写入必须在读取完成前完成。任何在写入时遇到的错误都将作为读取错误来报告。

type ReaderAt

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

ReaderAt 接口包装了基本的 ReadAt 方法。

ReadAt 从基本输入源的偏移量 off 处开始,将 len(p) 个字节读取到 p 中。 它返回读取的字节数 n(0 <= n <= len(p))以及任何遇到的错误。

当 ReadAt 返回的 n < len(p) 时,它就会返回一个非nil的错误来解释 为什么没有返回更多的字节。在这一点上,ReadAt 比 Read 更严格。

即使 ReadAt 返回的 n < len(p),它也会在调用过程中使用 p 的全部作为暂存空间。 若一些数据可用但不到 len(p) 字节,ReadAt 就会阻塞直到所有数据都可用或产生一个错误。 在这一点上 ReadAt 不同于 Read。

若 n = len(p) 个字节在输入源的的结尾处由 ReadAt 返回,ReadAt 不是返回 err == EOF 就是返回 err == nil。

若 ReadAt 按查找偏移量从输入源读取,ReadAt 应当既不影响基本查找偏移量也不被它所影响。

ReadAt 的客户端可对相同的输入源并行执行 ReadAt 调用。

实现必须不保留 p。

type ReaderFrom

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

ReaderFrom 接口包装了 ReadFrom 方法。

ReadFrom 从 r 中读取数据,直到 EOF 或发生错误。其返回值 n 为读取的字节数。 除 io.EOF 之外,在读取过程中遇到的任何错误也将被返回。

如果 ReaderFrom 可用,Copy 函数就会使用它。

type RuneReader

type RuneReader interface {
    ReadRune() (r rune, size int, err error)
}

RuneReader 接口包装了 ReadRune 方法。

ReadRune 读取单个用UTF-8编码的Unicode字符,并返回该符文及其字节大小。 若没有字符可用,就会置为 err。

type RuneScanner

type RuneScanner interface {
    RuneReader
    UnreadRune() error
}

RuneScanner 接口将 UnreadRune 方法添加到基本的 ReadRune 方法。

UnreadRune 使下一次调用 ReadRune 返回的符文与上一次调用 ReadRune 返回的相同。 调用 UnreadRune 两次而中间没有调用 ReadRune 的话就会返回错误。

type SectionReader

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

SectionReader 在基本 ReaderAt 的片段上实现了Read、Seek和ReadAt。

func NewSectionReader

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

NewSectionReader 返回一个 SectionReader,它从 r 中的偏移量 off 处读取 n 个字节后以 EOF 停止。

func (*SectionReader) Read

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

func (*SectionReader) ReadAt

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

func (*SectionReader) Seek

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

func (*SectionReader) Size

func (s *SectionReader) Size() int64

Size 返回片段的字节数。

type Seeker

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

Seeker 接口包装了基本的 Seek 方法。

Seek 将 offset 置为下一个 Read 或 Write 的偏移量 ,它的解释取决于 whence: 0 表示相对于文件的起始处,1 表示相对于当前的偏移,而 2 表示相对于其结尾处。 Seek 返回新的偏移量和一个错误,如果有的话。

对负数偏移量进行 Seek 会产生错误。对任何正数偏移量进行 Seek 是合法的,但对底层类型的后续 I/O 操作行为则取决于具体实现。

type WriteCloser

type WriteCloser interface {
    Writer
    Closer
}

WriteCloser 接口组合了基本的 Write 和 Close 方法。

type WriteSeeker

type WriteSeeker interface {
    Writer
    Seeker
}

WriteSeeker 接口组合了基本的 Write 和 Seek 方法。

type Writer

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

Writer 接口包装了基本的 Write 方法。

Write 将 len(p) 个字节从 p 中写入到基本数据流中。它返回从 p 中被写入的字节数 n(0 <= n <= len(p))以及任何遇到的引起写入提前停止的错误。若 Write 返回的 n < len(p),它就必须返回一个非nil的错误。Write 不能修改此切片的数据,即便它是临时的。

实现必须不保留 p。

func MultiWriter

func MultiWriter(writers ...Writer) Writer

MultiWriter 创建一个 Writer,它将其写入复制到所有提供的 writers 中,类似于Unix的tee(1)命令。

type WriterAt

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

WriterAt 接口包装了基本的 WriteAt 方法。

WriteAt 从 p 中将 len(p) 个字节写入到偏移量 off 处的基本数据流中。它返回从 p 中被写入的字节数 n(0 <= n <= len(p))以及任何遇到的引起写入提前停止的错误。 若 WriteAt 返回的 n < len(p),它就必须返回一个非nil的错误。

若 WriteAt 按查找偏移量写入到目标中,WriteAt 应当既不影响基本查找偏移量也不被它所影响。

若区域没有重叠,WriteAt 的客户端可对相同的目标并行执行 WriteAt 调用。

实现必须不保留 p。

type WriterTo

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

WriterTo 接口包装了 WriteTo 方法。

WriteTo 将数据写入 w 中,直到没有数据可读或发生错误。其返回值 n 为写入的字节数。 在写入过程中遇到的任何错误也将被返回。

如果 WriterTo 可用,Copy 函数就会使用它。

子目录

名称      摘要
..
ioutil      ioutil 实现了一些I/O的工具函数。