<system_error> categories and standard/system error codes

Question

C++11 introduced the <system_error> header containing a generic system to handle error codes. An std::error_code is a tuple containing an int, the error code, and a reference to an std::error_category, which defines the error domain and handling of the error code. The standard library comes with four categories: std::generic_category, std::system_category, std::future_category, and std::iostream_category.

There are conflicts on which category to use, both here on SO and on C++ reference sites, when creating std::error_codes/throwing std::system_errors with errno and WinAPI error codes:

• errno with std::generic_category: SO answer, llvm-commits, cplusplus.com
• errno with std::system_category: SO answer, cppreference.com
• GetLastError() with std::generic_category: SO answer
• GetLastError() with std::system_category: SO answer, SO comment

However, errno and GetLastError() can't use the same category, otherwise some error codes would be ambiguous. Error code 33 is one example, as it is both EDOM and ERROR_LOCK_VIOLATION.

There are even some places advocating a user-made category for the WinAPI, but I can't find any references to that at the moment. This alternative would be specially painful.

Which category should be used with errno, and which should be used with GetLastError() so that

• std::error_code::default_error_condition()
• std::error_code::message()

are unambinguous and appropriate to the underlying error code?

Answer 1

I have to admit to a bit of surprise at the confusion regarding <system_error> given Chris summarised exactly how it works at http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html and I personally find the C++ standard text above perfectly clear. But to summarise in very succinct words:

If on POSIX:

generic_category => POSIX standard errno space

system_category => Local POSIX errno space (usually extends POSIX with proprietary errno codes). Use strerror() to expand codes into string descriptions returned by message().

In practice on POSIX both implementations are the same underneath and map the native errno space.

If on Windows:

generic_category => POSIX standard errno space which is returned by various POSIX emulation functions in the MSVCRT like fopen() etc

system_category => The Win32 GetLastError() space. Use FormatMessage() to expand codes into string descriptions returned by message().

How to use <system_error> portably

std::error_code ec; #ifdef _WIN32 if((HANDLE)-1 == CreateFile(...))   ec = std::error_code(GetLastError(), std::system_category()); #else if(-1 == open(...))   ec = std::error_code(errno, std::system_category()); #endif // To test using portable code if(ec == std::errc::no_such_file_or_directory)    ... // To convert into nearest portable error condition (lossy, may fail) std::error_condition ec2(ec.default_error_condition()) 

Other thoughts:

Some commentators have said that <system_error> is poorly designed and shouldn't be used. This is simply not true, it's pretty optimal given the C++ 03 idiomatic practice of the time of its design, it generates very tight high quality fixed latency code on all major STLs except Dinkumware's. It's user extensible to any arbitrary error code system, and standardises unifying into a single system disparate third party library error handling.

It is true it would look quite different today had constexpr global variables been available at the time of its design, and maybe that might get rectified in a C++ standard coming after 17. But if you are a programmer who needs to move around error codes from third party libraries without losing information through code not written to know about those third party libraries, then <system_error> is an excellent solution.

Consider it as similar to the virtual keyword for third party library error code handling - it erases the need for code transporting third party codes from needing to understand those codes. If you have that problem in your code base - and most large code bases do - then absolutely you should be using <system_error> instead of whatever error code mapping or translation system you're currently using.