package io · Go 標準庫中文參考

# package io `import "io"` io包提供了對I/O原語的基本接口。本包的基本任務是包裝這些原語已有的實現（如os包里的原語），使之成為共享的公共接口，這些公共接口抽象出了泛用的函數并附加了一些相關的原語的操作。因為這些接口和原語是對底層實現完全不同的低水平操作的包裝，除非得到其它方面的通知，客戶端不應假設它們是并發執行安全的。 ## Index * [Variables](#pkg-variables) * [type Reader](#Reader) * [type Writer](#Writer) * [type Closer](#Closer) * [type Seeker](#Seeker) * [type ReadCloser](#ReadCloser) * [type ReadSeeker](#ReadSeeker) * [type WriteCloser](#WriteCloser) * [type WriteSeeker](#WriteSeeker) * [type ReadWriter](#ReadWriter) * [type ReadWriteCloser](#ReadWriteCloser) * [type ReadWriteSeeker](#ReadWriteSeeker) * [type ReaderAt](#ReaderAt) * [type WriterAt](#WriterAt) * [type ByteReader](#ByteReader) * [type ByteScanner](#ByteScanner) * [type RuneReader](#RuneReader) * [type RuneScanner](#RuneScanner) * [type ByteWriter](#ByteWriter) * [type ReaderFrom](#ReaderFrom) * [type WriterTo](#WriterTo) * [type LimitedReader](#LimitedReader) * [func LimitReader(r Reader, n int64) Reader](#LimitReader) * [func (l \*LimitedReader) Read(p []byte) (n int, err error)](#LimitedReader.Read) * [type SectionReader](#SectionReader) * [func NewSectionReader(r ReaderAt, off int64, n int64) \*SectionReader](#NewSectionReader) * [func (s \*SectionReader) Size() int64](#SectionReader.Size) * [func (s \*SectionReader) Read(p []byte) (n int, err error)](#SectionReader.Read) * [func (s \*SectionReader) ReadAt(p []byte, off int64) (n int, err error)](#SectionReader.ReadAt) * [func (s \*SectionReader) Seek(offset int64, whence int) (int64, error)](#SectionReader.Seek) * [type PipeReader](#PipeReader) * [func Pipe() (\*PipeReader, \*PipeWriter)](#Pipe) * [func (r \*PipeReader) Read(data []byte) (n int, err error)](#PipeReader.Read) * [func (r \*PipeReader) Close() error](#PipeReader.Close) * [func (r \*PipeReader) CloseWithError(err error) error](#PipeReader.CloseWithError) * [type PipeWriter](#PipeWriter) * [func (w \*PipeWriter) Write(data []byte) (n int, err error)](#PipeWriter.Write) * [func (w \*PipeWriter) Close() error](#PipeWriter.Close) * [func (w \*PipeWriter) CloseWithError(err error) error](#PipeWriter.CloseWithError) * [func TeeReader(r Reader, w Writer) Reader](#TeeReader) * [func MultiReader(readers ...Reader) Reader](#MultiReader) * [func MultiWriter(writers ...Writer) Writer](#MultiWriter) * [func Copy(dst Writer, src Reader) (written int64, err error)](#Copy) * [func CopyN(dst Writer, src Reader, n int64) (written int64, err error)](#CopyN) * [func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)](#ReadAtLeast) * [func ReadFull(r Reader, buf []byte) (n int, err error)](#ReadFull) * [func WriteString(w Writer, s string) (n int, err error)](#WriteString) ## Variables ``` var EOF = errors.New("EOF") ``` EOF當無法得到更多輸入時，Read方法返回EOF。當函數一切正常的到達輸入的結束時，就應返回EOF。如果在一個結構化數據流中EOF在不期望的位置出現了，則應返回錯誤ErrUnexpectedEOF或者其它給出更多細節的錯誤。 ``` var ErrClosedPipe = errors.New("io: read/write on closed pipe") ``` 當從一個已關閉的Pipe讀取或者寫入時，會返回ErrClosedPipe。 ``` var ErrNoProgress = errors.New("multiple Read calls return no data or error") ``` 某些使用io.Reader接口的客戶端如果多次調用Read都不返回數據也不返回錯誤時，就會返回本錯誤，一般來說是io.Reader的實現有問題的標志。 ``` var ErrShortBuffer = errors.New("short buffer") ``` ErrShortBuffer表示讀取操作需要大緩沖，但提供的緩沖不夠大。 ``` var ErrShortWrite = errors.New("short write") ``` ErrShortWrite表示寫入操作寫入的數據比提供的少，卻沒有顯式的返回錯誤。 ``` var ErrUnexpectedEOF = errors.New("unexpected EOF") ``` ErrUnexpectedEOF表示在讀取一個固定尺寸的塊或者數據結構時，在讀取未完全時遇到了EOF。 ## type [Reader](https://github.com/golang/go/blob/master/src/io/io.go#L67 "View Source") ``` type Reader interface { Read(p []byte) (n int, err error) } ``` Reader接口用于包裝基本的讀取方法。 Read方法讀取len(p)字節數據寫入p。它返回寫入的字節數和遇到的任何錯誤。即使Read方法返回值n < len(p)，本方法在被調用時仍可能使用p的全部長度作為暫存空間。如果有部分可用數據，但不夠len(p)字節，Read按慣例會返回可以讀取到的數據，而不是等待更多數據。當Read在讀取n > 0個字節后遭遇錯誤或者到達文件結尾時，會返回讀取的字節數。它可能會在該次調用返回一個非nil的錯誤，或者在下一次調用時返回0和該錯誤。一個常見的例子，Reader接口會在輸入流的結尾返回非0的字節數，返回值err == EOF或err == nil。但不管怎樣，下一次Read調用必然返回(0, EOF)。調用者應該總是先處理讀取的n > 0字節再處理錯誤值。這么做可以正確的處理發生在讀取部分數據后的I/O錯誤，也能正確處理EOF事件。如果Read的某個實現返回0字節數和nil錯誤值，表示被阻礙；調用者應該將這種情況視為未進行操作。 ## type [Writer](https://github.com/golang/go/blob/master/src/io/io.go#L78 "View Source") ``` type Writer interface { Write(p []byte) (n int, err error) } ``` Writer接口用于包裝基本的寫入方法。 Write方法len(p)?字節數據從p寫入底層的數據流。它會返回寫入的字節數(0 <= n <= len(p))和遇到的任何導致寫入提取結束的錯誤。Write必須返回非nil的錯誤，如果它返回的?n < len(p)。Write不能修改切片p中的數據，即使臨時修改也不行。 ## type [Closer](https://github.com/golang/go/blob/master/src/io/io.go#L86 "View Source") ``` type Closer interface { Close() error } ``` Closer接口用于包裝基本的關閉方法。在第一次調用之后再次被調用時，Close方法的的行為是未定義的。某些實現可能會說明他們自己的行為。 ## type [Seeker](https://github.com/golang/go/blob/master/src/io/io.go#L101 "View Source") ``` type Seeker interface { Seek(offset int64, whence int) (int64, error) } ``` Seeker接口用于包裝基本的移位方法。 Seek方法設定下一次讀寫的位置：偏移量為offset，校準點由whence確定：0表示相對于文件起始；1表示相對于當前位置；2表示相對于文件結尾。Seek方法返回新的位置以及可能遇到的錯誤。移動到一個絕對偏移量為負數的位置會導致錯誤。移動到任何偏移量為正數的位置都是合法的，但其下一次I/O操作的具體行為則要看底層的實現。 ## type [ReadCloser](https://github.com/golang/go/blob/master/src/io/io.go#L112 "View Source") ``` type ReadCloser interface { Reader Closer } ``` ReadCloser接口聚合了基本的讀取和關閉操作。 ## type [ReadSeeker](https://github.com/golang/go/blob/master/src/io/io.go#L131 "View Source") ``` type ReadSeeker interface { Reader Seeker } ``` ReadSeeker接口聚合了基本的讀取和移位操作。 ## type [WriteCloser](https://github.com/golang/go/blob/master/src/io/io.go#L118 "View Source") ``` type WriteCloser interface { Writer Closer } ``` WriteCloser接口聚合了基本的寫入和關閉操作。 ## type [WriteSeeker](https://github.com/golang/go/blob/master/src/io/io.go#L137 "View Source") ``` type WriteSeeker interface { Writer Seeker } ``` WriteSeeker接口聚合了基本的寫入和移位操作。 ## type [ReadWriter](https://github.com/golang/go/blob/master/src/io/io.go#L106 "View Source") ``` type ReadWriter interface { Reader Writer } ``` ReadWriter接口聚合了基本的讀寫操作。 ## type [ReadWriteCloser](https://github.com/golang/go/blob/master/src/io/io.go#L124 "View Source") ``` type ReadWriteCloser interface { Reader Writer Closer } ``` ReadWriteCloser接口聚合了基本的讀寫和關閉操作。 ## type [ReadWriteSeeker](https://github.com/golang/go/blob/master/src/io/io.go#L143 "View Source") ``` type ReadWriteSeeker interface { Reader Writer Seeker } ``` ReadWriteSeeker接口聚合了基本的讀寫和移位操作。 ## type [ReaderAt](https://github.com/golang/go/blob/master/src/io/io.go#L195 "View Source") ``` type ReaderAt interface { ReadAt(p []byte, off int64) (n int, err error) } ``` ReaderAt接口包裝了基本的ReadAt方法。 ReadAt從底層輸入流的偏移量off位置讀取len(p)字節數據寫入p，?它返回讀取的字節數(0 <= n <= len(p))和遇到的任何錯誤。當ReadAt方法返回值n < len(p)時，它會返回一個非nil的錯誤來說明為啥沒有讀取更多的字節。在這方面，ReadAt是比Read要嚴格的。即使ReadAt方法返回值?n < len(p)，它在被調用時仍可能使用p的全部長度作為暫存空間。如果有部分可用數據，但不夠len(p)字節，ReadAt會阻塞直到獲取len(p)個字節數據或者遇到錯誤。在這方面，ReadAt和Read是不同的。如果ReadAt返回時到達輸入流的結尾，而返回值n == len(p)，其返回值err既可以是EOF也可以是nil。如果ReadAt是從某個有偏移量的底層輸入流（的Reader包裝）讀取，ReadAt方法既不應影響底層的偏移量，也不應被底層的偏移量影響。 ReadAt方法的調用者可以對同一輸入流執行并行的ReadAt調用。 ## type [WriterAt](https://github.com/golang/go/blob/master/src/io/io.go#L212 "View Source") ``` type WriterAt interface { WriteAt(p []byte, off int64) (n int, err error) } ``` WriterAt接口包裝了基本的WriteAt方法。 WriteAt將p全部len(p)字節數據寫入底層數據流的偏移量off位置。它返回寫入的字節數(0 <= n <= len(p))和遇到的任何導致寫入提前中止的錯誤。當其返回值n < len(p)時，WriteAt必須放哪會一個非nil的錯誤。如果WriteAt寫入的對象是某個有偏移量的底層輸出流（的Writer包裝），WriteAt方法既不應影響底層的偏移量，也不應被底層的偏移量影響。 ReadAt方法的調用者可以對同一輸入流執行并行的WriteAt調用。（前提是寫入范圍不重疊） ## type [ByteReader](https://github.com/golang/go/blob/master/src/io/io.go#L220 "View Source") ``` type ByteReader interface { ReadByte() (c byte, err error) } ``` ByteReader是基本的ReadByte方法的包裝。 ReadByte讀取輸入中的單個字節并返回。如果沒有字節可讀取，會返回錯誤。 ## type [ByteScanner](https://github.com/golang/go/blob/master/src/io/io.go#L231 "View Source") ``` type ByteScanner interface { ByteReader UnreadByte() error } ``` ByteScanner接口在基本的ReadByte方法之外還添加了UnreadByte方法。 UnreadByte方法讓下一次調用ReadByte時返回之前調用ReadByte時返回的同一個字節。連續調用兩次UnreadByte方法而中間沒有調用ReadByte時，可能會導致錯誤。 ## type [RuneReader](https://github.com/golang/go/blob/master/src/io/io.go#L246 "View Source") ``` type RuneReader interface { ReadRune() (r rune, size int, err error) } ``` RuneReader是基本的ReadRune方法的包裝。 ReadRune讀取單個utf-8編碼的字符，返回該字符和它的字節長度。如果沒有有效的字符，會返回錯誤。 ## type [RuneScanner](https://github.com/golang/go/blob/master/src/io/io.go#L257 "View Source") ``` type RuneScanner interface { RuneReader UnreadRune() error } ``` RuneScanner接口在基本的ReadRune方法之外還添加了UnreadRune方法。 UnreadRune方法讓下一次調用ReadRune時返回之前調用ReadRune時返回的同一個utf-8字符。連續調用兩次UnreadRune方法而中間沒有調用ReadRune時，可能會導致錯誤。 ## type [ByteWriter](https://github.com/golang/go/blob/master/src/io/io.go#L237 "View Source") ``` type ByteWriter interface { WriteByte(c byte) error } ``` ByteWriter是基本的WriteByte方法的包裝。 ## type [ReaderFrom](https://github.com/golang/go/blob/master/src/io/io.go#L156 "View Source") ``` type ReaderFrom interface { ReadFrom(r Reader) (n int64, err error) } ``` ReaderFrom接口包裝了基本的ReadFrom方法。 ReadFrom方法從r讀取數據直到EOF或者遇到錯誤。返回值n是讀取的字節數，執行時遇到的錯誤（EOF除外）也會被返回。 ## type [WriterTo](https://github.com/golang/go/blob/master/src/io/io.go#L167 "View Source") ``` type WriterTo interface { WriteTo(w Writer) (n int64, err error) } ``` WriterTo接口包裝了基本的WriteTo方法。 WriteTo方法將數據寫入w直到沒有數據可以寫入或者遇到錯誤。返回值n是寫入的字節數，執行時遇到的任何錯誤也會被返回。 ## type [LimitedReader](https://github.com/golang/go/blob/master/src/io/io.go#L387 "View Source") ``` type LimitedReader struct { R Reader // 底層Reader接口 N int64 // 剩余可讀取字節數 } ``` LimitedReader從R中讀取數據，但限制可以讀取的數據的量為最多N字節，每次調用Read方法都會更新N以標記剩余可以讀取的字節數。 ### func [LimitReader](https://github.com/golang/go/blob/master/src/io/io.go#L382 "View Source") ``` func LimitReader(r Reader, n int64) Reader ``` 返回一個Reader，它從r中讀取n個字節后以EOF停止。返回值接口的底層為\*LimitedReader類型。 ### func (\*LimitedReader) [Read](https://github.com/golang/go/blob/master/src/io/io.go#L392 "View Source") ``` func (l *LimitedReader) Read(p []byte) (n int, err error) ``` ## type [SectionReader](https://github.com/golang/go/blob/master/src/io/io.go#L412 "View Source") ``` type SectionReader struct { // 內含隱藏或非導出字段 } ``` SectionReader實現了對底層滿足ReadAt接口的輸入流某個片段的Read、ReadAt、Seek方法。 ### func [NewSectionReader](https://github.com/golang/go/blob/master/src/io/io.go#L406 "View Source") ``` func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader ``` 返回一個從r中的偏移量off處為起始，讀取n個字節后以EOF停止的SectionReader。 ### func (\*SectionReader) [Size](https://github.com/golang/go/blob/master/src/io/io.go#L469 "View Source") ``` func (s *SectionReader) Size() int64 ``` Size返回該片段的字節數。 ### func (\*SectionReader) [Read](https://github.com/golang/go/blob/master/src/io/io.go#L419 "View Source") ``` func (s *SectionReader) Read(p []byte) (n int, err error) ``` ### func (\*SectionReader) [ReadAt](https://github.com/golang/go/blob/master/src/io/io.go#L452 "View Source") ``` func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error) ``` ### func (\*SectionReader) [Seek](https://github.com/golang/go/blob/master/src/io/io.go#L434 "View Source") ``` func (s *SectionReader) Seek(offset int64, whence int) (int64, error) ``` ## type [PipeReader](https://github.com/golang/go/blob/master/src/io/pipe.go#L124 "View Source") ``` type PipeReader struct { // 內含隱藏或非導出字段 } ``` PipeReader是一個管道的讀取端。 ### func [Pipe](https://github.com/golang/go/blob/master/src/io/pipe.go#L186 "View Source") ``` func Pipe() (*PipeReader, *PipeWriter) ``` Pipe創建一個同步的內存中的管道。它可以用于連接期望io.Reader的代碼和期望io.Writer的代碼。一端的讀取對應另一端的寫入，直接在兩端拷貝數據，沒有內部緩沖。可以安全的并行調用Read和Write或者Read/Write與Close方法。Close方法會在最后一次阻塞中的I/O操作結束后完成。并行調用Read或并行調用Write也是安全的：每一個獨立的調用會依次進行。 ### func (\*PipeReader) [Read](https://github.com/golang/go/blob/master/src/io/pipe.go#L133 "View Source") ``` func (r *PipeReader) Read(data []byte) (n int, err error) ``` Read實現了標準Reader接口：它從管道中讀取數據，會阻塞直到寫入端開始寫入或寫入端被關閉。 ### func (\*PipeReader) [Close](https://github.com/golang/go/blob/master/src/io/pipe.go#L139 "View Source") ``` func (r *PipeReader) Close() error ``` Close關閉讀取器；關閉后如果對管道的寫入端進行寫入操作，就會返回(0, ErrClosedPip)。 ### func (\*PipeReader) [CloseWithError](https://github.com/golang/go/blob/master/src/io/pipe.go#L145 "View Source") ``` func (r *PipeReader) CloseWithError(err error) error ``` CloseWithError類似Close方法，但將調用Write時返回的錯誤改為err。 ## type [PipeWriter](https://github.com/golang/go/blob/master/src/io/pipe.go#L151 "View Source") ``` type PipeWriter struct { // 內含隱藏或非導出字段 } ``` PipeWriter是一個管道的寫入端。 ### func (\*PipeWriter) [Write](https://github.com/golang/go/blob/master/src/io/pipe.go#L160 "View Source") ``` func (w *PipeWriter) Write(data []byte) (n int, err error) ``` Write實現了標準Writer接口：它將數據寫入到管道中，會阻塞直到讀取器讀完所有的數據或讀取端被關閉。 ### func (\*PipeWriter) [Close](https://github.com/golang/go/blob/master/src/io/pipe.go#L166 "View Source") ``` func (w *PipeWriter) Close() error ``` Close關閉寫入器；關閉后如果對管道的讀取端進行讀取操作，就會返回(0, EOF)。 ### func (\*PipeWriter) [CloseWithError](https://github.com/golang/go/blob/master/src/io/pipe.go#L172 "View Source") ``` func (w *PipeWriter) CloseWithError(err error) error ``` CloseWithError類似Close方法，但將調用Read時返回的錯誤改為err。 ## func [TeeReader](https://github.com/golang/go/blob/master/src/io/io.go#L476 "View Source") ``` func TeeReader(r Reader, w Writer) Reader ``` TeeReader返回一個將其從r讀取的數據寫入w的Reader接口。所有通過該接口對r的讀取都會執行對應的對w的寫入。沒有內部的緩沖：寫入必須在讀取完成前完成。寫入時遇到的任何錯誤都會作為讀取錯誤返回。 ## func [MultiReader](https://github.com/golang/go/blob/master/src/io/multi.go#L31 "View Source") ``` func MultiReader(readers ...Reader) Reader ``` MultiReader返回一個將提供的Reader在邏輯上串聯起來的Reader接口。他們依次被讀取。當所有的輸入流都讀取完畢，Read才會返回EOF。如果readers中任一個返回了非nil非EOF的錯誤，Read方法會返回該錯誤。 ## func [MultiWriter](https://github.com/golang/go/blob/master/src/io/multi.go#L57 "View Source") ``` func MultiWriter(writers ...Writer) Writer ``` MultiWriter創建一個Writer接口，會將提供給其的數據寫入所有創建時提供的Writer接口。 ## func [Copy](https://github.com/golang/go/blob/master/src/io/io.go#L341 "View Source") ``` func Copy(dst Writer, src Reader) (written int64, err error) ``` 將src的數據拷貝到dst，直到在src上到達EOF或發生錯誤。返回拷貝的字節數和遇到的第一個錯誤。對成功的調用，返回值err為nil而非EOF，因為Copy定義為從src讀取直到EOF，它不會將讀取到EOF視為應報告的錯誤。如果src實現了WriterTo接口，本函數會調用src.WriteTo(dst)進行拷貝；否則如果dst實現了ReaderFrom接口，本函數會調用dst.ReadFrom(src)進行拷貝。 ## func [CopyN](https://github.com/golang/go/blob/master/src/io/io.go#L317 "View Source") ``` func CopyN(dst Writer, src Reader, n int64) (written int64, err error) ``` 從src拷貝n個字節數據到dst，直到在src上到達EOF或發生錯誤。返回復制的字節數和遇到的第一個錯誤。只有err為nil時，written才會等于n。如果dst實現了ReaderFrom接口，本函數很調用它實現拷貝。 ## func [ReadAtLeast](https://github.com/golang/go/blob/master/src/io/io.go#L283 "View Source") ``` func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error) ``` ReadAtLeast從r至少讀取min字節數據填充進buf。函數返回寫入的字節數和錯誤（如果沒有讀取足夠的字節）。只有沒有讀取到字節時才可能返回EOF；如果讀取了有但不夠的字節時遇到了EOF，函數會返回ErrUnexpectedEOF。?如果min比buf的長度還大，函數會返回ErrShortBuffer。只有返回值err為nil時，返回值n才會不小于min。 ## func [ReadFull](https://github.com/golang/go/blob/master/src/io/io.go#L306 "View Source") ``` func ReadFull(r Reader, buf []byte) (n int, err error) ``` ReadFull從r精確地讀取len(buf)字節數據填充進buf。函數返回寫入的字節數和錯誤（如果沒有讀取足夠的字節）。只有沒有讀取到字節時才可能返回EOF；如果讀取了有但不夠的字節時遇到了EOF，函數會返回ErrUnexpectedEOF。?只有返回值err為nil時，返回值n才會等于len(buf)。 ## func [WriteString](https://github.com/golang/go/blob/master/src/io/io.go#L269 "View Source") ``` func WriteString(w Writer, s string) (n int, err error) ``` WriteString函數將字符串s的內容寫入w中。如果w已經實現了WriteString方法，函數會直接調用該方法。