FormatMessage

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function formats a message string.

DWORD FormatMessage ( DWORD
dwFlags, 
LPCVOID
lpSource,

DWORD
dwMessageId,

DWORD
dwLanguageId,

LPTSTR
lpBuffer,

DWORD
nSize,

va_list *
Arguments
);

Parameters

dwFlags

[in] Specifies aspects of the formatting process and how to interpret the lpSourceparameter. The low-order byte of dwFlagsspecifies how the function handles line breaks in the output buffer. The low-order byte can also specify the maximum width of a formatted output line.

This parameter can be a combination of the following bit flags:

Value	Description
FORMAT_MESSAGE_ALLOCATE_BUFFER	Specifies that the lpBufferparameter is a pointer to a PVOIDpointer, and that the nSizeparameter specifies the minimum number of bytes (ANSI version) or characters (Unicode version) 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 LocalFreefunction 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 Argumentsparameter is ignored.
FORMAT_MESSAGE_FROM_STRING	Specifies that lpSourceis 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 lpSourceis a module handle containing the message-table resource(s) to search. If this lpSourcehandle 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 GetLastErrorfunction to retrieve the message text for a system-defined error.
	Not all Windows CE-based devices will contain the system message-table resources. This is a selectable part of the Windows CE operating system and is often removed to conserve space.
FORMAT_MESSAGE_ARGUMENT_ARRAY	Specifies that the Argumentsparameter is nota va_liststructure, but instead is just a pointer to an array of 32-bit values that represent the arguments.

The low-order byte of dwFlagscan 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 list shows how FormatMessageinterprets the value of the low-order byte.

Value	Description
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.

lpSource

[in] Pointer to the location of the message definition. The type of this parameter depends upon the settings in the dwFlagsparameter.

Value	Description
FORMAT_MESSAGE_FROM_HMODULE	The lpSourceparameter is an hModuleof the module that contains the message table to search.
FORMAT_MESSAGE_FROM_STRING	The lpSourceparameter is an LPTSTRthat points to unformatted message text. It will be scanned for inserts and formatted accordingly.

If neither of these flags is set in dwFlags, then lpSourceis ignored.

dwMessageId

[in] Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlagsincludes FORMAT_MESSAGE_FROM_STRING.

dwLanguageId

[in] Not supported.

lpBuffer

[out] Pointer to a buffer for the formatted (and null-terminated) message. If dwFlagsincludes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer using the LocalAllocfunction, and places the pointer to the buffer at the address specified in lpBuffer.

nSize

[in] If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the maximum number of characters that can be stored in the output buffer. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies the minimum number of bytes or characters to allocate for an output buffer.

Arguments

[in] Pointer to an array of 32-bit values that are used as insert values in the formatted message. A %1 in the format string indicates the first value in the Argumentsarray; a %2 indicates the second argument; and so on.

The interpretation of each 32-bit 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 Argumentsparameter 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 32-bit values; those values are input to the message formatted as the insert values. Each insert must have a corresponding element in the array.

Return Values

The number of characters stored in the output buffer, excluding the terminating null character, indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

This 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 resources for the message definition. FormatMessagefinds the message definition in a message table resource based on a message identifier. FormatMessagecopies the formatted message text to an output buffer, processing any embedded insert sequences if requested.

The FormatMessagefunction 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(), 0, // Default
language (LPTSTR) &lpMsgBuf, 0, NULL ); // Process any inserts
in lpMsgBuf. // ... // Display the string. MessageBox( NULL,
(LPCTSTR)lpMsgBuf, L"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 list. All escape sequences start with the percent character (%).

%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 ncan be in the range 1 through 99. The printfformat string (which must be bracketed by exclamation marks) is optional and defaults to !s!if not specified.

The printfformat string can contain the * specifier for either the precision or the width component. If * is specified for one component, the FormatMessagefunction uses insert % n+1; it uses % n+2 if * is specified for both components.

Floating-point printfformat specifiers—e, E, f, and g—are not supported. The workaround is to use the sprintffunction 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 FormatMessageis 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 printfformat string.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	1.0 and later	Winbase.h		Fmtmsg.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.