Allocates a new console for the calling process.

Syntax

BOOL WINAPI AllocConsole(void);

Parameters

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

A process can be associated with only one console, so the AllocConsole function fails if the calling process already has a console. A process can use the FreeConsole function to detach itself from its current console, then it can call AllocConsole to create a new console or AttachConsole to attach to another console.

If the calling process creates a child process, the child inherits the new console.

AllocConsole initializes standard input, standard output, and standard error handles for the new console. The standard input handle is a handle to the console's input buffer, and the standard output and standard error handles are handles to the console's screen buffer. To retrieve these handles, use the GetStdHandle function.

This function is primarily used by graphical user interface (GUI) application to create a console window. GUI applications are initialized without a console. Console applications are initialized with a console, unless they are created as detached processes (by calling the CreateProcess function with the DETACHED_PROCESS flag).

Requirements

See Also

Console Functions
Consoles
AttachConsole
CreateProcess
FreeConsole
GetStdHandle

Send comments about this topic to Microsoft

Build date: 8/7/2008