Export (0) Print
Expand All

lstrcpyn function

Copies a specified number of characters from a source string into a buffer.

Warning  Do not use. Consider using StringCchCopy instead. See Remarks.

Syntax


LPTSTR WINAPI lstrcpyn(
  _Out_  LPTSTR lpString1,
  _In_   LPCTSTR lpString2,
  _In_   int iMaxLength
);

Parameters

lpString1 [out]

Type: LPTSTR

The destination buffer, which receives the copied characters. The buffer must be large enough to contain the number of TCHAR values specified by iMaxLength, including room for a terminating null character.

lpString2 [in]

Type: LPCTSTR

The source string from which the function is to copy characters.

iMaxLength [in]

Type: int

The number of TCHAR values to be copied from the string pointed to by lpString2 into the buffer pointed to by lpString1, including a terminating null character.

Return value

Type: LPTSTR

If the function succeeds, the return value is a pointer to the buffer. The function can succeed even if the source string is greater than iMaxLength characters.

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

Remarks

The buffer pointed to by lpString1 must be large enough to include a terminating null character, and the string length value specified by iMaxLength includes room for a terminating null character.

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

Security Warning

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.

If the buffer pointed to by lpString1 is not large enough to contain the copied string, a buffer overrun can occur. When copying an entire string, note that sizeof returns the number of bytes. For example, if lpString1 points to a buffer szString1 which is declared as TCHAR szString[100], then sizeof(szString1) gives the size of the buffer in bytes rather than WCHAR, 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 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.

Using sizeof(szString1)/sizeof(szString1[0]) gives the proper size of the buffer.

Consider using StringCchCopy instead; use either StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src);, being aware that buffer must not be a pointer or use StringCchCopy(buffer, ARRAYSIZE(buffer), src);, 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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

lstrcpynW (Unicode) and lstrcpynA (ANSI)

See also

Reference
StringCbCopy
StringCbCopyEx
StringCbCopyN
StringCbCopyNEx
StringCchCopy
StringCchCopyEx
StringCchCopyN
StringCchCopyNEx
StringCbLength
StringCchLength
lstrcmp
lstrcmpi
lstrlen
Conceptual
Strings

 

 

Community Additions

ADD
Show:
© 2014 Microsoft