AllocConsoleWithOptions function

Optionally allocates a new console for the calling process, while allowing you to specify the visibility of the new console window.

Syntax

HRESULT WINAPI AllocConsoleWithOptions(
    _In_opt_  PALLOC_CONSOLE_OPTIONS allocOptions,
    _Out_opt_ PALLOC_CONSOLE_RESULT  result
);

Parameters

allocOptions [in, optional] A ALLOC_CONSOLE_OPTIONS structure that controls how this function allocates a window.

result [out, optional] Receives one of the following values:

Value	Meaning
ALLOC_CONSOLE_RESULT_NO_CONSOLE 0	No console was created, because ALLOC_CONSOLE_MODE_DEFAULT was used and the parent process asked for none to be created.
ALLOC_CONSOLE_RESULT_NEW_CONSOLE 1	A new console session was created as a result of this call. The resulting behavior is identical to AllocConsole.
ALLOC_CONSOLE_RESULT_EXISTING_CONSOLE 2	The process has attached itself to an existing console session, inherited by the parent process. The resulting behavior is identical to AttachConsole.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Unlike with AllocConsole or AttachConsole, calling this method when already connected to a console session does not result in an error. The result parameter will be set to ALLOC_CONSOLE_RESULT_EXISTING_CONSOLE in that case.

A process can use the FreeConsole function to detach itself from its current console. A console is closed when the last process attached to it terminates or calls FreeConsole.

Requirements

Minimum supported client	Windows 11 24H2 (build 26100) [desktop apps only]
Minimum supported server	Windows Server 2025 (build 26100)
Header	ConsoleApi.h (via WinCon.h, include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

See also

Console Functions

Consoles

Console Allocation Policy

AllocConsole

AttachConsole

FreeConsole