4 ms·

I'm not exactly a hardcore fan of Win32 userspace documentation but POSIX's drives me far more insane. Can you name a few examples that aren't from shell32/shlw

I'm not exactly a hardcore fan of Win32 userspace documentation but POSIX's drives me far more insane. Can you name a few examples that aren't from shell32/shlwapi?

temac 9y ago
General principles will be more interesting than examples: Win32 does not list the errors that can happen, rendering the greater error code space it has half-useless. Even without considering errors, the description of what functions do is often unclear or made in not precise terms. It is often needed to test the functions in tiny test programs to actually understand all their details before you can use them properly, and given they often have a high number of parameters this makes this matter even worse. Something as simple as the CreateProcess and family of function is a complete mess (both in the doc and in the detailed way they work...) POSIX actually doubles as a reference documentation. I don't think such a thing really exists for Win32 -- MSDN is way too vague to achieve that purpose. Maybe people from Wine / ReactOS maintain a better doc, I don't know.
- wfunction 9y ago
  > Win32 does not list the errors that can happen This is so patently wrong. Firstly, the first example I thought of (CreateFile) clearly stated that you could get ERROR_FILE_NOT_FOUND, ERROR_ALREADY_EXISTS, ERROR_FILE_EXISTS, ERROR_PIPE_BUSY, ERROR_SHARING_VIOLATION, ERROR_ACCESS_DENIED. Secondly, drivers can sometimes return error codes that the OS might not expect to be necessary, and the OS can't just coerce the error codes into something else; it'd lose information. [1] For example, if you CreateFile, a driver that mandatorily logs data might decide to return an error saying it's low on disk space even though the file already exists, which you wouldn't expect. If your code isn't specially written to handle it, you should treat it as the general failure condition it is. Heck, you can even think of Windows as returning "TRUE" (for no error) or "FALSE" (for error), and GetLastError as just providing details you can ignore. Simply the fact that you know the possibilities are TRUE and FALSE doesn't satisfy you though, does it? So isn't the problem that Linux is just suppressing information it could actually pass through? If anything, Windows is doing this right and Linux is doing it right by being restrictive on the returned information... but in any cases, at best you can suggest they're both "different" and maybe on a good day people would entertain the possibility. Certainly returning MORE information than you need is not something you can call out as a flaw... [1] e.g. see http://stackoverflow.com/a/19249991 http://stackoverflow.com/a/19249991
  - temac 9y ago
    You cherry-picked one function for which some errors were specified (and even in this case; few of them), yet you ignore the general case where MSDN seems to tell "go fuck yourself" to the programmer looking for the possible different error cases. Which are important to known in case you want to react programmatively to some, and in a different way to others. Given how poor the error reporting is under Windows (so poor that useless 32 bits hex error code, component dependant, are pretty much the only (useless) thing that users are seeing), the theory of "more of those" are better is also utterly ridiculous. I've never debugged anything looking at WinNT/Win32 error codes, or even the event log, etc, while I've in plenty of occasion debugged things with Unix errno, strace (which gives errno for failed syscalls) logs in /var/log (often dumping Unix errno + some context) or even just reading stderr. If you want to understand how much of the getlasterror specs are missing in Win32, just take a look at the Wine unit tests in various are. For each of those cases (maybe 99% of which are undocumented in MSDN), that can correspond to programmers needing to replicate their own qualification beforehand usage of affected functions, or worse to implicitly make some (sometimes false) hypothesis. And the overwhelming majority of them are not related whatsoever to any kind of driver and whatnot, it is just that not even the upper layer errors are properly specified/documented. This is the kind of info which should appear somewhere in MS doc, and which does not. It's insanely ridiculous because it's obvious MS have it in a form or another, given it is crucial for backward compatibility (or compatibility in general, if you take the Wine case -- but I guess when you remain within MS the main issue is backward compat)
    - wfunction 9y ago
      > I've never debugged anything looking at WinNT/Win32 error codes I think your lack of experience explains the issue. I do it pretty damn frequently. > so poor that useless 32 bits hex error code, component dependant, are pretty much the only (useless) thing that users are seeing All you need to do is look up the error code in either the headers or in MSDN [1] and then read the error message. It explains what's going on and does it far better than the minimal number of errnos possible. And no, I didn't cherry-pick anything. Like I said, I picked the first function I thought of. If you really cared enough to provide an example you could/would have, but you didn't. And this is ignoring the fact that I then told you why the listing of error codes or lack thereof was not possible in general. And it's not like in Linux you don't need to write and run and re-write and re-run code fifty times before you know all the edge cases. I remember having one hell of a time trying to figure out how to use epoll, for example. The documentation could easily be 2-3x as long. Regarding WINE: WINE is not software that uses the Windows API. It replicates the Windows API. Nobody ever claimed Windows's error reporting behavior is easy to replicate. We're talking about APIs, i.e. interfaces for programmers that program TO the system. An open set of error codes makes a ton of sense for all the reasons I listed. Of course an open sense means you'll have a much harder time replicating the behaviors. Windows was not designed to be easy to copy; it was designed to be easy to use. I would've thought that would be obvious. [1] https://msdn.microsoft.com/en-us/library/windows/desktop/ms681381.aspx https://msdn.microsoft.com/en-us/library/windows/desktop/ms6...
