GetStdHandle 함수

아티클
07/12/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$` 활성 콘솔 화면 버퍼입니다.

참고 항목

이러한 상수의 값은 부호 없는 숫자이지만 헤더 파일에는 부호 있는 숫자의 캐스트로 정의되며, 최대 32비트 값 바로 아래에 롤오버되는 C 컴파일러를 활용합니다. 헤더를 구문 분석하지 않고 상수를 재정의하는 언어에서 이러한 핸들과 인터페이스할 때 이 제약 조건에 유의하세요. 예를 들어 ((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이거나 콘솔 의사 핸들이 아니면 표준 핸들이 바뀌지 않습니다.

참고 항목

콘솔 프로세스는 채워진 표준 핸들로 시작해야 합니다. 그렇지 않으면 새 콘솔에 적합한 핸들로 자동으로 채워집니다. GUI(그래픽 사용자 인터페이스) 애플리케이션은 표준 핸들 없이 시작할 수 있으며 자동으로 채워지지 않습니다.

예제

예제는 입력 버퍼 이벤트 읽기를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
헤더	ProcessEnv.h(Winbase.h를 통해, Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll