by Michael S. Kaplan, published on 2009/08/14 10:01 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2009/08/14/9869928.aspx
There was a recent [internal] discussion thread where someone was asking about what was the best way to output localized text to the console.
After a bit of thread drift, STL pointed out that blog post (Conventional wisdom is retarded, aka What the @#%&* is _O_U16TEXT?) which explains how to fix the bulk of the problems one sees with wprintf and such.
Not that it did much good initially, since the conclusion reached:
Thanks.
Why not using WriteFile always and drop WriteConsole? Unicode string may be converted to ASCII one before calling WriteFile. The code is simpler and the output is uniform – both, string in file and one copied from console, are ASCII. Otherwise, console string is ASCII, but file contains Unicode.
clearly suggests that the topic was not read to the bottom! :-)
It's okay, he was set straight very quickly, so no worries there. Given how unlikely I am to read a email from a VP all the way to the end, I can't expect people to read a blog post of mine to the end; they have staffs and get paid a helluva lot more money for what they wrote and even spell-checked it!
Anyway, one thing that was mentioned even further in the thread, after someone complained about the documentation being inadequate (a problem I talked some too, in the original blog and Before you say "What's next?" you have to figure out the action items), was that all of the correct info was sitting in the header file (fcntl.h):
/* O_TEXT files have <cr><lf> sequences translated to <lf> on read()'s,
** and <lf> sequences translated to <cr><lf> on write()'s
*/
#define _O_TEXT 0x4000 /* file mode is text (translated) */
#define _O_BINARY 0x8000 /* file mode is binary (untranslated) */
#define _O_WTEXT 0x10000 /* file mode is UTF16 (translated) */
#define _O_U16TEXT 0x20000 /* file mode is UTF16 no BOM (translated) */
#define _O_U8TEXT 0x40000 /* file mode is UTF8 no BOM (translated) */
So this explains the difference between the various _O_*TEXT defines much more concisely than the documentation does! :-)
Now yes blog posts do not add up to official documentation, even when they are more accurate and are cited by technology owners.
And yes header files (especially ones with warnings like the one at the top of fcntl.h!) might not be either in some legal sense.
But remember that when documentation is wrong, the only bad consequence is confusion -- it does not make programs spontaneously fail.
Header files, on the other hand, are intended to represent what the developer was honestly expecting the code to do, and there is an honest chance that a non-comment mistake in a header file will keep something from building -- which means there is a greater chance that the problem might be fixed!
So if you want to know What the @#%&* is _O_WTEXT?, you may want to check the header file first. You might be surprise yourself....