Table of Contents
Copyright (c) 2003 Aaron Isotton
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
In any quality program you have to handle and report errors. When
reporting errors from the operating system, it is
crucial that you give as much information as
possible to the user. Many functions of the Win32 API set an error code
which can be retrieved using GetLastError().
You can obtain a description of the error using
FormatMessage(), but using it is an absolute
horror. winerr is a very thin wrapper around
FormatMessage() and
GetLastError() similar in many aspects to C's
strerror().
The overhead of winerr is minimal; the static library is less than one kilobyte in size, and most probably you won't use all of the functions so that your linker will not use the whole library.
You can download winerr and its documentation from http://www.isotton.com/winerr/.
Using mingw, you can link your programs with the provided
libwinerr.a. I don't know whether it works with
MSVC too; you might need to rename it to
libwinerr.lib.
Alternatively, you can simply add winerr.c to
your project and compile it with the rest of your sources.
There are two sets of functions in winerr: the multibyte and the
wide character ones. Consistently with the Win32 API, there are two
definitions for every function: one ending with
“A” (the multibyte version) and one
ending with “W” (the unicode version).
Additionally, a constant mapping to the appropriate function is
#defined according to whether
UNICODE is defined or not. If you have ever dealt
with multibyte/wide character issues with the Win32 API, you know what I
mean. Otherwise look at winerr.h.
Returns a pointer to a static buffer containing the description of
the error code code.
As the buffer is static, this might be an issue in multithreaded
programs. In that case, use winerr_r().
This is the reentrant version of winerr().
As you have to pass the buffer, it can be used with multithreaded
programs without causing problems.
buffer is a pointer to a character string where
the error description should be written; len is the
maximum number of characters (not bytes) which should be written to
the buffer.
A pointer to buffer is returned. This is
useful if you want, for example, to use
winerr_r() directly in
printf().