©
This document uses PHP Chinese website manual Release
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
CopyBuffer
CopyN
LimitReader
MultiReader
MultiWriter
ReadAtLeast
ReadFull
SectionReader
SectionReader.ReadAt
SectionReader.Seek
TeeReader
WriteString
io.go multi.go pipe.go
寻求哪些值。
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(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 mainimport ("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(dst Writer, src Reader, buf []byte) (written int64, err error)
CopyBuffer 与 Copy 相同，只是它通过提供的缓冲区（如果需要的话）进行分级，而不是分配临时的缓冲区。如果 buf 为零，则分配一个；否则如果它的长度为零，CopyBuffer 会发生混乱。
package mainimport ("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(dst Writer, src Reader, n int64) (written int64, err error)
CopyN 拷贝从 src 到 dst 的 n 个字节（或直出现一个错误）。它返回拷贝的字节数和复制时遇到的最早的错误。返回时，written == n 当且仅当 err == nil 。
如果 dst 实现 ReaderFrom 接口，则使用它实现副本。
package mainimport ("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(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 mainimport ("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(r Reader, buf []byte) (n int, err error)
ReadFull 完全读取从 r 到 buf 的 len(buf) 个字节。它返回复制的字节数，如果读取的字节更少，则返回错误。只有在没有字节被读取的情况下，错误才是 EOF 。如果在读取一些但不是全部字节后发生 EOF，则 ReadFull 将返回 ErrUnexpectedEOF 。返回时，n == len(buf) 当且仅当 err == nil 。
package mainimport ("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(w Writer, s string) (n int, err error)
WriteString 将字符串 s 的内容写入 w，它接受一个字节片段。如果 w 实现 WriteString 方法，则直接调用它。否则，w.Write 只会被调用一次。
package mainimport ("io""os")func main() {
io.WriteString(os.Stdout, "Hello World")}ByteReader 是包装 ReadByte 方法的接口。
ReadByte 读取并返回输入中的下一个字节或遇到的任何错误。如果 ReadByte 返回错误，则不消耗输入字节，并且返回的字节值未定义。
type ByteReader interface { ReadByte() (byte, error)}ByteScanner 是将 UnreadByte 方法添加到基本 ReadByte 方法的接口。
UnreadByte 导致下一次对 ReadByte 的调用返回与先前对 ReadByte 的调用相同的字节。在没有对 ReadByte 的中间调用的情况下调用 UnreadByte 两次可能是错误的。
type ByteScanner interface {
ByteReader UnreadByte() error}ByteWriter 是包装 WriteByte 方法的接口。
type ByteWriter interface { WriteByte(c byte) error}Closer 是包装基本 Close 方法的接口。
第一次调用后 Close 的行为是未定义的。具体实现可以记录他们自己的行为。
type Closer interface { Close() error}LimitedReader 从 R 中读取数据，但将数据量限制为仅返回 N 个字节。每次读取更新 N 将反映新的剩余金额。当 N <= 0 或当基础 R 返回 EOF 时，读取返回 EOF 。
type LimitedReader struct {
R Reader // 底层阅读器
N int64 // 剩余最大字节数}func (l *LimitedReader) Read(p []byte) (n int, err error)
PipeReader 是pipe的二分之一read。
type PipeReader struct { // 包含已过滤或未导出的字段}func Pipe() (*PipeReader, *PipeWriter)
Pipe 创建一个同步内存管道。它可以用来连接代码期望一个 io.Reader 与代码期待一个 io.Writer 。
读取和写入管道是一对一匹配的，除非需要多个读取消耗单个写入。也就是说，对 PipeWriter 的每次写入都会阻塞，直到它满足 PipeReader 中完全使用写入数据的一个或多个读取。数据直接从写入复制到相应的 Read（或 Reads）; 没有内部缓冲。
相互并行或使用 Close 并行调用 Read 和 Write 是安全的。并行调用读取和并行调用写入也是安全的：个别调用将按顺序进行门控。
func (r *PipeReader) Close() error
Close 关闭阅读器；随后写入管道的写入一半将返回错误 ErrClosedPipe 。
func (r *PipeReader) CloseWithError(err error) error
CloseWithError 关闭阅读器；随后写入管道的写入一半将返回错误 err 。
func (r *PipeReader) Read(data []byte) (n int, err error)
Read 实现标准的 Read 接口：它从管道读取数据，阻塞直到写入者到达或写入结束被关闭。如果写入结束时出现错误，则该错误返回为错误；否则 err 是 EOF 。
PipeWriter 是写入一半的管道。
type PipeWriter struct { // 包含已过滤或未导出的字段}func (w *PipeWriter) Close() error
Close 关闭写入者；后续读取管道的一半将不返回字节和 EOF 。
func (w *PipeWriter) CloseWithError(err error) error
CloseWithError 关闭写入者；从管道的读取一半的后续读取将返回没有字节和 error 错误，或如果错误为零则为 EOF 。
CloseWithError 总是返回 nil 。
func (w *PipeWriter) Write(data []byte) (n int, err error)
Write 实现了标准的 Write 接口：它将数据写入管道，阻塞直到一个或多个读取器消耗完所有数据或读取端关闭。如果读取结束时出现错误，则该错误返回为 err ; 否则 err 是 ErrClosedPipe 。
ReadCloser 是分组基本的 Read 和 Close 方法的接口。
type ReadCloser interface {
Reader
Closer}ReadSeeker 是将基本的 Read 和 Seek 方法分组的接口。
type ReadSeeker interface {
Reader
Seeker}ReadWriteCloser 是对基本的 Read，Write 和 Close 方法进行分组的接口。
type ReadWriteCloser interface {
Reader
Writer
Closer}ReadWriteSeeker 是将基本的 Read，Write 和 Seek 方法分组的接口。
type ReadWriteSeeker interface {
Reader
Writer
Seeker}ReadWriter 是分组基本读写方法的接口。
type ReadWriter interface {
Reader
Writer}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(r Reader, n int64) Reader
LimitReader 返回一个 Reader，它从 r 读取，但在 n 字节后用 EOF 停止。底层的实现是一个 *LimitedReader 。
package mainimport ("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(readers ...Reader) Reader
MultiReader 返回一个 Reader，它是提供的输入读取器的逻辑连接。他们顺序阅读。一旦所有输入都返回 EOF，Read 将返回 EOF 。如果任何阅读器返回非零非 EOF 错误，则 Read 将返回该错误。
package mainimport ("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(r Reader, w Writer) Reader
TeeReader 返回一个读写器，它读写从 r 读取的内容。从 r 执行的所有读取操作都与 w 的相应写入相匹配。没有内部缓冲 - 写入必须在读取完成之前完成。写入时遇到的任何错误都会报告为读取错误。
package mainimport ("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)}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)}ReaderFrom 是包装 ReadFrom 方法的接口。
ReadFrom 从 r 读取数据直到出现 EOF 或错误。返回值 n 是读取的字节数。读取过程中遇到的除 io.EOF 外的任何错误也会返回。
复制功能使用 ReaderFrom（如果可用）。
type ReaderFrom interface { ReadFrom(r Reader) (n int64, err error)}RuneReader 是包装 ReadRune 方法的接口。
ReadRune 读取单个 UTF-8 编码的 Unicode 字符，并以字节为单位返回符文及其大小。如果没有可用的字符，则会设置 err 。
type RuneReader interface { ReadRune() (r rune, size int, err error)}RuneScanner 是将 UnreadRune 方法添加到基本 ReadRune 方法的接口。
UnreadRune 会导致下一次对 ReadRune 的调用返回与先前对 ReadRune 的调用相同的符文。在没有对 ReadRune 的中间调用的情况下调用 UnreadRune 可能是错误的。
type RuneScanner interface {
RuneReader UnreadRune() error}SectionReader 在基础 ReaderAt 的一部分上实现 Read，Seek 和 ReadAt 。
type SectionReader struct { // 包含已过滤或未导出的字段}package mainimport ("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(r ReaderAt, off int64, n int64) *SectionReader
NewSectionReader 返回一个 SectionReader，它从 r 处开始读取 offset，并在 n 字节后用 EOF 停止。
func (s *SectionReader) Read(p []byte) (n int, err error)
func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error)
package mainimport ("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 (s *SectionReader) Seek(offset int64, whence int) (int64, error)
package mainimport ("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 (s *SectionReader) Size() int64
大小以字节为单位返回该部分的大小。
Seeker 是包装基本 Seek 方法的接口。
Seek 设置下一个读取或写入偏移量的偏移量，根据此解释：SeekStart 表示相对于文件的开始，SeekCurrent 表示相对于当前偏移量，SeekEnd 表示相对于结束。Seek 返回相对于文件开始的新偏移量和一个错误（如果有的话）。
在文件开始之前寻找偏移量是一个错误。寻求任何正偏移量是合法的，但后续对基础对象的 I/O 操作的行为取决于实现。
type Seeker interface { Seek(offset int64, whence int) (int64, error)}WriteCloser 是分组基本 Write 和 Close 方法的接口。
type WriteCloser interface {
Writer
Closer}WriteSeeker 是将基本写入和查找方法分组的接口。
type WriteSeeker interface {
Writer
Seeker}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(writers ...Writer) Writer
MultiWriter 创建一个写入器，将其写入所有提供的写入器，类似于 Unix tee(1) 命令。
package mainimport ("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())}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)}WriterTo 是包装 WriteTo 方法的接口。
WriteTo 将数据写入 w，直到没有更多数据要写入或出现错误时为止。返回值 n 是写入的字节数。写入过程中遇到的任何错误也会返回。
复制功能使用 WriterTo（如果可用）。
type WriterTo interface { WriteTo(w Writer) (n int64, err error)}Name | Synopsis |
|---|---|
ioutil | Package ioutil实现了一些 I/O 实用程序功能。 |