One thing that struck me when I first encountered the 4.3BSD Unix system call documentation in the 1980s, was that each call was followed by an exhaustive list of the errors associated with it. Ten years later, when I was going through the Windows API, I was disappointed to see that very few functions documented their error conditions. This is a big deal.
Consider as an example how the open function can fail. The 4.3BSD manual page documents 23 possible error conditions. Here is the complete list.
This list allows programmers to judge which errors are likely to occur in a given situation, which can be handled, and what to do about the rest. Modern FreeBSD expands this list to 40 documented errors, while the Debian distribution of GNU/Linux documents 32.
In contrast, the documentation of the Windows OpenFile function only specifies that “If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.”, which can return any of about 6000 error codes. As this information is returned at runtime, the main way programmers can find out which errors they need to handle in order to make their programs more resilient is by painful trial and error.
I first identified this problem in an article I wrote in 1997, titled A Critique of the Windows Application Programming Interface. At that time the possible error codes were 1130. As exemplified by the documentation of the Windows OpenFile function, things have not improved much in the past quarter century. Yet, there is a glimmer of hope. As I was reading the documentation of the RegQueryValueExA function, I was struck that it actually documented the reasons it could fail.
Excitedly, I installed the 1999 MSDN Library documentation to see how it was documented back then. The error conditions were indeed missing: “ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.” Although the error behavior of thousands of Windows functions must still be properly specified, adding such documentation a move in the right direction. After all the 1979 Seventh Research Edition Unix manual also lacked detailed system call error documentation, lamely arguing that “The possible error numbers are not recited with each writeup in section 2, since many errors are possible for most of the calls.” This was fixed a few years later, and we’re still enjoying the fruits of that labor.Comments Toot! Tweet
Last modified: Wednesday, September 30, 2020 0:00 am
Unless otherwise expressly stated, all original material on this page created by Diomidis Spinellis is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.