| title | AllocConsoleWithOptions function | |||
|---|---|---|---|---|
| description | See reference information about the AllocConsoleWithOptions function, which allocates a new console for the calling process. | |||
| author | lhecker | |||
| ms.author | lhecker | |||
| ms.topic | article | |||
| keywords | console, character mode applications, command line applications, terminal applications, console api, conpty, pseudoconsole | |||
| topic_type |
|
|||
| api_name |
|
|||
| api_location |
|
|||
| api_type |
|
Optionally allocates a new console for the calling process, while allowing you to specify the visibility of the new console window.
HRESULT WINAPI AllocConsoleWithOptions(
_In_opt_ PALLOC_CONSOLE_OPTIONS allocOptions,
_Out_opt_ PALLOC_CONSOLE_RESULT result
);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. |
Type: HRESULT
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
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.
| 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 |