Sorting it all Out

Actually, in this case it sounds like a bug.

The doc says "Return Value ... , if nBuff is zero, the return value is the size, in array elements, of the buffer needed to receive all current input locale identifiers."

That is the contract.

No matter what the value of the second parameter is, it will return the needed size.

Otherwise the doc should say "if nBuff is zero and lpList is NULL, ..."

http://msdn.microsoft.com/en-us/library/ms646297%28VS.85%29.aspx

It also does not break any "Raymond rule."

A rule is "All buffers are valid to the size declared or implied"; and in this case the declared size is zero, so the function should not try to touch anything in the buffer.

The linked article also says "Pointers are not NULL unless explicitly permitted otherwise." - if you're supposed to be passing in NULL, then the documentation should mention _that_, and it's still a bug that it doesn't.

As the documentation stands there is no reason to think a null pointer is a better choice than an uninitialized pointer. After all, if it's dereferencing an uninitialized pointer today, who says it won't dereference a null pointer tomorrow? Which leaves the only option to be _allocating memory twice_.

If you think about how this works, you can see why Microsoft needs the pointer to be null if the count is zero.

This is a 30+ year old C convention, Microsoft doesn't need to document it in each individual function call.  Either a pointer points towards what it is supposed to, or the pointer is null.  Casts are there because there are times where someone who knows what they are doing needs to treat one type as another -- they are not there to make the compiler "shut up."

Now, for 16 to 32 and for 32 to 64, Microsoft has a set of wrapper libraries.  These either invoke the kernel, or they invoke the newer API.  I believe the latter is much more common than the former.

Microsoft has a tool, it reads a header file, and for each structure it writes a marshaller.  For each function, it invokes the marshaller (MarshalTo64 or w/e), then invokes the native function, then invokes the marshaller again (MarshalTo32).

Because there are millions of functions, Microsoft isn't going to convert each one by hand.  They have a tool, it writes all these stubs.  The tool, out of necessity, doesn't know anything about which parameters are used in which cases -- it assumes that the pointer is either valid or null.

It has to, otherwise you'd have to be able to express all the pre and post conditions for every combination of variables using #defines, etc., and the header would expand exponentially.

This is, however, why newer APIs are being factored to use cursor/iterator against OS-owned memory, or COM.