LoadStringA function (winuser.h)

Article
12/08/2023

Loads a string resource from the executable file associated with a specified module and either copies the string into a buffer with a terminating null character or returns a read-only pointer to the string resource itself.

Syntax

int LoadStringA(
  [in, optional] HINSTANCE hInstance,
  [in]           UINT      uID,
  [out]          LPSTR     lpBuffer,
  [in]           int       cchBufferMax
);

Parameters

[in, optional] hInstance

Type: HINSTANCE

A handle to an instance of the module whose executable file contains the string resource. To get the handle to the application itself, call the GetModuleHandle function with NULL.

[in] uID

Type: UINT

The identifier of the string to be loaded.

[out] lpBuffer

Type: LPTSTR

The buffer to receive the string. Must be at least cchBufferMax characters in size.

[in] cchBufferMax

Type: int

The size of the buffer, in characters. The string is truncated and null-terminated if it is longer than the number of characters specified. This parameter may not be zero.

Return value

Type: int

If the function succeeds, the return value is the number of characters copied into the buffer, not including the terminating null character.

If the string resource does not exist, the return value is zero.

To get extended error information, call GetLastError.

Remarks

Unlike the LoadStringW function, the LoadStringA function does not support passing a value of zero for cchBufferMax. Doing so will corrupt memory.

Security Remarks

Using this function incorrectly can compromise the security of your application. Incorrect use includes specifying the wrong size in the cchBufferMax parameter. For example, if lpBuffer points to a buffer szBuffer which is declared as TCHAR szBuffer[100], then sizeof(szBuffer) gives the size of the buffer in bytes, which could lead to a buffer overflow for the Unicode version of the function. Buffer overflow situations are the cause of many security problems in applications. In this case, using sizeof(szBuffer)/sizeof(TCHAR) or sizeof(szBuffer)/sizeof(szBuffer[0]) would give the proper size of the buffer.

Examples

For an example, see Creating a Child Window

Note

The winuser.h header defines LoadString as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll

Share via