by Michael S. Kaplan, published on 2011/08/29 07:01 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2011/08/29/10201368.aspx
Andrew asked:
Is it a bug in RtlUTF8ToUnicodeN, or a doc bug in MSDN? Thanks.
User Mode Codes:
WCHAR wsUtf16[100];
ULONG cwUtf16Written;
CHAR chTest1 = 'A';
CHAR chTest2[] = {'A','B'};
status = RtlUTF8ToUnicodeN(wsUtf16,
ARRAYSIZE(wsUtf16),
&cwUtf16Written,
&chTest1,
sizeof(chTest1));
printf("cwUtf16Written = %d\n", cwUtf16Written);
status = RtlUTF8ToUnicodeN(wsUtf16,
ARRAYSIZE(wsUtf16),
&cwUtf16Written,
chTest2,
sizeof(chTest2));
printf("cwUtf16Written = %d\n", cwUtf16Written);
Output:
cwUtf16Written = 2
cwUtf16Written = 4
MSDN:
NTSTATUS WINAPI RtlUTF8ToUnicodeN(
__out PWSTR UnicodeStringDestination,
__in ULONG UnicodeStringMaxWCharCount,
__out_opt PULONG UnicodeStringActualWCharCount,
__in PCCH UTF8StringSource,
__in ULONG UTF8StringByteCount
);
http://msdn.microsoft.com/en-us/library/ee453688(VS.85).aspx
Regards,
Andrew
Now of course that link is just one of those relevant to this function.
The two links are:
As this would hint at, there are a potentially huge number of callers of this function, all of whom would be broken if the buffer size variable meaning was changed.
Therefore, whether this was ever in the noble history of RtlUTF8ToUnicodeN considered a bug in the function, it is officially now just a doc bug.
Bugs like this that exist in different doc libraries (despite actually being in just one part of the source tree, albeit a part compiled many different times), and up being complicated to keep in sync.
The vast differences in the two doc topics help indicate that -- and suggest that there may even be a better way to keep them in sync.
I mean, it wouldn't have helped with this bug, but....
cheong00 on 29 Aug 2011 7:58 PM:
At some point, maybe Microsoft documentation team who manages these docs will consider it worthwhile to create webparts that reads from a web services. That web service can locate and parse a specified header location to fetch the information out. (may need help from the compiler teams to do so)
Note: I'm in the mood of over-engineering problems. :P
Michael S. Kaplan on 30 Aug 2011 8:16 AM:
Assumes lots of facts not in evidence, since:
The net effect would be a serious impoverishing of the docs.
Can we really call it "overengineering" if the net effect is underperformance? :-)
cheong00 on 30 Aug 2011 6:32 PM:
I don't know... perheps if the header files contains XML comment that's written by function creators, it'd be able to add a nice side-reference to the documentation. The current MSDN documentation could be described as a reparsed interpretation of that the developer involved said, and that reinterpretation may not be accurate enough in some case.
Before anyone saying the header files are included in Visual Studio anyway, I'll be the first to admit that since I don't know how to write C++, nor there's requirement for me to write in that in my job, I seldom required to install full version of VS in my job machine. Usually only C# or VB.NET part is installed.
Regarding there are many teams, since the doc writers need to gather the information from the teams anyway, I should require much additional effort to fetch a copy of current header files for them.
Yuhong Bao on 31 Aug 2011 1:05 PM:
I think the real question is why there are redundant documentation for the same function in ntoskrnl and ntdll?
Yuhong Bao on 24 Jan 2012 4:34 PM:
In fact, look at the end of this comment thread: