One of the common misconceptions surrounding Win32 programming is that you must decide early in the design process whether your application will be a console or GUI application. In reality, console applications can create windows and have a message loop just like a GUI application (see "Adding Graphics to Console Applications" by Michael Covington, Visual Developer, June/July 1997). Alternatively, graphical applications can create and use a console. Although Win32 provides functions for communicating with a console, they are a little clumsy to use and require parameters that are unnecessary for simple text I/O. This article shows how to use standard C/C++ I/O with consoles, and how to work around specific problems in the Visual C++ I/O library.

The standard C I/O package operates on top of whatever I/O services the local operating system provides. Your C program then manipulates handles of type FILE*, no matter what the actual details of the physical file I/O are. The file I/O package that Win32 provides uses handles of type HANDLE, so Win32 C implementations of the standard I/O functions must internally associate a HANDLE with each FILE*, and eventually call the Win32 API to perform the I/O.

C predefines the meaning of three handles: stdin, stdout, and stderr. These names refer to FILE* handles that refer to standard input, output, and error output. Win32 provides a similar concept; it provides a function called GetStdHandle(), and you can pass that function one of three constants (STD_INPUT_HANDLE, STD_OUTPUT_HANDLE, or STD_ERROR_HANDLE) to obtain the HANDLE associated with standard input, standard output, or the standard error output. Exactly what these handles refer to depends on how your Win32 program was built and marked. These handles could be redirected to files, or they could be associated with a console window. If you launch a program from a DOS box (which is basically a console window), it may end up using that DOS box as its console window by default (that is, writing to standard output produces output in the DOS box window).

Win32 GUI applications do not, by default, have an associated console window. However, it is possible for your GUI application to explicitly create a console window and then manually associate standard C I/O handles (FILE*) with the appropriate Win32 handles (HANDLE) so that ordinary C runtime functions can operate on the console. To associate a C file handle with a Win32 file handle, the Visual C++ runtime library provides _open_osfhandle(). Given a valid Win32 handle, this function returns an RTL handle that internally operates on the given Win32 handle. This lets you transform the three console handles into compatible C file handles that you can use to redirect stdin, stdout, and stderr to the console.

Once stdin, stdout, and stderr are redirected, standard C functions such as printf() and gets() can be used, without change, to communicate with the Win32 console. But what about C++ I/O streams? Since cin, cout, cerr, and clog are closely tied to C’s stdin, stdout, and stderr, you would expect them to behave similarly. This is half right.

C++ I/O streams actually come in two flavors: template and non- template. The older non-template version of I/O streams is slowly being replaced by a newer template style of streams first defined by the Standard Template Library (STL) and which are now being absorbed into the ANSI C++ standard. Visual C++ v5 provides both types and allows you to choose between the two by including different header files. STL I/O streams work as you would expect, automatically using any newly redirected stdio handles. Non-template I/O streams, however, do not work as expected. To discover why, I looked at the source code, conveniently provided on the Visual C++ CD-ROM.

The problem is that the older I/O streams were designed to use UNIX-style "file descriptors," where integers are used instead of handles (0 for stdin, 1 for stdout, and so on). That’s convenient for UNIX implementations, but Win32 C compilers have to provide yet another I/O layer to represent that style of I/O, since Win32 does not provide a compatible set of functions. In any case, when you call _open_osfhandle() to associate a new Win32 handle with (for example) stdout, it has no effect on the other layer of I/O code. Hence, file descriptor 1 will continue using the same underlying Win32 handle as before, and sending output to cout will not produce the desired effect.

Fortunately, the designers of the original I/O stream package foresaw this problem and provided a clean and useful solution. The base class ios provides a static function, sync_with_stdio(), that causes the library to change its underlying file descriptors to reflect any changes in the standard I/O layer. Though this is not strictly necessary for STL I/O streams, it does no harm and lets me write code that works correctly with either the new or old form of I/O streams.

guicon.cpp (Listing 1) and guicon.h (Listing 2) provide code for redirecting C and C++ I/O to a Win32 console. RedirectIOToConsole() does all the work, creating a console and increasing the number of lines buffered with calls to AllocConsole() and SetConsoleScreenBufferSize() respectively. Each process is allowed only one console, so calling AllocConsole() multiple times will not produce multiple consoles. Increasing the screen buffer size allows you to scroll back and look at a history of up to MAX_CONSOLE_LINES of text. The code then creates a new FILE* handle for STD_INPUT_HANDLE, STD_OUTPUT_HANDLE, and STD_ERROR_HANDLE, and the existing stdin, stdout, and stderr are replaced. setvbuf() is then called to turn off input and output buffering, effectively flushing the data with each read and write. Last, but not least, a call to ios::sync_with_stdio() ensures that cin, cout, cerr, and clog are associated with the new stdin, stdout, and stderr. The code is wrapped in preprocessor conditionals to allow it to be easily compiled out for release applications.

The code in test.cpp (Listing 3) is a sample of using RedirectIOToConsole(). It outputs text using the C stdio and C++ I/O streams and uses a simple integer to test input. Additionally, if you are using STL streams it tests the wide character versions of cin, cout, cerr, and clog. The rest of the code demonstrates how the Visual C++ C runtime debug functions can be used to output useful debugging information to the console. Since Win32 destroys the console when the application exits, I pause for two seconds before exiting so that you can see the last few pieces of output.

Overall, having a console associated with a Win32 GUI application is a very useful tool. Though similar debug text output can be achieved using Win32’s OutputDebugString() and DBWin32 (see "A DBWin32 Debugger for Windows" by Andrew Tucker, C/C++ Users Journal, October 1996), this console technique is much more portable between the Win32 API flavors (namely Windows 95 and NT) and it provides a method of input as well as output. Another application might be to use the console as a simple debugger that allows you to print out crucial data structures and inspect and change variables without the use of a full-blown interactive debugger. Finally, for those applications whose user interface makes sense as both a console app and a GUI, a command-line switch could allow the user to choose which is appropriate for their situation — something that is not as readily available when using a GUI from a console application.

Covington, Michael. "Adding Graphics to Console Applications," Visual Developer, June/July 1997.

Tucker, Andrew. "A DBWin32 Debugger for Windows," C/C++ Users Journal, October 1996.

Andrew Tucker (ast@halcyon.com) is a software engineer in Seatte, WA. His programming interests include compilers, debuggers, and other areas of systems programming.