contras1970 9y ago
As someone who strives to write great reference manuals and thinks pretty high of the prose in the POSIX spec, would you point me at some examples of good win32 documentation? I'm always looking for inspiration.
- wfunction 9y ago
  I don't really have a list handy so I might have to keep looking to find something that meets the "great" bar (again -- I'm not a hardcore fan, I mere think it's reasonably decent), but for example check out the page on I/O Concepts [1] and the sub-pages (such as "Synchronous and Asynchronous I/O"). Does the POSIX documentation have anything like it? I don't recall so remind me if it does. https://msdn.microsoft.com/en-us/library/windows/desktop/aa365199.aspx https://msdn.microsoft.com/en-us/library/windows/desktop/aa3...

I'm not exactly a hardcore fan of Win32 userspace documentation but POSIX's drives me far more insane. Can you name a few examples that aren't from shell32/shlwapi?

temac 9y ago

General principles will be more interesting than examples: Win32 does not list the errors that can happen, rendering the greater error code space it has half-useless. Even without considering errors, the description of what functions do is often unclear or made in not precise terms. It is often needed to test the functions in tiny test programs to actually understand all their details before you can use them properly, and given they often have a high number of parameters this makes this matter even worse. Something as simple as the CreateProcess and family of function is a complete mess (both in the doc and in the detailed way they work...) POSIX actually doubles as a reference documentation. I don't think such a thing really exists for Win32 -- MSDN is way too vague to achieve that purpose. Maybe people from Wine / ReactOS maintain a better doc, I don't know.

