在线文档教程

io

Package io

  • import "io"

  • 概况

  • 索引

  • 示例

  • 子目录

概况

Package 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

示例

Copy

包文件

io.go multi.go pipe.go

常量

Seek 值。

const ( SeekStart = 0 // 寻找相对于文件的起源 SeekCurrent = 1 // 寻找相对于当前的偏移量 SeekEnd = 2 // 寻求相对于目的 )

变量

当没有更多输入可用时,EOF 是由 Read 返回的错误。函数只能返回 EOF 来表示输入的正常结束。如果 EOF 在结构化数据流中意外发生,则适当的错误是 ErrUnexpectedEOF 或其他一些错误,以提供更多详细信息。

var EOF = errors.New("EOF")

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

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

ErrNoProgress 是由一些 io.Reader 的客户端在许多 Read 的调用未能返回任何数据或错误(通常是破坏的 io.Reader 实现的标志)失败时返回的。

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

ErrShortBuffer 意味着读取需要比提供的更长的缓冲区。

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

ErrShortWrite 意味着写入接受的字节数少于请求的数量,但未能返回明确的错误。

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

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

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

func Copy(显示源代码)

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

将副本从 src 复制到 dst ,直到在 src 上达到 EOF 或发生错误。它返回复制的字节数和复制时遇到的第一个错误(如果有的话)。

成功的复制返回err == nil,而不是err == EOF。由于 Copy 定义为从 src 读取直到 EOF,因此它不会将 Read 中的 EOF 视为要报告的错误。

如果 src 实现 WriterTo 接口,则通过调用 src.WriteTo(dst)来实现副本。否则,如果 dst 实现 ReaderFrom 接口,则通过调用 dst.ReadFrom(src)来实现副本。

示例

package main import ( "io" "log" "os" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") if _, err := io.Copy(os.Stdout, r err != nil { log.Fatal(err) } }

func CopyBuffer(显示源代码)

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

CopyBuffer 与 Copy 相同,只是它通过提供的缓冲区(如果需要的话)进行分级,而不是分配临时的缓冲区。如果 buf 为零,则分配一个;否则如果它的长度为零,CopyBuffer 会发生混乱。

示例

package main import ( "io" "log" "os" "strings" ) func main() { r1 := strings.NewReader("first reader\n") r2 := strings.NewReader("second reader\n") buf := make([]byte, 8) // 在这里使用buf ... if _, err := io.CopyBuffer(os.Stdout, r1, buf err != nil { log.Fatal(err) } // ...也在这里重复使用。 无需分配额外的缓冲区。 if _, err := io.CopyBuffer(os.Stdout, r2, buf err != nil { log.Fatal(err) } }

func CopyN(显示源代码)

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

CopyN 拷贝从 src 到 dst 的 n 个字节(或直出现一个错误)。它返回拷贝的字节数和复制时遇到的最早的错误。返回时,written == n 当且仅当 err == nil 。

如果 dst 实现 ReaderFrom 接口,则使用它实现副本。

示例

package main import ( "io" "log" "os" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read") if _, err := io.CopyN(os.Stdout, r, 5 err != nil { log.Fatal(err) } }

func ReadAtLeast(显示源代码)

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

ReadAtLeast 从 r 读入 buf,直到它读取至少最小字节。它返回复制的字节数,如果读取的字节更少,则返回错误。只有在没有字节被读取的情况下,错误才是 EOF 。如果在读取少于最小字节数后发生 EOF,则 ReadAtLeast 返回 ErrUnexpectedEOF 。如果 min 大于 buf 的长度,则 ReadAtLeast 返回 ErrShortBuffer。返回时,n> = min 当且仅当 err == nil 。

示例

package main import ( "fmt" "io" "log" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") buf := make([]byte, 33) if _, err := io.ReadAtLeast(r, buf, 4 err != nil { log.Fatal(err) } fmt.Printf("%s\n", buf) // 缓冲区小于最小读取大小。 shortBuf := make([]byte, 3) if _, err := io.ReadAtLeast(r, shortBuf, 4 err != nil { fmt.Println("error:", err) } // 最小读取大小比io.Reader流大 longBuf := make([]byte, 64) if _, err := io.ReadAtLeast(r, longBuf, 64 err != nil { fmt.Println("error:", err) } }

func ReadFull(显示源代码)

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

ReadFull 完全读取从 r 到 buf 的 len(buf) 个字节。它返回复制的字节数,如果读取的字节更少,则返回错误。只有在没有字节被读取的情况下,错误才是 EOF 。如果在读取一些但不是全部字节后发生 EOF,则 ReadFull 将返回 ErrUnexpectedEOF 。返回时,n == len(buf) 当且仅当 err == nil 。

示例

package main import ( "fmt" "io" "log" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") buf := make([]byte, 4) if _, err := io.ReadFull(r, buf err != nil { log.Fatal(err) } fmt.Printf("%s\n", buf) // 最小读取大小比io.Reader流大 longBuf := make([]byte, 64) if _, err := io.ReadFull(r, longBuf err != nil { fmt.Println("error:", err) } }

func WriteString(显示源代码)

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

WriteString 将字符串 s 的内容写入 w,它接受一个字节片段。如果 w 实现 WriteString 方法,则直接调用它。否则,w.Write 只会被调用一次。

示例

package main import ( "io" "os" ) func main() { io.WriteString(os.Stdout, "Hello World") }

type ByteReader(显示源代码)

ByteReader 是包装 ReadByte 方法的接口。

ReadByte 读取并返回输入中的下一个字节或遇到的任何错误。如果 ReadByte 返回错误,则不消耗输入字节,并且返回的字节值未定义。

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

type ByteScanner(显示源代码)

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

UnreadByte 导致下一次对 ReadByte 的调用返回与先前对 ReadByte 的调用相同的字节。在没有对 ReadByte 的中间调用的情况下调用 UnreadByte 两次可能是错误的。

type ByteScanner interface { ByteReader UnreadByte() error }

type ByteWriter(显示源代码)

ByteWriter 是包装 WriteByte 方法的接口。

type ByteWriter interface { WriteByte(c byte) error }

type Closer(显示源代码)

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

第一次调用后 Close 的行为是未定义的。具体实现可以记录他们自己的行为。

type Closer interface { Close() error }

type LimitedReader(显示源代码)

LimitedReader 从 R 中读取数据,但将数据量限制为仅返回 N 个字节。每次读取更新 N 将反映新的剩余金额。当 N <= 0 或当基础 R 返回 EOF 时,读取返回 EOF 。

type LimitedReader struct { R Reader // 底层阅读器 N int64 // 剩余最大字节数 }

func (*LimitedReader) Read(显示源代码)

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

type PipeReader(显示源代码)

PipeReader 是pipe的二分之一read。

type PipeReader struct { // 包含已过滤或未导出的字段 }

func Pipe(显示源代码)

func Pipe() (*PipeReader, *PipeWriter)

Pipe 创建一个同步内存管道。它可以用来连接代码期望一个 io.Reader 与代码期待一个 io.Writer 。

读取和写入管道是一对一匹配的,除非需要多个读取消耗单个写入。也就是说,对 PipeWriter 的每次写入都会阻塞,直到它满足 PipeReader 中完全使用写入数据的一个或多个读取。数据直接从写入复制到相应的 Read(或 Reads); 没有内部缓冲。

相互并行或使用 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 是 EOF 。

type PipeWriter(显示源代码)

PipeWriter 是写入一半的管道。

type PipeWriter struct { // 包含已过滤或未导出的字段 }

func (*PipeWriter) Close(显示源代码)

func (w *PipeWriter) Close() error

Close 关闭写入者;后续读取管道的一半将不返回字节和 EOF 。

func (*PipeWriter) CloseWithError(显示源代码)

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

CloseWithError 关闭写入者;从管道的读取一半的后续读取将返回没有字节和 error 错误,或如果错误为零则为 EOF 。

CloseWithError 总是返回 nil 。

func (*PipeWriter) Write(显示源代码)

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

Write 实现了标准的 Write 接口:它将数据写入管道,阻塞直到一个或多个读取器消耗完所有数据或读取端关闭。如果读取结束时出现错误,则该错误返回为 err ; 否则 err 是 ErrClosedPipe 。

type ReadCloser(显示源代码)

ReadCloser 是分组基本的 Read 和 Close 方法的接口。

type ReadCloser interface { Reader Closer }

type ReadSeeker(显示源代码)

ReadSeeker 是将基本的 Read 和 Seek 方法分组的接口。

type ReadSeeker interface { Reader Seeker }

type ReadWriteCloser(显示源代码)

ReadWriteCloser 是对基本的 Read,Write 和 Close 方法进行分组的接口。

type ReadWriteCloser interface { Reader Writer Closer }

type ReadWriteSeeker(显示源代码)

ReadWriteSeeker 是将基本的 Read,Write 和 Seek 方法分组的接口。

type ReadWriteSeeker interface { Reader Writer Seeker }

type ReadWriter(显示源代码)

ReadWriter 是分组基本读写方法的接口。

type ReadWriter interface { Reader Writer }

type Reader(显示源代码)

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

Read 读取 len(p)个字节到 p 。它返回读取的字节数(0 <= n <= len(p))和遇到的任何错误。即使 Read 返回 n <len(p),它也可以在调用期间将全部 p 用作暂存空间。如果某些数据可用但不是 len(p) 字节,则 Read 通常返回可用的数据,而不是等待更多数据。

当 Read 在成功读取 n> 0 字节后遇到错误或文件结束条件时,它会返回读取的字节数。它可能会从相同的调用中返回(非零)错误,或者从后续调用中返回错误(和 n == 0)。这种一般情况的一个实例是,在输入流末尾返回非零字节数的 Reader 可能会返回 err == EOF 或 err == nil 。下一个 Read 应该返回 0,EOF 。

在考虑错误错误之前,Callers 应始终处理返回的 n> 0 个字节。这样做可以正确处理读取一些字节后发生的 I/O 错误以及两种允许的 EOF 行为。

除非 len(p)== 0,否则 Read 的实现不鼓励返回零字节的计数和零错误。调用者应该将返回值 0 和零作为表示什么都没有发生; 特别是它不表示 EOF 。

Implementations 不能保留 p 。

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

func LimitReader(显示源代码)

func LimitReader(r Reader, n int64) Reader

LimitReader 返回一个 Reader,它从 r 读取,但在 n 字节后用 EOF 停止。底层的实现是一个 *LimitedReader 。

示例

package main import ( "io" "log" "os" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") lr := io.LimitReader(r, 4) if _, err := io.Copy(os.Stdout, lr err != nil { log.Fatal(err) } }

func MultiReader(显示源代码)

func MultiReader(readers ...Reader) Reader

MultiReader 返回一个 Reader,它是提供的输入读取器的逻辑连接。他们顺序阅读。一旦所有输入都返回 EOF,Read 将返回 EOF 。如果任何阅读器返回非零非 EOF 错误,则 Read 将返回该错误。

示例

package main import ( "io" "log" "os" "strings" ) func main() { r1 := strings.NewReader("first reader ") r2 := strings.NewReader("second reader ") r3 := strings.NewReader("third reader\n") r := io.MultiReader(r1, r2, r3) if _, err := io.Copy(os.Stdout, r err != nil { log.Fatal(err) } }

func TeeReader(显示源代码)

func TeeReader(r Reader, w Writer) Reader

TeeReader 返回一个读写器,它读写从 r 读取的内容。从 r 执行的所有读取操作都与 w 的相应写入相匹配。没有内部缓冲 - 写入必须在读取完成之前完成。写入时遇到的任何错误都会报告为读取错误。

示例

package main import ( "bytes" "fmt" "io" "io/ioutil" "log" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") var buf bytes.Buffer tee := io.TeeReader(r, &buf) printall := func(r io.Reader) { b, err := ioutil.ReadAll(r) if err != nil { log.Fatal(err) } fmt.Printf("%s", b) } printall(tee) printall(&buf) }

type ReaderAt(显示源代码)

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

ReadAt 将 len(p) 个字节读入底层输入源的偏移 off 开始的 p 。它返回读取的字节数 (0 <= n <= len(p)) 和遇到的任何错误。

当 ReadAt 返回 n <len(p) 时,它将返回一个非零错误,解释为什么不返回更多字节。在这方面,ReadAt 比 Read 更严格。

即使 ReadAt 返回 n <len(p),它也可能在调用期间将所有 p 用作临时空间。如果有些数据可用但不是 len(p) 字节,则 ReadAt 阻塞,直到所有数据都可用或发生错误。在这方面,ReadAt 与 Read 不同。

如果 ReadAt 返回的 n = len(p) 字节位于输入源的末尾,则 ReadAt 可能会返回 err == EOF 或 err == nil 。

如果 ReadAt 正在从具有查找偏移量的输入源读取,则 ReadAt 不应受影响,也不应受基础查找偏移量的影响。

ReadAt 的客户端可以在同一个输入源上执行并行 ReadAt 调用。

实现不能保留 p 。

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

type ReaderFrom(显示源代码)

ReaderFrom 是包装 ReadFrom 方法的接口。

ReadFrom 从 r 读取数据直到出现 EOF 或错误。返回值 n 是读取的字节数。读取过程中遇到的除 io.EOF 外的任何错误也会返回。

复制功能使用 ReaderFrom(如果可用)。

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

type RuneReader(显示源代码)

RuneReader 是包装 ReadRune 方法的接口。

ReadRune 读取单个 UTF-8 编码的 Unicode 字符,并以字节为单位返回符文及其大小。如果没有可用的字符,则会设置 err 。

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

type RuneScanner(显示源代码)

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

UnreadRune 会导致下一次对 ReadRune 的调用返回与先前对 ReadRune 的调用相同的符文。在没有对 ReadRune 的中间调用的情况下调用 UnreadRune 可能是错误的。

type RuneScanner interface { RuneReader UnreadRune() error }

type SectionReader(显示源代码)

SectionReader 在基础 ReaderAt 的一部分上实现 Read,Seek 和 ReadAt 。

type SectionReader struct { // 包含已过滤或未导出的字段 }

示例

package main import ( "io" "log" "os" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") s := io.NewSectionReader(r, 5, 17) if _, err := io.Copy(os.Stdout, s err != nil { log.Fatal(err) } }

func NewSectionReader(显示源代码)

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

NewSectionReader 返回一个 SectionReader,它从 r 处开始读取 offset,并在 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)

示例

package main import ( "fmt" "io" "log" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") s := io.NewSectionReader(r, 5, 16) buf := make([]byte, 6) if _, err := s.ReadAt(buf, 10 err != nil { log.Fatal(err) } fmt.Printf("%s\n", buf) }

func (*SectionReader) Seek(显示源代码)

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

示例

package main import ( "fmt" "io" "log" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") s := io.NewSectionReader(r, 5, 16) if _, err := s.Seek(10, io.SeekStart err != nil { log.Fatal(err) } buf := make([]byte, 6) if _, err := s.Read(buf err != nil { log.Fatal(err) } fmt.Printf("%s\n", buf) }

func (*SectionReader) Size(显示源代码)

func (s *SectionReader) Size() int64

大小以字节为单位返回该部分的大小。

type Seeker(显示源代码)

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

Seek 设置下一个读取或写入偏移量的偏移量,根据此解释:SeekStart 表示相对于文件的开始,SeekCurrent 表示相对于当前偏移量,SeekEnd 表示相对于结束。Seek 返回相对于文件开始的新偏移量和一个错误(如果有的话)。

在文件开始之前寻找偏移量是一个错误。寻求任何正偏移量是合法的,但后续对基础对象的 I/O 操作的行为取决于实现。

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

type WriteCloser(显示源代码)

WriteCloser 是分组基本 Write 和 Close 方法的接口。

type WriteCloser interface { Writer Closer }

type WriteSeeker(显示源代码)

WriteSeeker 是将基本写入和查找方法分组的接口。

type WriteSeeker interface { Writer Seeker }

type Writer(显示源代码)

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

写从 p 写入 len(p) 个字节到底层数据流。它返回从p (0 <= n <= len(p)) 写入的字节数,以及遇到任何导致写入提前停止的错误。如果返回 n < len(p),则写入必须返回非零错误。写入不能修改片数据,即使是暂时的。

实现不能保留 p 。

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

func MultiWriter(显示源代码)

func MultiWriter(writers ...Writer) Writer

MultiWriter 创建一个写入器,将其写入所有提供的写入器,类似于 Unix tee(1) 命令。

示例

package main import ( "bytes" "fmt" "io" "log" "strings" ) func main() { r := strings.NewReader("some io.Reader stream to be read\n") var buf1, buf2 bytes.Buffer w := io.MultiWriter(&buf1, &buf2) if _, err := io.Copy(w, r err != nil { log.Fatal(err) } fmt.Print(buf1.String()) fmt.Print(buf2.String()) }

type WriterAt(显示源代码)

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

WriteAt 将 p 的 len(p) 个字节写入偏移关闭的基础数据流。它返回从 p (0 <= n <= len(p))写入的字节数,以及遇到任何导致写入提前停止的错误。如果返回 n < len(p),WriteAt 必须返回非零错误。

如果 WriteAt 正在使用搜索偏移量写入目标,则 WriteAt 不应受影响,也不应受底层搜索偏移量的影响。

如果范围不重叠,则 WriteAt 的客户端可以在同一个目的地上执行并行 WriteAt 调用。

实现不能保留 p 。

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

type WriterTo(显示源代码)

WriterTo 是包装 WriteTo 方法的接口。

WriteTo 将数据写入 w,直到没有更多数据要写入或出现错误时为止。返回值 n 是写入的字节数。写入过程中遇到的任何错误也会返回。

复制功能使用 WriterTo(如果可用)。

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

子目录

NameSynopsis
ioutilPackage ioutil实现了一些 I/O 实用程序功能。