ReadFile 函式 （fileapi.h）

從指定的檔案或輸入/輸出 （I/O） 裝置讀取數據。 如果裝置支援，讀取會發生在檔案指標所指定的位置。

此函式是針對同步和異步操作所設計。 如需專為異步操作而設計的類似函式，請參閱 ReadFileEx。

語法

BOOL ReadFile(
  [in]                HANDLE       hFile,
  [out]               LPVOID       lpBuffer,
  [in]                DWORD        nNumberOfBytesToRead,
  [out, optional]     LPDWORD      lpNumberOfBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

參數

[in] hFile

裝置的句柄（例如檔案、檔案數據流、實體磁碟、磁碟區、控制台緩衝區、磁帶機、套接字、通訊資源、mailslot 或管道）。

hFile 參數必須已使用讀取許可權建立。 如需詳細資訊，請參閱 一般存取權限 和 檔案安全性和存取權限。

針對異步讀取作業，hFile 可以是由 CreateFile 函式以 FILE_FLAG_OVERLAPPED 旗標開啟的任何句柄，或是由 套接字 或 接受 函式所傳回的套接字句柄。

[out] lpBuffer

接收從檔案或裝置讀取之數據的緩衝區指標。

此緩衝區在讀取作業期間必須保持有效。 呼叫端在讀取作業完成之前，不得使用此緩衝區。

[in] nNumberOfBytesToRead

要讀取的位元組數目上限。

[out, optional] lpNumberOfBytesRead

使用同步 hFile 參數時，接收讀取位元組數目的變數指標。 ReadFile 將此值設定為零，再執行任何工作或錯誤檢查。 如果這是異步操作，請針對此參數使用 NULL，以避免潛在的錯誤結果。

只有當 lpOverlapped 參數未 NULL時，這個參數才能 NULL。

Windows 7： 此參數不能 NULL。

如需詳細資訊，請參閱一節。

[in, out, optional] lpOverlapped

如果已使用 FILE_FLAG_OVERLAPPED開啟 hFile 參數，則需要 重疊 結構的指標，否則它可以 NULL。

如果 hFile 是以 FILE_FLAG_OVERLAPPED開啟，則 lpOverlapped 參數必須指向有效且 唯一的重疊 結構，否則函式可能會錯誤地報告讀取作業已完成。

對於支援位元組位移的 hFile，如果您使用此參數，您必須指定位元移，才能開始從檔案或裝置讀取。 此位移是藉由設定 OFFSET 和 OffsetHigh 重疊 結構的成員來指定。 對於不支援位元組位移的 hFile，會忽略 Offset 和 OffsetHigh。

如需 lpOverlapped 和 FILE_FLAG_OVERLAPPED之不同組合的詳細資訊，請參閱一節和 同步處理和檔案位置 一節。

傳回值

如果函式成功，則傳回值為非零值（TRUE）。

如果函式失敗或以異步方式完成，則傳回值為零（FALSE）。 若要取得擴充的錯誤資訊，請呼叫 getLastError 函式 。

注意

  GetLastError 程式代碼 ERROR_IO_PENDING 不是失敗;它會指定讀取作業以異步方式暫止完成。 如需詳細資訊，請參閱。

言論

ReadFile 函式會在發生下列其中一個情況時傳回：

• 已讀取要求的位元組數目。
• 寫入作業在管道的寫入端完成。
• 正在使用異步句柄，而且讀取是以異步方式發生。
• 發生錯誤。

每當有太多未處理的異步 I/O 要求時，ReadFile 函式可能會 ERROR_INVALID_USER_BUFFER 失敗，或 ERROR_NOT_ENOUGH_MEMORY。

若要取消所有暫止的異步 I/O 作業，請使用下列其中一項：

• CancelIo：此函式只會取消呼叫線程針對指定之檔句柄發出的作業。
• CancelIoEx：此函式會取消指定之檔句柄之線程發出的所有作業。

使用 CancelSynchronousIo 來取消暫止的同步 I/O 作業。

取消的 I/O 作業已完成，錯誤 ERROR_OPERATION_ABORTED。

ReadFile 函式可能會因為 ERROR_NOT_ENOUGH_QUOTA而失敗，這表示呼叫進程的緩衝區無法鎖定頁面。 如需詳細資訊，請參閱 SetProcessWorkingSetSize。

如果檔案的一部分被另一個進程鎖定，而讀取作業與鎖定的部分重疊，則此函式會失敗。

當讀取作業使用緩衝區時存取輸入緩衝區，可能會導致讀取到該緩衝區的數據損毀。 應用程式不得讀取、寫入、重新配置或釋放讀取作業所使用的輸入緩衝區，直到讀取作業完成為止。 使用異步檔句柄時，這可能會特別有問題。 如需同步處理與異步檔句柄的其他資訊，請參閱 Synchronization and File Position 一節和 CreateFile 參考主題。

您可以使用 ReadFile 主控台輸入句柄，從控制台輸入緩衝區讀取字元。 控制台模式會決定 readFile 函式 的確切行為。 根據預設，主控台模式為 ENABLE_LINE_INPUT，表示 ReadFile 應該讀取，直到到達歸位字元為止。 如果您按 Ctrl+C，呼叫會成功，但 GetLastError 會傳回 ERROR_OPERATION_ABORTED。 如需詳細資訊，請參閱 CreateFile。

從通訊裝置讀取時，ReadFile 的行為取決於目前通訊逾時設定，並使用 SetCommTimeouts 和 GetCommTimeouts 函式來擷取。 如果您無法設定逾時值，可能會產生無法預測的結果。 如需通訊逾時的詳細資訊，請參閱 COMMTIMEOUTS。

如果 ReadFile 嘗試從緩衝區太小的郵件集讀取，則函式會傳回 FALSE，GetLastError 會傳回 ERROR_INSUFFICIENT_BUFFER。

使用 FILE_FLAG_NO_BUFFERING 旗標，使用 CreateFile 開啟的檔案時，有嚴格的需求。 如需詳細資訊，請參閱 檔案緩衝處理。

如果 hFile 以 FILE_FLAG_OVERLAPPED開啟，下列條件會生效：

• lpOverlapped 參數必須指向有效且唯一 重疊 結構，否則函式可能會錯誤地報告讀取作業已完成。
• lpNumberOfBytesRead 參數應設定為 NULL。 使用 GetOverlappedResult 函式來取得讀取的實際位元組數目。 如果 hFile 參數與 I/O 完成埠相關聯，您也可以呼叫 getQueuedCompletionStatus 函式來取得讀取的位元組數目。

同步處理和檔案位置

如果 hFile 是以 FILE_FLAG_OVERLAPPED開啟，則為異步檔句柄;否則為同步。 如先前所述，使用 重疊 結構的規則會稍有不同。

注意

 如果檔案或裝置已針對異步 I/O 開啟，則後續呼叫函式，例如，使用該句柄 ReadFile 通常會立即傳回，但也可以針對封鎖的執行以同步方式運作。 如需詳細資訊，請參閱 異步磁碟 I/O 在 Windows上顯示為同步。

使用異步檔句柄的考慮：

• ReadFile 可能會在讀取作業完成之前傳回。 在此案例中，ReadFile 會傳回 FALSE，而 getLastError 函式 會傳回 ERROR_IO_PENDING，這可讓呼叫進程在系統完成讀取作業時繼續。
• lpOverlapped 參數不能 NULL，而且應該與下列事實搭配使用：
  • 雖然系統會自動設定和重設 重疊 結構中指定的事件，但不會自動更新重疊 結構 中所指定的位移。
  • ReadFile 開始 I/O 作業時，將事件重設為非對齊狀態。
  • 重疊 結構中指定的事件會在讀取作業完成時設定為訊號狀態;在那段時間之前，讀取作業會被視為擱置中。
  • 因為讀取作業會從 OVERLAPPED 結構中指定的位移開始，而且 ReadFile 可能會在系統層級讀取作業完成之前傳回 （讀取擱置），因此，在發出事件訊號之前，應用程式不應修改、釋放或重複使用結構的任何其他部分位移（亦即 讀取完成。
  • 如果在異步操作期間偵測到檔案尾（EOF），則針對該作業 GetOverlappedResult 呼叫會傳回 FALSE，GetLastError 會傳回 ERROR_HANDLE_EOF。

使用同步檔案句柄的考慮：

• 如果 lpOverlappedNULL，則讀取作業會從目前的檔案位置開始，ReadFile 在作業完成前不會傳回，而且系統會在 ReadFile 傳回之前更新檔案指標。
• 如果 lpOverlapped 不是 NULL，讀取作業會從 重疊 結構中指定的位移開始，而且讀取作業 ReadFile 在讀取作業完成前才會傳回。 系統會在 ReadFi le 傳回之前，更新重疊 位移和檔案指標 重疊。
• 如果 lpOverlappedNULL，則當同步讀取作業到達檔案結尾時，ReadFile 會傳 回 TRUE，並將 *lpNumberOfBytesRead 設定為零。
• 如果 lpOverlapped 未 NULL，則當同步讀取作業到達檔案結尾時，ReadFile 會傳回 FALSE，GetLastError 傳 回 ERROR_HANDLE_EOF。

如需詳細資訊，請參閱 CreateFile 和 同步和異步 I/O。

管道

如果使用匿名管道且寫入句柄已關閉，當 readFile 嘗試使用管道的對應讀取句柄讀取時，函式會傳回 false ，GetLastError 傳回 ERROR_BROKEN_PIPE。

如果在訊息模式中讀取命名管道，且下一個訊息的時間超過 nNumberOfBytesToRead 參數所指定的 ，ReadFile 會傳回 FALSE，GetLastError 會傳回 ERROR_MORE_DATA。 後續呼叫 readFile 或 PeekNamedPipe 函式，即可讀取訊息的其餘部分。

如果 lpNumberOfBytesRead 參數為零時，ReadFile 在管道上傳回 true TRUE，則管線的另一端會呼叫 WriteFile函式，並將 nNumberOfBytesToWrite 設為零。

如需管道的詳細資訊，請參閱 管道。

交易作業

如果有系結至檔句柄的交易，則函式會從檔案的交易檢視傳回數據。 交易讀取句柄保證會在句柄期間顯示檔案的相同檢視。 如需詳細資訊，請參閱 關於交易式NTFS。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。

科技	支援
伺服器消息塊 （SMB） 3.0 通訊協定	是的
SMB 3.0 透明故障轉移 （TFO）	是的
具有向外延展檔案共用的SMB 3.0（SO）	是的
叢集共用磁碟區檔案系統 （CsvFS）	是的
復原檔案系統 （ReFS）	是的

例子

如需示範如何測試檔尾的程式碼範例，請參閱 測試檔案尾。 如需其他範例，請參閱 建立和使用暫存盤 和 開啟檔案以讀取或寫入。

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 |UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平臺	窗戶
標頭	fileapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

檔案管理功能

GetCommTimeouts

GetOverlappedResult

GetQueuedCompletionStatus

重疊

PeekNamedPipe

ReadFileEx

SetCommTimeouts

SetErrorMode

WriteFile