wfunction 9y ago
> Win32 does not list the errors that can happen This is so patently wrong. Firstly, the first example I thought of (CreateFile) clearly stated that you could get ERROR_FILE_NOT_FOUND, ERROR_ALREADY_EXISTS, ERROR_FILE_EXISTS, ERROR_PIPE_BUSY, ERROR_SHARING_VIOLATION, ERROR_ACCESS_DENIED. Secondly, drivers can sometimes return error codes that the OS might not expect to be necessary, and the OS can't just coerce the error codes into something else; it'd lose information. [1] For example, if you CreateFile, a driver that mandatorily logs data might decide to return an error saying it's low on disk space even though the file already exists, which you wouldn't expect. If your code isn't specially written to handle it, you should treat it as the general failure condition it is. Heck, you can even think of Windows as returning "TRUE" (for no error) or "FALSE" (for error), and GetLastError as just providing details you can ignore. Simply the fact that you know the possibilities are TRUE and FALSE doesn't satisfy you though, does it? So isn't the problem that Linux is just suppressing information it could actually pass through? If anything, Windows is doing this right and Linux is doing it right by being restrictive on the returned information... but in any cases, at best you can suggest they're both "different" and maybe on a good day people would entertain the possibility. Certainly returning MORE information than you need is not something you can call out as a flaw... [1] e.g. see http://stackoverflow.com/a/19249991 http://stackoverflow.com/a/19249991
- temac 9y ago
  You cherry-picked one function for which some errors were specified (and even in this case; few of them), yet you ignore the general case where MSDN seems to tell "go fuck yourself" to the programmer looking for the possible different error cases. Which are important to known in case you want to react programmatively to some, and in a different way to others. Given how poor the error reporting is under Windows (so poor that useless 32 bits hex error code, component dependant, are pretty much the only (useless) thing that users are seeing), the theory of "more of those" are better is also utterly ridiculous. I've never debugged anything looking at WinNT/Win32 error codes, or even the event log, etc, while I've in plenty of occasion debugged things with Unix errno, strace (which gives errno for failed syscalls) logs in /var/log (often dumping Unix errno + some context) or even just reading stderr. If you want to understand how much of the getlasterror specs are missing in Win32, just take a look at the Wine unit tests in various are. For each of those cases (maybe 99% of which are undocumented in MSDN), that can correspond to programmers needing to replicate their own qualification beforehand usage of affected functions, or worse to implicitly make some (sometimes false) hypothesis. And the overwhelming majority of them are not related whatsoever to any kind of driver and whatnot, it is just that not even the upper layer errors are properly specified/documented. This is the kind of info which should appear somewhere in MS doc, and which does not. It's insanely ridiculous because it's obvious MS have it in a form or another, given it is crucial for backward compatibility (or compatibility in general, if you take the Wine case -- but I guess when you remain within MS the main issue is backward compat)
  - wfunction 9y ago
    > I've never debugged anything looking at WinNT/Win32 error codes I think your lack of experience explains the issue. I do it pretty damn frequently. > so poor that useless 32 bits hex error code, component dependant, are pretty much the only (useless) thing that users are seeing All you need to do is look up the error code in either the headers or in MSDN [1] and then read the error message. It explains what's going on and does it far better than the minimal number of errnos possible. And no, I didn't cherry-pick anything. Like I said, I picked the first function I thought of. If you really cared enough to provide an example you could/would have, but you didn't. And this is ignoring the fact that I then told you why the listing of error codes or lack thereof was not possible in general. And it's not like in Linux you don't need to write and run and re-write and re-run code fifty times before you know all the edge cases. I remember having one hell of a time trying to figure out how to use epoll, for example. The documentation could easily be 2-3x as long. Regarding WINE: WINE is not software that uses the Windows API. It replicates the Windows API. Nobody ever claimed Windows's error reporting behavior is easy to replicate. We're talking about APIs, i.e. interfaces for programmers that program TO the system. An open set of error codes makes a ton of sense for all the reasons I listed. Of course an open sense means you'll have a much harder time replicating the behaviors. Windows was not designed to be easy to copy; it was designed to be easy to use. I would've thought that would be obvious. [1] https://msdn.microsoft.com/en-us/library/windows/desktop/ms681381.aspx https://msdn.microsoft.com/en-us/library/windows/desktop/ms6...

contras1970 9y ago

As someone who strives to write great reference manuals and thinks pretty high of the prose in the POSIX spec, would you point me at some examples of good win32 documentation? I'm always looking for inspiration.

wfunction 9y ago
I don't really have a list handy so I might have to keep looking to find something that meets the "great" bar (again -- I'm not a hardcore fan, I mere think it's reasonably decent), but for example check out the page on I/O Concepts [1] and the sub-pages (such as "Synchronous and Asynchronous I/O"). Does the POSIX documentation have anything like it? I don't recall so remind me if it does. https://msdn.microsoft.com/en-us/library/windows/desktop/aa365199.aspx https://msdn.microsoft.com/en-us/library/windows/desktop/aa3...