Golang的io包API中文說明
package io
import "io"
io包提供了對I/O原語的基本接口。本包的基本任務是包裝這些原語已有的實現（如os包里的原語），使之成為共享的公共接口，這些公共接口抽象出了泛用的函數并附加了一些相關的原語的操作。
因為這些接口和原語是對底層實現完全不同的低水平操作的包裝，除非得到其它方面的通知，客戶端不應假設它們是并發執行安全的。
Index
- Variables
- type Reader
- type Writer
- type Closer
- type Seeker
- type ReadCloser
- type ReadSeeker
- type WriteCloser
- type WriteSeeker
- type ReadWriter
- type ReadWriteCloser
- type ReadWriteSeeker
- type ReaderAt
- type WriterAt
- type ByteReader
- type ByteScanner
- type RuneReader
- type RuneScanner
- type ByteWriter
- type ReaderFrom
- type WriterTo
- type LimitedReader
- func LimitReader(r Reader, n int64) Reader
- func (l *LimitedReader) Read(p []byte) (n int, err error)
- type SectionReader
- func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader
- func (s *SectionReader) Size() int64
- 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)
- type PipeReader
- func Pipe() (*PipeReader, *PipeWriter)
- func (r *PipeReader) Read(data []byte) (n int, err error)
- func (r *PipeReader) Close() error
- func (r *PipeReader) CloseWithError(err error) error
- type PipeWriter
- func (w *PipeWriter) Write(data []byte) (n int, err error)
- func (w *PipeWriter) Close() error
- func (w *PipeWriter) CloseWithError(err error) error
- func TeeReader(r Reader, w Writer) Reader
- func MultiReader(readers ...Reader) Reader
- func MultiWriter(writers ...Writer) Writer
- func Copy(dst Writer, src Reader) (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)
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
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
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
type Closer interface { Close() error } Closer接口用于包裝基本的關閉方法。
在第一次調用之后再次被調用時，Close方法的的行為是未定義的。某些實現可能會說明他們自己的行為。
type Seeker
type Seeker interface { Seek(offset int64, whence int) (int64, error)
} Seeker接口用于包裝基本的移位方法。
Seek方法設定下一次讀寫的位置：偏移量為offset，校準點由whence確定：0表示相對于文件起始；1表示相對于當前位置；2表示相對于文件結尾。Seek方法返回新的位置以及可能遇到的錯誤。
移動到一個絕對偏移量為負數的位置會導致錯誤。移動到任何偏移量為正數的位置都是合法的，但其下一次I/O操作的具體行為則要看底層的實現。
type ReadCloser
type ReadCloser interface { Reader Closer } ReadCloser接口聚合了基本的讀取和關閉操作。
type ReadSeeker
type ReadSeeker interface { Reader Seeker } ReadSeeker接口聚合了基本的讀取和移位操作。
type WriteCloser
type WriteCloser interface { Writer Closer } WriteCloser接口聚合了基本的寫入和關閉操作。
type WriteSeeker
type WriteSeeker interface { Writer Seeker } WriteSeeker接口聚合了基本的寫入和移位操作。
type ReadWriter
type ReadWriter interface { Reader Writer } ReadWriter接口聚合了基本的讀寫操作。
type ReadWriteCloser
type ReadWriteCloser interface { Reader Writer Closer } ReadWriteCloser接口聚合了基本的讀寫和關閉操作。
type ReadWriteSeeker
type ReadWriteSeeker interface { Reader Writer Seeker } ReadWriteSeeker接口聚合了基本的讀寫和移位操作。
type ReaderAt
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
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
type ByteReader interface { ReadByte() (c byte, err error)
} ByteReader是基本的ReadByte方法的包裝。
ReadByte讀取輸入中的單個字節并返回。如果沒有字節可讀取，會返回錯誤。
type ByteScanner
type ByteScanner interface { ByteReader UnreadByte() error } ByteScanner接口在基本的ReadByte方法之外還添加了UnreadByte方法。
UnreadByte方法讓下一次調用ReadByte時返回之前調用ReadByte時返回的同一個字節。連續調用兩次UnreadByte方法而中間沒有調用ReadByte時，可能會導致錯誤。
type RuneReader
type RuneReader interface { ReadRune() (r rune, size int, err error)
} RuneReader是基本的ReadRune方法的包裝。
ReadRune讀取單個utf-8編碼的字符，返回該字符和它的字節長度。如果沒有有效的字符，會返回錯誤。
type RuneScanner
type RuneScanner interface { RuneReader UnreadRune() error } RuneScanner接口在基本的ReadRune方法之外還添加了UnreadRune方法。
UnreadRune方法讓下一次調用ReadRune時返回之前調用ReadRune時返回的同一個utf-8字符。連續調用兩次UnreadRune方法而中間沒有調用ReadRune時，可能會導致錯誤。
type ByteWriter
type ByteWriter interface { WriteByte(c byte) error } ByteWriter是基本的WriteByte方法的包裝。
type ReaderFrom
type ReaderFrom interface { ReadFrom(r Reader) (n int64, err error)
} ReaderFrom接口包裝了基本的ReadFrom方法。
ReadFrom方法從r讀取數據直到EOF或者遇到錯誤。返回值n是讀取的字節數，執行時遇到的錯誤（EOF除外）也會被返回。
type WriterTo
type WriterTo interface { WriteTo(w Writer) (n int64, err error)
} WriterTo接口包裝了基本的WriteTo方法。
WriteTo方法將數據寫入w直到沒有數據可以寫入或者遇到錯誤。返回值n是寫入的字節數，執行時遇到的任何錯誤也會被返回。
type LimitedReader
type LimitedReader struct { R Reader // 底層Reader接口 N int64 // 剩余可讀取字節數 } LimitedReader從R中讀取數據，但限制可以讀取的數據的量為最多N字節，每次調用Read方法都會更新N以標記剩余可以讀取的字節數。
func LimitReader
func LimitReader(r Reader, n int64) Reader
返回一個Reader，它從r中讀取n個字節后以EOF停止。返回值接口的底層為*LimitedReader類型。
func (*LimitedReader) Read
func (l *LimitedReader) Read(p []byte) (n int, err error)
type SectionReader
type SectionReader struct { // 內含隱藏或非導出字段 } SectionReader實現了對底層滿足ReadAt接口的輸入流某個片段的Read、ReadAt、Seek方法。
func NewSectionReader
func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader
返回一個從r中的偏移量off處為起始，讀取n個字節后以EOF停止的SectionReader。
func (*SectionReader) Size
func (s *SectionReader) Size() int64
Size返回該片段的字節數。
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)
type PipeReader
type PipeReader struct { // 內含隱藏或非導出字段 } PipeReader是一個管道的讀取端。
func Pipe
func Pipe() (*PipeReader, *PipeWriter)
Pipe創建一個同步的內存中的管道。它可以用于連接期望io.Reader的代碼和期望io.Writer的代碼。一端的讀取對應另一端的寫入，直接在兩端拷貝數據，沒有內部緩沖。可以安全的并行調用Read和Write或者Read/Write與Close方法。Close方法會在最后一次阻塞中的I /O操作結束后完成。并行調用Read或并行調用Write也是安全的：每一個獨立的調用會依次進行。
func (*PipeReader) Read
func (r *PipeReader) Read(data []byte) (n int, err error)
Read實現了標準Reader接口：它從管道中讀取數據，會阻塞直到寫入端開始寫入或寫入端被關閉。
func (*PipeReader) Close
func (r *PipeReader) Close() error
Close關閉讀取器；關閉后如果對管道的寫入端進行寫入操作，就會返回(0, ErrClosedPip)。
func (*PipeReader) CloseWithError
func (r *PipeReader) CloseWithError(err error) error
CloseWithError類似Close方法，但將調用Write時返回的錯誤改為err。
type PipeWriter
type PipeWriter struct { // 內含隱藏或非導出字段 } PipeWriter是一個管道的寫入端。
func (*PipeWriter) Write
func (w *PipeWriter) Write(data []byte) (n int, err error)
Write實現了標準Writer接口：它將數據寫入到管道中，會阻塞直到讀取器讀完所有的數據或讀取端被關閉。
func (*PipeWriter) Close
func (w *PipeWriter) Close() error
Close關閉寫入器；關閉后如果對管道的讀取端進行讀取操作，就會返回(0, EOF)。
func (*PipeWriter) CloseWithError
func (w *PipeWriter) CloseWithError(err error) error
CloseWithError類似Close方法，但將調用Read時返回的錯誤改為err。
func TeeReader
func TeeReader(r Reader, w Writer) Reader
TeeReader返回一個將其從r讀取的數據寫入w的Reader接口。所有通過該接口對r的讀取都會執行對應的對w的寫入。沒有內部的緩沖：寫入必須在讀取完成前完成。寫入時遇到的任何錯誤都會作為讀取錯誤返回。
func MultiReader
func MultiReader(readers ...Reader) Reader
MultiReader返回一個將提供的Reader在邏輯上串聯起來的Reader接口。他們依次被讀取。當所有的輸入流都讀取完畢，Read才會返回EOF。如果readers中任一個返回了非nil非EOF的錯誤，Read方法會返回該錯誤。
func MultiWriter
func MultiWriter(writers ...Writer) Writer
MultiWriter創建一個Writer接口，會將提供給其的數據寫入所有創建時提供的Writer接口。
func Copy
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
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
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
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
func WriteString(w Writer, s string) (n int, err error)
WriteString函數將字符串s的內容寫入w中。如果w已經實現了WriteString方法，函數會直接調用該方法。