| Platform SDK: Debugging and Error Handling |
The FormatMessage function formats a message string. The function requires a message definition as input. The message definition can come from a buffer passed into the function. It can come from a message table resource in an already-loaded module. Or the caller can ask the function to search the system's message table resource(s) for the message definition. The function finds the message definition in a message table resource based on a message identifier and a language identifier. The function copies the formatted message text to an output buffer, processing any embedded insert sequences if requested.
DWORD FormatMessage( DWORD dwFlags, // source and processing options LPCVOID lpSource, // message source DWORD dwMessageId, // message identifier DWORD dwLanguageId, // language identifier LPTSTR lpBuffer, // message buffer DWORD nSize, // maximum size of message buffer va_list *Arguments // array of message inserts );
You can specify a combination of the following values.
| Value | Meaning |
|---|---|
| FORMAT_MESSAGE_ALLOCATE_BUFFER | Specifies that the lpBuffer parameter is a pointer to a PVOID pointer, and that the nSize parameter specifies the minimum number of TCHARs to allocate for an output message buffer. The function allocates a buffer large enough to hold the formatted message, and places a pointer to the allocated buffer at the address specified by lpBuffer. The caller should use the LocalFree function to free the buffer when it is no longer needed. |
| FORMAT_MESSAGE_IGNORE_INSERTS | Specifies that insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. This flag is useful for fetching a message for later formatting. If this flag is set, the Arguments parameter is ignored. |
| FORMAT_MESSAGE_FROM_STRING | Specifies that lpSource is a pointer to a null-terminated message definition. The message definition may contain insert sequences, just as the message text in a message table resource may. Cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM. |
| FORMAT_MESSAGE_FROM_HMODULE | Specifies that lpSource is a module handle containing the message-table resource(s) to search. If this lpSource handle is NULL, the current process's application image file will be searched. Cannot be used with FORMAT_MESSAGE_FROM_STRING. |
| FORMAT_MESSAGE_FROM_SYSTEM | Specifies that the function should search the system message-table resource(s) for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, the function searches the system message table if the message is not found in the module specified by lpSource. Cannot be used with FORMAT_MESSAGE_FROM_STRING.
If this flag is specified, an application can pass the result of the GetLastError function to retrieve the message text for a system-defined error. |
| FORMAT_MESSAGE_ARGUMENT_ARRAY | Specifies that the Arguments parameter is not a va_list structure, but instead is just a pointer to an array of values that represent the arguments. |
The low-order byte of dwFlags can specify the maximum width of a formatted output line. Use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant and bitwise Boolean operations to set and retrieve this maximum width value.
The following table shows how FormatMessage interprets the value of the low-order byte.
| Value | Meaning |
|---|---|
| 0 | There are no output line width restrictions. The function stores line breaks that are in the message definition text into the output buffer. |
| A nonzero value other than FORMAT_MESSAGE_MAX_WIDTH_MASK | The nonzero value is the maximum number of characters in an output line. The function ignores regular line breaks in the message definition text. The function never splits a string delimited by white space across a line break. The function stores hard-coded line breaks in the message definition text into the output buffer. Hard-coded line breaks are coded with the %n escape sequence. |
| FORMAT_MESSAGE_MAX_WIDTH_MASK | The function ignores regular line breaks in the message definition text. The function stores hard-coded line breaks in the message definition text into the output buffer. The function generates no new line breaks. |
| dwFlags Setting | Parameter Type |
|---|---|
| FORMAT_MESSAGE_FROM_HMODULE | This parameter is a handle to the module that contains the message table to search. |
| FORMAT_MESSAGE_FROM_STRING | This parameter is a pointer to a string that consists of unformatted message text. It will be scanned for inserts and formatted accordingly. |
If neither of these flags is set in dwFlags, then lpSource is ignored.
If you pass a specific LANGID in this parameter, FormatMessage will return a message for that LANGID only. If the function cannot find a message for that LANGID, it returns ERROR_RESOURCE_LANG_NOT_FOUND. If you pass in zero, FormatMessage looks for a message for LANGIDs in the following order:
If FormatMessage doesn't find a message for any of the preceding LANGIDs, it returns any language message string that is present. If that fails, it returns ERROR_RESOURCE_LANG_NOT_FOUND.
The interpretation of each value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string.
By default, the Arguments parameter is of type va_list*, which is a language- and implementation-specific data type for describing a variable number of arguments. If you do not have a pointer of type va_list*, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of values; those values are input to the message formatted as the insert values. Each insert must have a corresponding element in the array.
Windows 95: No single insertion string may exceed 1023 characters in length.
If the function succeeds, the return value is the number of TCHARs stored in the output buffer, excluding the terminating null character.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
The FormatMessage function can be used to obtain error message strings for the system error codes returned by GetLastError, as shown in the following sample code.
LPVOID lpMsgBuf;
FormatMessage(
FORMAT_MESSAGE_ALLOCATE_BUFFER |
FORMAT_MESSAGE_FROM_SYSTEM |
FORMAT_MESSAGE_IGNORE_INSERTS,
NULL,
GetLastError(),
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language
(LPTSTR) &lpMsgBuf,
0,
NULL
);
// Process any inserts in lpMsgBuf.
// ...
// Display the string.
MessageBox( NULL, (LPCTSTR)lpMsgBuf, "Error", MB_OK | MB_ICONINFORMATION );
// Free the buffer.
LocalFree( lpMsgBuf );
Within the message text, several escape sequences are supported for dynamically formatting the message. These escape sequences and their meanings are shown in the following table. All escape sequences start with the percent character (%).
| Escape Sequence | Meaning |
|---|---|
| %0 | Terminates a message text line without a trailing newline character. This escape sequence can be used to build up long lines or to terminate the message itself without a trailing newline character. It is useful for prompt messages. |
| %n!printf format string! | Identifies an insert. The value of n can be in the range 1 through 99. The printf format string (which must be bracketed by exclamation marks) is optional and defaults to !s! if not specified. |
| The printf format string can contain the * specifier for either the precision or the width component. If * is specified for one component, the FormatMessage function uses insert %n+1; it uses %n+2 if * is specified for both components. | |
| Floating-point printf format specifiers — e, E, f, and g — are not supported. The workaround is to to use the sprintf function to format the floating-point number into a temporary buffer, then use that buffer as the insert string. |
Any other nondigit character following a percent character is formatted in the output message without the percent character. Following are some examples:
| Format string | Resulting output |
|---|---|
| %% | A single percent sign in the formatted message text. |
| %n | A hard line break when the format string occurs at the end of a line. This format string is useful when FormatMessage is supplying regular line breaks so the message fits in a certain width. |
| %space | A space in the formatted message text. This format string can be used to ensure the appropriate number of trailing spaces in a message text line. |
| %. | A single period in the formatted message text. This format string can be used to include a single period at the beginning of a line without terminating the message text definition. |
| %! | A single exclamation point in the formatted message text. This format string can be used to include an exclamation point immediately after an insert without its being mistaken for the beginning of a printf format string. |
Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.
Error Handling Overview, Error Handling Functions, MESSAGETABLE Resource, Message Compiler