Don’t forget, the fourth parameter to ReadFile and WriteFile is sometimes mandatory

Raymond Chen

April 4th, 20130 0

The Read­FileandWrite­Filefunctions have a parameter calledlp­Number­Of­Byte­Read,which is documented as

  __out_opt LPDWORD lpNumberOfBytesRead,
// or
  __out_opt LPDWORD lpNumberOfBytesWritten,

“Cool,” you think.“That parameter is optional, and I can safely pass NULL.”

My program runs fine if standard output is a console,but if I redirect standard output, then it crasheson the Write­File call.I verified that the handle is valid.

int __cdecl main(int, char **)
{
  // error checking removed for expository purposes
  HANDLE hStdOut = GetStdHandle(STD_OUTPUT_HANDLE);
  WriteFile(hStdOut, “hello”, 5, NULL, NULL);
  return 0;
}

The crash occurs inside the Write­File functiontrying to write to a null pointer.

But you need to read further in the documentation forWrite­File:

lp­Number­Of­Bytes­Written [out, optional]

A pointer to the variable that receives the number of bytes written when using a synchronous hFile parameter. Write­File sets this value to zero before doing any work or error checking. Use NULL for this parameter if this is an asynchronous operation to avoid potentially erroneous results.

This parameter can be NULL only when the lp­Over­lapped parameter is not NULL.

That second paragraph is the catch:The parameter is sometimes optional and sometimes mandatory.The annotation language used in the function head is notexpressive enough to say,“Sometimes optional, sometimes mandatory,”so it chooses the weakest annotation (“optional”)so as not to generate false positives when run throughstatic code analysis tools.

With the benefit of hindsight, the functions probably should havebeen split into pairs, one for use with an OVERLAPPEDstructure and one without.That way, one version of the function would have a mandatorylp­Number­Of­Bytes­Writtenparameter and nolp­Over­lapped parameter at all;the other would have a mandatorylp­Over­lapped parameter and nolp­Number­Of­Bytes­Writtenparameter at all.

The crash trying to write to a null pointer is consistent with theremark in the documentation thatthelp­Number­Of­Bytes­Writtenis set to zero before any work is performed.As for why the code runs okay if output is not redirected:Appearing to succeed is a valid form of undefined behavior.It appears that when the output handle is a console,the rule aboutlp­Number­Of­Bytes­Writtenis not consistently enforced.

At least for now.

Raymond Chen