{"id":40443,"date":"2004-03-02T06:57:00","date_gmt":"2004-03-02T06:57:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2004\/03\/02\/why-are-handle-return-values-so-inconsistent\/"},"modified":"2004-03-02T06:57:00","modified_gmt":"2004-03-02T06:57:00","slug":"why-are-handle-return-values-so-inconsistent","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20040302-00\/?p=40443","title":{"rendered":"Why are HANDLE return values so inconsistent?"},"content":{"rendered":"

\nIf you look at the various functions that return HANDLE<\/code>s,\nyou’ll see that some of them return NULL<\/code>\n(like CreateThread<\/code>)\nand some of them return INVALID_HANDLE_VALUE<\/code>\n(like CreateFile<\/code>).\nYou have to check the documentation to see what each particular function\nreturns on failure.<\/p>\n

\nWhy are the return values so inconsistent?<\/p>\n

\nThe reasons, as you may suspect, are historical.<\/p>\n

\nThe values were chosen to be compatible with 16-bit Windows.\nThe 16-bit functions OpenFile<\/code>, _lopen<\/code> and\n_lcreat<\/code> return -1<\/code> on failure, so the 32-bit\nCreateFile<\/code> function returns INVALID_HANDLE_VALUE<\/code>\nin order to facilitate porting code from Win16.<\/p>\n

\n(Armed with this, you can now answer the following trivia\nquestion: Why do I call CreateFile<\/code>\nwhen I’m not actually creating a file? Shouldn’t it be called\nOpenFile<\/code>? Answer: Yes, OpenFile<\/code> would have\nbeen a better name, but\n\nthat name was already taken<\/a>.)<\/p>\n

\nOn the other hand, there are no Win16 equivalents for\nCreateThread<\/code> or CreateMutex<\/code>, so they\nreturn NULL<\/code>.<\/p>\n

\nSince the precedent had now been set for inconsistent return values,\nwhenever a new function got added, it was a bit of a toss-up whether\nthe new function returned NULL<\/code> or\nINVALID_HANDLE_VALUE<\/code>.<\/p>\n

\nThis inconsistency has multiple consequences.<\/p>\n

\nFirst, of course, you have to be careful to check the return values\nproperly.<\/p>\n

\nSecond, it means that if you write a generic handle-wrapping class,\nyou have to be mindful of two possible “not a handle” values.<\/p>\n

\nThird, if you want to pre-initialize a HANDLE<\/code> variable,\nyou have to initialize it in a manner compatible with the function\nyou intend to use. For example, the following code is wrong:<\/p>\n

\nHANDLE h = NULL;\nif (UseLogFile()) {\n    h = CreateFile(...);\n}\nDoOtherStuff();\nif (h) {\n   Log(h);\n}\nDoOtherStuff();\nif (h) {\n    CloseHandle(h);\n}\n<\/pre>\n
This code has two bugs.  First, the return value from\nCreateFile<\/code> is checked incorrectly.  The code above\nchecks for NULL<\/code> instead of INVALID_HANDLE_VALUE<\/code>.\nSecond, the code initializes the h<\/code> variable incorrectly.\nHere’s the corrected version:<\/p>\n
\nHANDLE h = INVALID_HANDLE_VALUE;\nif (UseLogFile()) {\n    h = CreateFile(...);\n}\nDoOtherStuff();\nif (h != INVALID_HANDLE_VALUE) {\n   Log(h);\n}\nDoOtherStuff();\nif (h != INVALID_HANDLE_VALUE) {\n    CloseHandle(h);\n}\n<\/pre>\n
\nFourth, you have to be particularly careful with the\nINVALID_HANDLE_VALUE<\/code> value:\nBy coincidence, the value INVALID_HANDLE_VALUE<\/code>\nhappens to be numerically equal to the pseudohandle returned by\nGetCurrentProcess()<\/code>.\nMany kernel functions accept pseudohandles, so if\nif you mess up\nand accidentally call, say, WaitForSingleObject<\/code> on a\nfailed INVALID_HANDLE_VALUE<\/code> handle, you will actually\nend up waiting on your own process.  This wait will, of course,\nnever complete, because a process is signalled when it exits,\nso you ended up waiting for yourself.<\/p>\n","protected":false},"excerpt":{"rendered":"
If you look at the various functions that return HANDLEs, you’ll see that some of them return NULL (like CreateThread) and some of them return INVALID_HANDLE_VALUE (like CreateFile). You have to check the documentation to see what each particular function returns on failure. Why are the return values so inconsistent? The reasons, as you may […]<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[2],"class_list":["post-40443","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-history"],"acf":[],"blog_post_summary":"
If you look at the various functions that return HANDLEs, you’ll see that some of them return NULL (like CreateThread) and some of them return INVALID_HANDLE_VALUE (like CreateFile). You have to check the documentation to see what each particular function returns on failure. Why are the return values so inconsistent? The reasons, as you may […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/40443","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=40443"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/40443\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=40443"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=40443"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=40443"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}