This function copies a string to a buffer.

To copy a specified number of characters, use the lstrcpyn function.

Syntax

LPTSTR lstrcpy(      
    LPTSTR lpString1,
    LPTSTR lpString2
);

Parameters

lpString1

[out] Pointer to a buffer to receive the contents of the string pointed to by the lpString2 parameter. The buffer must be large enough to contain the string, including the terminating null character.

lpString2

[in] Pointer to the null-terminated string to be copied.

Return Value

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL and lpString1 may not be null-terminated.

Remarks

Security Alert  

Using this function incorrectly can compromise the security of your application. This function uses structured exception handling (SEH) to catch access violations and other errors. When this function catches SEH errors, it returns NULL without null-terminating the string and without notifying the caller of the error. The caller is not safe to assume that insufficient space is the error condition.

lpString1 must be large enough to hold lpString2 and the closing '\0', otherwise a buffer overrun may occur.

Buffer overflow situations are the cause of many security problems in applications and can cause a denial of service attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker to inject executable code into your process, especially if lpString1 is a stack-based buffer.

Consider using StringCchCopy instead; use either StringCchCopy(buffer, src, sizeof(buffer)/sizeof(buffer[0]);, being aware that buffer must not be a pointer or use StringCchCopy(buffer, src, ARRAYSIZE(buffer);, being aware that, when copying to a pointer, the caller is responsible for passing in the size of the pointed-to memory in characters.

Review Security Considerations: Windows User Interface before continuing.

With a double-byte character set (DBCS) version of the system, this function can be used to copy a DBCS string.

The lstrcpy function has an undefined behavior if source and destination buffers overlap.

Windows 95/98/Me: lstrcpyW is supported by the Microsoft Layer for Unicode (MSLU). Although the W version already exists on Windows 98/Me, it is included to give more consistent behavior across all Windows operating systems. To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.

Example

For an example, see Changing Environment Variables.

Function Information

Minimum DLL Version	kernel32.dll
Header	Declared in Winbase.h, include Windows.h
Import library	Kernel32.lib
Minimum operating systems	Windows 95, Windows NT 3.1
Unicode	Implemented as ANSI and Unicode versions.

See Also

Strings Overview, StringCbCopy, StringCbCopyEx, StringCbCopyN, StringCbCopyNEx, StringCchCopy, StringCchCopyEx, StringCchCopyN, StringCchCopyNEx, lstrcat, lstrcmp, lstrcmpi, lstrlen