strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

Статья
06/09/2015

Копируют символы одной строки в другую. Существуют более безопасные версии этих функций; см. раздел strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l.

Важно!

_mbsncpy и _mbsncpy_l не могут использоваться в приложениях, выполняемых в Среда выполнения Windows.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /ZW.

char *strncpy(
   char *strDest,
   const char *strSource,
   size_t count 
);
char *_strncpy_l(
   char *strDest,
   const char *strSource,
   size_t count,
   locale_t locale 
);
wchar_t *wcsncpy(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);
wchar_t *_wcsncpy_l(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
);
unsigned char *_mbsncpy(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count 
);
unsigned char *_mbsncpy_l(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
char *strncpy(
   char (&strDest)[size],
   const char *strSource,
   size_t count 
); // C++ only
template <size_t size>
char *_strncpy_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
wchar_t *wcsncpy(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
wchar_t *_wcsncpy_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Параметры

strDest
Конечная строка.
strSource
Исходная строка.
count
Число копируемых знаков.
locale
Языковой стандарт, который необходимо использовать.

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

Возвращает strDest. Нет зарезервированных возвращаемых значений для указания ошибки.

Заметки

Функция strncpy копирует первые count символов strSource в strDest и возвращает strDest. Если count меньше или равно длине strSource, нулевой символ не добавляется автоматически в скопированную строку. Если count больше, чем длина strSource, то строка назначения заполняется нулевыми символами до длины count. При перекрытии исходной и конечной строк поведение инструкции strncpy не определено.

Примечание по безопасности
strncpy не проверяет наличие достаточного места в strDest; это делает ее потенциальной причиной переполнения буфера.Аргумент count ограничивает число копируемых знаков и не является ограничением на размер strDest.См. следующий пример.Дополнительные сведения см. в разделе Как избежать переполнения буфера.

strncpy не проверяет наличие достаточного места в strDest; это делает ее потенциальной причиной переполнения буфера.Аргумент count ограничивает число копируемых знаков и не является ограничением на размер strDest.См. следующий пример.Дополнительные сведения см. в разделе Как избежать переполнения буфера.

Если strDest или strSource — указатель на NULL, или если count меньше или равен нулю, то вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, эти функции возвращают -1 и устанавливают для errno значение EINVAL.

wcsncpy и _mbsncpy — двубайтовая и многобайтовая символьные версии strncpy. Аргументы и возвращаемое значение wcsncpy и _mbsncpy различаются соответственно. В остальном эти шесть функций ведут себя идентично.

Версии этих функций с суффиксом _l идентичны, за исключением того, что для поведения, зависящего от языкового стандарта, они используют переданный параметр языкового стандарта вместо текущего языкового стандарта. Для получения дополнительной информации см. Языковой стандарт.

В C++ эти функции имеют шаблонные перегрузки, которые вызывают более новые и безопасные аналоги этих функций. Дополнительные сведения см. в разделе Безопасные перегрузки шаблонов.

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_tcsncpy	strncpy	_mbsnbcpy	wcsncpy
_tcsncpy_l	_strncpy_l	_mbsnbcpy_l	_wcsncpy_l

Примечание

_strncpy_l и _wcsncpy_l не имеет никакой зависимости от языкового стандарта; они предназначены только для _tcsncpy_l и не должны вызываться напрямую.

Требования

Подпрограмма	Обязательный заголовок
strncpy	<string.h>
wcsncpy	<string.h> или <wchar.h>
_mbsncpy, _mbsncpy_l	<mbstring.h>

Дополнительные сведения о совместимости см. в разделе Compatibility.

Пример

В следующем примере показано, как использовать strncpy и как можно неправильно использовать его, что вызывает ошибки и проблемы безопасности в программе. Компилятор выдает предупреждение при каждом вызове strncpy подобно crt_strncpy_x86.c(15) : warning C4996: 'strncpy': This function or variable may be unsafe. Consider using strncpy_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.

// crt_strncpy_x86.c
// Use this command in an x86 developer command prompt to compile: 
// cl /TC /W3 crt_strncpy_x86.c

#include <stdio.h>
#include <string.h>

int main() {
   char t[20];
   char s[20];
   char *p = 0, *q = 0;

   strcpy_s(s, sizeof(s), "AA BB CC");
   // Note: strncpy is deprecated; consider using strncpy_s instead
   strncpy(s, "aa", 2);     // "aa BB CC"         C4996
   strncpy(s + 3, "bb", 2); // "aa bb CC"         C4996
   strncpy(s, "ZZ", 3);     // "ZZ",              C4996
                            // count greater than strSource, null added
   printf("%s\n", s);

   strcpy_s(s, sizeof(s), "AA BB CC");
   p = strstr(s, "BB");
   q = strstr(s, "CC");
   strncpy(s, "aa", p - s - 1);   // "aa BB CC"   C4996
   strncpy(p, "bb", q - p - 1);   // "aa bb CC"   C4996
   strncpy(q, "cc",  q - s);      // "aa bb cc"   C4996
   strncpy(q, "dd", strlen(q));   // "aa bb dd"   C4996
   printf("%s\n", s);

   // some problems with strncpy
   strcpy_s(s, sizeof(s), "test");
   strncpy(t, "this is a very long string", 20 ); // C4996
   // Danger: at this point, t has no terminating null,
   // so the printf continues until it runs into one.
   // In this case, it will print "this is a very long test"
   printf("%s\n", t);

   strcpy_s(t, sizeof(t), "dogs like cats");
   printf("%s\n", t);

   strncpy(t + 10, "to chase cars.", 14); // C4996
   printf("%s\n", t);

   // strncpy has caused a buffer overrun and corrupted string s
   printf("Buffer overrun: s = '%s' (should be 'test')\n", s);
   // Since the stack grows from higher to lower addresses, buffer
   // overruns can corrupt function return addresses on the stack,
   // which can be exploited to run arbitrary code.
}

Output

Макет автоматических переменных и уровня защиты кода и обнаружения ошибок меняется с измененными параметрами компилятора. Этот пример может иметь разные результаты при компиляции в другой среде или с другими параметрами компилятора.