GetStdHandle 関数
指定された標準デバイス (標準入力、標準出力、または標準エラー) のハンドルを取得します。
構文
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$ です。 |
Note
これらの定数の値は符号なし数値で (ただし、ヘッダー ファイルで符号付き数値からのキャストとして定義されます)、C コンパイラを利用して最大 32 ビット値の直下にそれらがロールオーバーされます。 ヘッダーを解析せず、定数を再定義する言語でこれらのハンドルとやり取りするときは、この制約に注意してください。 例として、((DWORD)-10) は実際には、符号なし数値 4294967286 です。
戻り値
関数が成功した場合、戻り値は、指定されたデバイスのハンドル、または以前の SetStdHandle の呼び出しによって設定されたリダイレクト ハンドルです。 このハンドルには、アプリケーションで SetStdHandle を使用してアクセスが少ない標準ハンドルが設定されている場合を除き、GENERIC_READ と GENERIC_WRITE のアクセス権が与えられます。
ヒント
完了したら、CloseHandle を使用してこのハンドルを破棄する必要はありません。 詳細については、「解説」を参照してください。
失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
アプリケーションに関連付けられている標準ハンドル (対話型デスクトップで実行されているサービスなど) がなく、リダイレクトされていない場合、戻り値は NULL になります。
解説
コンソールに対する読み取りまたは書き込みを行う必要があるアプリケーションで、GetStdHandle によって返されるハンドルを使用できます。 コンソール作成時の標準入力ハンドルはコンソールの入力バッファーのハンドル、標準出力ハンドルと標準エラー ハンドルはコンソールのアクティブな画面バッファーのハンドルです。 これらのハンドルを、ReadFile 関数、WriteFile 関数、またはコンソールの入力バッファーまたは画面バッファーにアクセスするコンソール関数 (たとえば、ReadConsoleInput、WriteConsole、GetConsoleScreenBufferInfo などの関数) で使用できます。
SetStdHandle の呼び出しによって、プロセスの標準ハンドルをリダイレクトできます。この場合、GetStdHandle ではリダイレクトされたハンドルが返されます。 標準ハンドルがリダイレクトされている場合は、CreateFile 関数の呼び出しで CONIN$ 値を指定して、コンソールの入力バッファーのハンドルを取得できます。 同様に、CONOUT$ 値を指定して、コンソールのアクティブな画面バッファーのハンドルを取得できます。
main メソッドのエントリに関するプロセスの標準ハンドルは、アプリケーションのビルド時にリンカーに渡される /SUBSYSTEM フラグの構成によって指示されます。 /SUBSYSTEM:CONSOLE を指定すると、親の継承によって標準ハンドル テーブルがまだ設定されていなければ、コンソール セッションの起動時にハンドルを設定することがオペレーティング システムに要求されます。 それに対して、/SUBSYSTEM:WINDOWS は、アプリケーションでコンソールが必要でなく、標準ハンドルを使用しない可能性があることを意味します。 ハンドル継承の詳細については、STARTF_USESTDHANDLES に関するドキュメントを参照してください。
アプリケーションの中には、宣言されたサブシステムの境界の外側で動作するものがあります。たとえば、/SUBSYSTEM:WINDOWS アプリケーションでは、ログまたはデバッグのために標準ハンドルをチェック/使用することがありますが、通常はグラフィカル ユーザー インターフェイスで動作します。 これらのアプリケーションでは、起動時に標準ハンドルの状態を慎重に調べ、必要に応じて AttachConsole、AllocConsole、および FreeConsole を使用してコンソールを追加/削除する必要があります。
継承されたハンドルの種類によって動作が異なるアプリケーションもあります。 GetFileType を使用して、コンソール、パイプ、ファイルなどの種類を明確化できます。
ハンドルの破棄
GetStdHandle から取得したハンドルの使用が完了したとき、CloseHandle する必要はありません。 返される値は、単にプロセス テーブルに格納されている値のコピーです。 プロセス自体は、通常、これらのハンドルとその有効期間の所有者と見なされます。 各ハンドルは CreateProcess 呼び出しの継承と起動の詳細に応じて作成時にテーブルに配置され、プロセスが破棄されると解放されます。
これらのハンドルの有効期間を手動で操作することが、意図的にそれらを置き換えようとしたり、プロセスの他の部分でそれらが使用されるのをブロックしようとするアプリケーションに望ましい場合があります。 HANDLE はコードを実行してキャッシュできるため、そのコードにより必ずしも、SetStdHandle を介して行われた変更が取得されるとは限りません。 CloseHandle を使用してハンドルを明示的に閉じると、プロセス全体でそれが閉じられ、キャッシュされた参照を次に使用するときにエラーが発生します。
プロセス テーブルの標準ハンドルを置き換えるガイダンスとして、GetStdHandle を使用してテーブルから既存の HANDLE を取得し、SetStdHandle を使用して CreateFile (または同様の関数) によって開いた新しい HANDLE に置き換え、取得したハンドルを閉じる方法があります。
GetStdHandle または SetStdHandle 関数のいずれかによって、プロセス テーブルにハンドルとして格納されている値に関する検証は実行されません。 検証は ReadFile や WriteFile などの実際の読み取り/書き込み操作時に実行されます。
アタッチ/デタッチの動作
新しいコンソールにアタッチする場合、プロセスの作成時に STARTF_USESTDHANDLES が指定されていない限り、標準ハンドルは常にコンソール ハンドルに置き換えられます。
標準ハンドルの既存の値が NULL の場合、または標準ハンドルの既存の値がコンソールの擬似ハンドルのように見える場合、ハンドルはコンソール ハンドルに置き換えられます。
親によって CREATE_NEW_CONSOLE と STARTF_USESTDHANDLES の両方が使用されてコンソール プロセスが作成される場合、標準ハンドルの既存の値が NULL またはコンソールの擬似ハンドルである場合を除き、標準ハンドルが置き換えられることはありません。
Note
コンソール プロセスは、標準ハンドルを設定して開始する "必要があります"。または、新しいコンソールに対する適切なハンドルが自動的に設定されます。 グラフィカル ユーザー インターフェイス (GUI) アプリケーションは標準ハンドルなしで起動でき、自動的に設定されることはありません。
例
例については、「入力バッファー イベントの読み取り」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| ヘッダー | ProcessEnv.h (Winbase.h 経由、Windows.h が含まれる) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |