GetStdHandle 函式

發行項
12/13/2023

擷取指定標準裝置的控制代碼 (標準輸入、標準輸出或標準錯誤)。

語法

HANDLE WINAPI GetStdHandle(
  _In_ DWORD nStdHandle
);

參數

nStdHandle [in]
標準裝置。此參數可以是下列其中一個值。

值	意義
STD_INPUT_HANDLE`((DWORD)-10)`	標準輸入裝置。一開始，這是主控台輸入緩衝區 `CONIN$`。
STD_OUTPUT_HANDLE`((DWORD)-11)`	標準輸出裝置。一開始，這是作用中的主控台畫面緩衝區 `CONOUT$`。
STD_ERROR_HANDLE`((DWORD)-12)`	標準錯誤裝置。一開始，這是作用中的主控台畫面緩衝區 `CONOUT$`。

注意

這些常數的值是不帶正負號的數位，但會在頭檔中定義為從帶正負號的數字轉換，並利用 C 編譯程式將這些值變換到最大 32 位值之下。當以不剖析標頭且重新定義常數的語言與這些句柄互動時，請注意此條件約束。例如， ((DWORD)-10) 實際上是不帶正負號的數位 4294967286。

傳回值

如果函式成功，則傳回值是指定裝置的控制代碼，或是先前呼叫 SetStdHandle 時所設定的重新導向控制代碼。句柄具有 GENERIC_READ 和 GENERIC_WRITE 訪問許可權，除非應用程式已使用 SetStdHandle 來設定具有較少存取權的標準句柄。

提示

完成時，不需要使用 CloseHandle 處置此句柄。如需詳細資訊，請參閱。

如果函式失敗，傳回值會 INVALID_HANDLE_VALUE。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果應用程式沒有相關聯的標準控制代碼 (例如在互動式桌面上執行的服務)，而且尚未將其重新導向，則傳回值會是 Null。

備註

GetStdHandle 傳回的控制代碼可供需要讀取或寫入主控台的應用程式使用。建立主控台時，標準輸入控制代碼是主控台輸入緩衝區的控制代碼，而標準輸出和標準錯誤控制代碼則是主控台作用中畫面緩衝區的控制代碼。這些控制代碼可由 ReadFile 和 WriteFile 函式使用，或由任何存取主控台輸入緩衝區或畫面緩衝區的主控台函式使用 (例如 ReadConsoleInput、WriteConsole或 GetConsoleScreenBufferInfo 函式)。

對 SetStdHandle 發出的呼叫可能會將程序的標準控制代碼重新導向，在此情況下，GetStdHandle 會傳回重新導向的控制代碼。如果標準控制代碼已重新導向，您可以在呼叫 CreateFile 函式時指定 CONIN$ 值，以取得主控台輸入緩衝區的控制代碼。同樣地，您可以指定 CONOUT$ 值，以取得主控台作用中畫面緩衝區的控制代碼。

建立應用程式時，傳遞至連結器的 /SUBSYSTEM 旗標設定會決定在 main 方法進入點上的程序標準控制代碼。指定 /SUBSYSTEM:CONSOLE 會要求作業系統在啟動時以主控台工作階段填滿控制代碼 (如果父系尚未透過繼承來填滿標準控制代碼資料表)。相反地，/SUBSYSTEM:WINDOWS 則是表示應用程式不需要主控台，而且很可能不會使用標準控制代碼。如需有關句柄繼承的詳細資訊，請參閱STARTF_USESTDHANDLES檔。

有些應用程式會在其宣告的子系統界限外運作；例如，/SUBSYSTEM:WINDOWS 應用程式可能會檢查/使用標準控制代碼進行記錄或偵錯，但通常會搭配圖形使用者介面運作。這些應用程式必須在啟動時仔細探查標準控制代碼的狀態，並使用 AttachConsole、AllocConsole 和 FreeConsole 來新增/移除主控台 (如有需要)。

某些應用程式也可能會改變其在所繼承控制代碼類型上的行為。若要釐清主控台、管道、檔案和其他類型，可以使用 GetFileType 來執行。

處理處置

當使用從 GetStdHandle 擷取的句柄完成時，就不需要 CloseHandle。傳回的值只是儲存在進程數據表中的值複本。程式本身通常被視為這些句柄及其存留期的擁有者。根據 CreateProcess 呼叫的繼承和啟動特定專案，每個句柄都會放在數據表中，並在進程終結時釋出。

手動操作這些句柄的存留期，對於刻意嘗試取代這些句柄或封鎖進程的其他部分，可能會想要使用這些句柄。 HANDLE透過執行程式代碼可以快取，該程式代碼不一定會透過SetStdHandle 挑選所做的變更。透過 CloseHandle 明確關閉句柄將會關閉整個進程，而任何快取參考的下一個使用方式將會發生錯誤。

取代進程數據表中標準句柄的指引是使用 GetStdHandle 從數據表取得現有HANDLE句柄，使用 SetStdHandle 將新的 HANDLE 放在以 CreateFile 開啟的新中（或類似的函式），然後關閉擷取的句柄。

GetStdHandle 或 SetStdHandle 函式不會驗證儲存為進程數據表中句柄的值。驗證會在實際讀取/寫入作業時執行，例如 ReadFile 或 WriteFile。

連結/卸離行為

附加至新的控制台時，除非在程式建立期間指定STARTF_USESTDHANDLES，否則標準句柄一律會取代為控制台句柄。

如果標準控制代碼的現有值為 Null，或標準控制代碼的現有值看起來像主控台 pseudohandle，則控制代碼會取代為主控台控制代碼。

當父代同時使用CREATE_NEW_CONSOLE和STARTF_USESTDHANDLES來建立控制台進程時，除非標準句柄的現有值為 NULL 或控制台虛擬手法，否則不會取代標準句柄。

注意

主控台程序「必須」從填滿標準控制代碼開始，否則新的主控台會自動以適當的控制代碼填入。圖形使用者介面 (GUI) 應用程式可以在沒有標準控制代碼的情況下啟動，而且不會自動填入。

範例

如需範例，請參閱讀取輸入緩衝區事件。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
頁首	ProcessEnv.h (透過 Winbase.h，包括 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll