Функция lstrcpynW (winbase.h)

Статья
08/27/2023

Копирует указанное количество символов из исходной строки в буфер.

Предупреждение Не используйте. Вместо этого рекомендуется использовать StringCchCopy . См. заметки.

Синтаксис

LPWSTR lstrcpynW(
  [out] LPWSTR  lpString1,
  [in]  LPCWSTR lpString2,
  [in]  int     iMaxLength
);

Параметры

[out] lpString1

Тип: LPTSTR

Буфер назначения, который получает скопированные символы. Буфер должен быть достаточно большим, чтобы содержать количество значений TCHAR , указанных в iMaxLength, включая пространство для завершающего символа NULL.

[in] lpString2

Тип: LPCTSTR

Исходная строка, из которой функция копирует символы.

[in] iMaxLength

Тип: int

Количество значений TCHAR , копируемых из строки, на которую указывает lpString2 , в буфер, на который указывает lpString1, включая завершающий символ NULL.

Возвращаемое значение

Тип: LPTSTR

Если функция выполняется успешно, возвращаемое значение является указателем на буфер. Функция может быть успешной, даже если исходная строка больше символов iMaxLength .

Если функция завершается сбоем, возвращаемое значение равно NULL , а lpString1 может не заканчиваться null.

Буфер, на который указывает lpString1 , должен быть достаточно большим, чтобы включать завершающий символ NULL, а значение длины строки, указанное в iMaxLength , содержит место для завершающего символа NULL.

Функция lstrcpyn имеет неопределенное поведение, если буферы источника и назначения перекрываются.

Предупреждение системы безопасности

Неправильное использование этой функции может поставить под угрозу безопасность приложения. Эта функция использует структурированную обработку исключений (SEH) для перехвата нарушений доступа и других ошибок. Когда эта функция перехватывает ошибки SEH, она возвращает значение NULL , не завершая строку со значением NULL и не уведомляя вызывающий объект об ошибке. Вызывающий объект не может предположить, что недостаточно места является условием ошибки.

Если буфер, на который указывает lpString1 , недостаточно велик, чтобы содержать скопированную строку, может произойти переполнение буфера. При копировании всей строки обратите внимание, что sizeof возвращает количество байтов. Например, если lpString1 указывает на буфер szString1 , объявленный как TCHAR szString[100], то sizeof(szString1) задает размер буфера в байтах, а не WCHAR, что может привести к переполнению буфера для версии функции в Юникоде.

Ситуации переполнения буфера являются причиной многих проблем безопасности в приложениях и могут привести к атаке типа "отказ в обслуживании" на приложение в случае нарушения доступа. В худшем случае переполнение буфера может позволить злоумышленнику внедрить исполняемый код в процесс, особенно если lpString1 является буфером на основе стека.

Использование sizeof(szString1)/sizeof(szString1[0]) дает правильный размер буфера.

Вместо этого рекомендуется использовать StringCchCopy ; используйте либо StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src);, учитывая, что buffer не должен быть указателем, либо используйте StringCchCopy(buffer, ARRAYSIZE(buffer), src);, учитывая, что при копировании в указатель вызывающий объект отвечает за передачу размера указателя в памяти в символах.

Прежде чем продолжить, ознакомьтесь с рекомендациями по безопасности: пользовательский интерфейс Windows .

Примечание

Заголовок winbase.h определяет lstrcpyn как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll