функция lstrcpynA (winbase.h)

Статья
11/20/2024

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

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

Синтаксис

LPSTR lstrcpynA(
  [out] LPSTR  lpString1,
  [in]  LPCSTR 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 без завершения строки без уведомления вызывающего объекта об ошибке. Вызывающий объект не является безопасным, чтобы предположить, что недостаточно места является условием ошибки.

Если буфер, на который указывает lpString1 недостаточно велик, чтобы содержать скопированную строку, может произойти перезапуск буфера. При копировании всей строки обратите внимание, что размер возвращает количество байтов. Например, если 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 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll