WriteConsole 함수

아티클
07/12/2023

현재 커서 위치에서 시작하는 콘솔 화면 버퍼에 문자열을 씁니다.

구문

BOOL WINAPI WriteConsole(
  _In_             HANDLE  hConsoleOutput,
  _In_       const VOID    *lpBuffer,
  _In_             DWORD   nNumberOfCharsToWrite,
  _Out_opt_        LPDWORD lpNumberOfCharsWritten,
  _Reserved_       LPVOID  lpReserved
);

매개 변수

hConsoleOutput [in]
콘솔 화면 버퍼에 대한 핸들입니다. 핸들에는 GENERIC_WRITE 액세스 권한이 있어야 합니다. 자세한 내용은 콘솔 버퍼 보안 및 액세스 권한을 참조하세요.

lpBuffer [in]
콘솔 화면 버퍼에 쓸 문자가 포함된 버퍼에 대한 포인터입니다. WriteConsoleA의 경우 char 배열이거나 WriteConsoleW의 경우 wchar_t 배열이어야 합니다.

nNumberOfCharsToWrite [in]
쓸 문자 수입니다. 지정된 문자 수의 총 크기가 사용 가능한 힙을 초과하면 ERROR_NOT_ENOUGH_MEMORY와 함께 함수가 실패합니다.

lpNumberOfCharsWritten [out, optional]
실제로 쓰인 문자 수를 받는 변수에 대한 포인터입니다.

lpReserved는 예약되어 있으며, NULL이어야 합니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

WriteConsole 함수는 현재 커서 위치의 콘솔 화면 버퍼에 문자를 씁니다. 문자를 쓰면 커서 위치가 이동합니다. Console SetConsoleCursorPosition 함수는 현재 커서 위치를 설정합니다.

문자는 콘솔 화면 버퍼와 연결된 전경 및 배경색 특성을 사용하여 쓰입니다. SetConsoleTextAttribute 함수는 이러한 색을 변경합니다. 현재 색 특성 및 현재 커서 위치를 확인하려면 GetConsoleScreenBufferInfo를 사용합니다.

WriteFile 함수의 동작에 영향을 주는 모든 입력 모드는 WriteConsole에도 동일한 영향을 줍니다. 콘솔 화면 버퍼의 출력 모드를 검색하고 설정하려면 GetConsoleMode 및 SetConsoleMode 함수를 사용합니다.

이 함수는 콘솔의 현재 코드 페이지에서 유니코드 문자 또는 8비트 문자를 사용합니다. 콘솔의 코드 페이지는 처음에 기본적으로 시스템의 OEM 코드 페이지로 설정됩니다. 콘솔의 코드 페이지를 변경하려면 SetConsoleCP 또는 SetConsoleOutputCP 함수를 사용합니다. 레거시 소비자는 chcp 또는 mode con cp select= 명령을 사용할 수도 있지만 새로운 개발에는 추천되지 않습니다.

WriteConsole은 파일로 리디렉션되는 표준 핸들과 함께 사용되면 실패합니다. 애플리케이션에서 리디렉션될 수 있는 다국어 출력을 처리하는 경우 출력 핸들이 콘솔 핸들인지 확인합니다(한 가지 방법으로 GetConsoleMode 함수를 호출하여 성공 여부를 확인함). 핸들이 콘솔 핸들인 경우 WriteConsole을 호출합니다. 핸들이 콘솔 핸들이 아닌 경우 출력이 리디렉션되고 WriteFile을 호출하여 I/O를 수행해야 합니다. 바이트 순서 표시를 접두사로 유니코드 일반 텍스트 파일의 앞에 붙여야 합니다. 자세한 내용은 바이트 순서 표시 사용을 참조하세요.

애플리케이션에서 ANSI 모드의 WriteConsole을 사용하여 ANSI 문자를 쓸 수 있지만, 사용하도록 설정된 경우를 제외하고는 콘솔에서 "ANSI 이스케이프" 또는 "가상 터미널" 시퀀스를 지원하지 않습니다. 자세한 내용 및 운영 체제 버전 적용 가능성은 콘솔 가상 터미널 시퀀스를 참조하세요.

가상 터미널 이스케이프 시퀀스를 사용하도록 설정되지 않은 경우 콘솔 함수에서 동등한 기능을 제공할 수 있습니다. 자세한 내용은 SetCursorPos, SetConsoleTextAttribute 및 GetConsoleCursorInfo를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
헤더	ConsoleApi.h(WinCon.h를 통해, Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll
유니코드 및 ANSI 이름	WriteConsoleW(유니코드) 및 WriteConsoleA(ANSI)