strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l
Символы копии одной строки в другую.Здесь представлены версии strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l с усовершенствованной безопасностью, как описано в разделе Средства безопасности в CRT.
Важно |
---|
_mbsncpy_s и _mbsncpy_s_l нельзя использовать в приложениях, выполняемых в среды выполнения Windows.Дополнительные сведения см. в разделе Функции CRT не поддерживаются при /ZW. |
errno_t strncpy_s(
char *strDest,
size_t numberOfElements,
const char *strSource,
size_t count
);
errno_t _strncpy_s_l(
char *strDest,
size_t numberOfElements,
const char *strSource,
size_t count,
_locale_t locale
);
errno_t wcsncpy_s(
wchar_t *strDest,
size_t numberOfElements,
const wchar_t *strSource,
size_t count
);
errno_t _wcsncpy_s_l(
wchar_t *strDest,
size_t numberOfElements,
const wchar_t *strSource,
size_t count,
_locale_t locale
);
errno_t _mbsncpy_s(
unsigned char *strDest,
size_t numberOfElements,
const unsigned char *strSource,
size_t count
);
errno_t _mbsncpy_s_l(
unsigned char *strDest,
size_t numberOfElements,
const unsigned char *strSource,
size_t count,
locale_t locale
);
template <size_t size>
errno_t strncpy_s(
char (&strDest)[size],
const char *strSource,
size_t count
); // C++ only
template <size_t size>
errno_t _strncpy_s_l(
char (&strDest)[size],
const char *strSource,
size_t count,
_locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncpy_s(
wchar_t (&strDest)[size],
const wchar_t *strSource,
size_t count
); // C++ only
template <size_t size>
errno_t _wcsncpy_s_l(
wchar_t (&strDest)[size],
const wchar_t *strSource,
size_t count,
_locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncpy_s(
unsigned char (&strDest)[size],
const unsigned char *strSource,
size_t count
); // C++ only
template <size_t size>
errno_t _mbsncpy_s_l(
unsigned char (&strDest)[size],
const unsigned char *strSource,
size_t count,
locale_t locale
); // C++ only
Параметры
strDest
Строка назначения.numberOfElements
Размер строки назначения, в символах.strSource
Строка источника.count
Число символов для копирования, или _TRUNCATE.locale
Используемый языковой стандарт.
Возвращаемое значение
Ноль, если оно завершится успешно, значение STRUNCATE, если произошло усечение, в противном случае код ошибки.
Условия возникновения ошибки
strDest |
numberOfElements |
strSource |
Возвращаемое значение |
Содержимое strDest. |
---|---|---|---|---|
NULL |
любое значение |
любое значение |
EINVAL |
без изменений |
любое значение |
любое значение |
NULL |
EINVAL |
strDest[0] присваивается значение 0. |
любое значение |
0 |
любое значение |
EINVAL |
без изменений |
NULL не |
слишком маленький |
любое значение |
ERANGE |
strDest[0] присваивается значение 0. |
Заметки
Эти функции будут скопированы первые символы DstrSource в strDest, где D - нижняя из count и длины strSource.Если эти символы D приспособят в функции strDest (размер которого задано как numberOfElements) и по-прежнему остаться место для маркера конца строки null, эти символы копируются и конечное значение NULL будет добавлен; в противном случае strDest[0] имеет значение нулю-символу и обработчик недопустимого параметра метода, как описано в разделе Проверка параметров.
Исключение к вышеуказанному абзацу.Если count имеет значение _TRUNCATE, что многие strSource как поместит в strDest копируется в то же время оставить место для конечное значение NULL, всегда добавляется.
Например:
char dst[5];
strncpy_s(dst, 5, "a long string", 5);
это означает, что спрашиваем strncpy_s для копирования 5 символов в буфер длиной 5 байт; это не вышло, нет места для маркера конца строки null, поэтому strncpy_s обнулит строка и вызывает обработчик недопустимого параметра.
Если расширение функциональности усечения, следует использовать _TRUNCATE или size (– 1).
strncpy_s(dst, 5, "a long string", _TRUNCATE);
strncpy_s(dst, 5, "a long string", 4);
Обратите внимание, что в отличие от strncpy, если count больше, чем длина strSource, строка назначения не проложена с нулями-символами до длины count.
При перекрытии исходной и конечной строк поведение инструкции strncpy_s не определено.
Если strDest или strSource, NULL или numberOfElements равно 0, то обработчик недопустимого параметра вызывается.Если выполнение разрешено для продолжить, функция возвращает EINVAL и задает errno в EINVAL.
wcsncpy_s и _mbsncpy_s — двубайтовая и многобайтовая символьные версии strncpy_s.Аргументы и возвращаемое значение зависит от wcsncpy_s и mbsncpy_s соответственно.Эти 6 функций поведение идентично в противном случае.
Выходное значение зависеть на параметром параметра категории LC_CTYPE языкового стандарта; дополнительные сведения см. в разделе setlocale.Версии этих функций без суффикса _l используют текущий языковой стандарт для данной функциональности, зависящей от языкового стандарта; версии с суффиксом _l идентичны, за исключением того, что они используют переданный параметр языкового стандарта.Для получения дополнительной информации см. Языковой стандарт.
В C++ использование данных функций упрощено наличием шаблонных перегрузок; перегруженные методы могут автоматически определять длину буфера (что исключает необходимость указания аргумента с размером буфера), а также они могут автоматически заменять более старые, незащищенные функции их новыми безопасными аналогами.Для получения дополнительной информации см. Предоставляйте перегруженный шаблона.
Отладочные версии этих функций сначала заполняют буфер значением 0xFD.Для отключения данного поведения используйте _CrtSetDebugFillThreshold.
Универсальное текстовое сопоставление функций
Функция TCHAR.H |
неопределенные _UNICODE & _MBCS |
определенные _MBCS |
Определение _UNICODE |
---|---|---|---|
_tcsncpy_s |
strncpy_s |
_mbsnbcpy_s |
wcsncpy_s |
_tcsncpy_s_l |
_strncpy_s_l |
_mbsnbcpy_s_l |
_wcsncpy_s_l |
Примечание |
---|
_strncpy_s_l, _wcsncpy_s_l и _mbsncpy_s_l не имеют имеет зависимость от языкового стандарта и предоставляются только для _tcsncpy_s_l и не должны вызывать напрямую. |
Требования
Функция |
Требуемый заголовок |
---|---|
strncpy_s, _strncpy_s_l |
<string.h> |
wcsncpy_s, _wcsncpy_s_l |
<string.h> или <wchar.h> |
_mbsncpy_s, _mbsncpy_s_l |
<mbstring.h> |
Дополнительные сведения о совместимости см. в разделе Совместимость во введении.
Пример
// crt_strncpy_s_1.cpp
// compile with: /MTd
// these #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h> // For _CrtSetReportMode
#include <errno.h>
// This example uses a 10-byte destination buffer.
errno_t strncpy_s_tester( const char * src,
int count )
{
char dest[10];
printf( "\n" );
if ( count == _TRUNCATE )
printf( "Copying '%s' to %d-byte buffer dest with truncation semantics\n",
src, _countof(dest) );
else
printf( "Copying %d chars of '%s' to %d-byte buffer dest\n",
count, src, _countof(dest) );
errno_t err = strncpy_s( dest, _countof(dest), src, count );
printf( " new contents of dest: '%s'\n", dest );
return err;
}
void Examples()
{
strncpy_s_tester( "howdy", 4 );
strncpy_s_tester( "howdy", 5 );
strncpy_s_tester( "howdy", 6 );
printf( "\nDestination buffer too small:\n" );
strncpy_s_tester( "Hi there!!", 10 );
printf( "\nTruncation examples:\n" );
errno_t err = strncpy_s_tester( "How do you do?", _TRUNCATE );
printf( " truncation %s occur\n", err == STRUNCATE ? "did"
: "did not" );
err = strncpy_s_tester( "Howdy.", _TRUNCATE );
printf( " truncation %s occur\n", err == STRUNCATE ? "did"
: "did not" );
printf( "\nSecure template overload example:\n" );
char dest[10];
strncpy( dest, "very very very long", 15 );
// With secure template overloads enabled (see #defines at
// top of file), the preceding line is replaced by
// strncpy_s( dest, _countof(dest), "very very very long", 15 );
// Instead of causing a buffer overrun, strncpy_s invokes
// the invalid parameter handler.
// If secure template overloads were disabled, strncpy would
// copy 15 characters and overrun the dest buffer.
printf( " new contents of dest: '%s'\n", dest );
}
void myInvalidParameterHandler(
const wchar_t* expression,
const wchar_t* function,
const wchar_t* file,
unsigned int line,
uintptr_t pReserved)
{
wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}
int main( void )
{
_invalid_parameter_handler oldHandler, newHandler;
newHandler = myInvalidParameterHandler;
oldHandler = _set_invalid_parameter_handler(newHandler);
// Disable the message box for assertions.
_CrtSetReportMode(_CRT_ASSERT, 0);
Examples();
}
// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s
#include <stdio.h>
#include <stdlib.h>
int main( void )
{
char a[20] = "test";
char s[20];
// simple strncpy usage:
strcpy_s( s, 20, "dogs like cats" );
printf( "Original string:\n '%s'\n", s );
// Here we can't use strncpy_s since we don't
// want null termination
strncpy( s, "mice", 4 );
printf( "After strncpy (no null-termination):\n '%s'\n", s );
strncpy( s+5, "love", 4 );
printf( "After strncpy into middle of string:\n '%s'\n", s );
// If we use strncpy_s, the string is terminated
strncpy_s( s, _countof(s), "mice", 4 );
printf( "After strncpy_s (with null-termination):\n '%s'\n", s );
}
Эквивалент в .NET Framework
См. также
Ссылки
Интерпретация последовательностей многобайтового символов
strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l