将一个字符串的字符复制到另一个字符串。 这些版本的 strncpy、_strncpy_l、wcsncpy、_wcsncpy_l、_mbsncpy、_mbsncpy_l 具有安全增强功能，如 CRT 中的安全功能中所述。
重要
_mbsncpy_s 和 _mbsncpy_s_l 无法用于在 Windows 运行时中执行的应用程序。 有关详细信息，请参阅通用 Windows 平台应用中不支持的 CRT 函数。
有关 _tcsnccpy_s、 _tcsnccpy_s_l、 _tcsnccpy_s和 _tcsnccpy_s_l 查看 泛型文本函数映射。
语法
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
errno_t strncpy_s(
char (&strDest)[size],
const char *strSource,
size_t count
); // C++ only
template
errno_t _strncpy_s_l(
char (&strDest)[size],
const char *strSource,
size_t count,
_locale_t locale
); // C++ only
template
errno_t wcsncpy_s(
wchar_t (&strDest)[size],
const wchar_t *strSource,
size_t count
); // C++ only
template
errno_t _wcsncpy_s_l(
wchar_t (&strDest)[size],
const wchar_t *strSource,
size_t count,
_locale_t locale
); // C++ only
template
errno_t _mbsncpy_s(
unsigned char (&strDest)[size],
const unsigned char *strSource,
size_t count
); // C++ only
template
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
any
any
EINVAL
未修改
any
any
NULL
EINVAL
strDest[0]：设置为 0
任意
0
any
EINVAL
未修改
非 NULL
过小
任意
ERANGE
strDest[0]：设置为 0
备注
这些函数尝试将 strSource 的前 D 个字符复制到 strDest，其中 D 是 count 和 strSource 长度中较小的一个。 如果这些 D 字符适合 strDest（其大小为 numberOfElements），并且仍为 null 终止符留出空间，则复制这些字符并附加一个终止 null；否则，strDest[0] 将设置为空字符，并调用无效参数处理程序，如参数验证中所述。
上面的段落有一个例外。 如果 count 为 _TRUNCATE，那么将复制适合 strDest 的尽可能多的strSource，同时仍为终止 null 留出空间，始终追加该 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 长度前，不会用 null 字符填补目标字符串。
如果源和目标字符串重叠，则 strncpy_s 的行为是未定义的。
如果 strDest 或 strSource 是 NULL，或者 numberOfElements 是 0，则会调用无效的参数处理程序。 如果允许继续执行，则函数将返回 EINVAL，并且将 errno 设置为 EINVAL。
wcsncpy_s 和 _mbsncpy_s 分别是 strncpy_s 的宽字符及多字节字符版本。 wcsncpy_s 和 mbsncpy_s 的参数和返回值将相应变化。 否则这六个函数具有相同行为。
输出值受区域设置的 LC_CTYPE 类别设置的影响。 有关详细信息，请参阅 setlocale。 这些不带 _l 后缀的函数的版本使用为该区域设置相关的行为的当前区域设置；带有 _l 后缀的版本相同，只不过它们使用传递的区域设置参数。 有关详细信息，请参阅 Locale。
在 C++ 中，使用这些函数由模板重载简化；重载可以自动推导出缓冲区长度 (不再需要指定大小自变量)，并且它们可以自动用以更新、更安全的对应物替换旧的、不安全的函数。 有关详细信息，请参阅安全模板重载。
这些函数的调试库版本首先用 0xFE 填充缓冲区。 若要禁用此行为，请使用 _CrtSetDebugFillThreshold。
默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。
泛型文本函数映射
列中的 tchar.h 函数映射到其他列中的函数，具体取决于编译时定义的字符集。
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
_tcsnccpy_s
strncpy_s
_mbsncpy_s
_wcsncpy_s
_tcsnccpy_s_l
_strncpy_s_l
_mbsncpy_s_l
_wcsncpy_s_l
注意
_strncpy_s_l、_wcsncpy_s_l 和 _mbsncpy_s_l 没有区域设置依赖性。 它们只是为 _tcsncpy_s_l 提供的，不打算直接调用。
要求
例程
必需的标头
strncpy_s, _strncpy_s_l
wcsncpy_s, _wcsncpy_s_l
_mbsncpy_s, _mbsncpy_s_l
有关兼容性的详细信息，请参阅 兼容性。
示例：将字符复制到缓冲区
// 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
#include
#include
#include
#include
// 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();
}
Copying 4 chars of 'howdy' to 10-byte buffer dest
new contents of dest: 'howd'
Copying 5 chars of 'howdy' to 10-byte buffer dest
new contents of dest: 'howdy'
Copying 6 chars of 'howdy' to 10-byte buffer dest
new contents of dest: 'howdy'
Destination buffer too small:
Copying 10 chars of 'Hi there!!' to 10-byte buffer dest
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
new contents of dest: ''
Truncation examples:
Copying 'How do you do?' to 10-byte buffer dest with truncation semantics
new contents of dest: 'How do yo'
truncation did occur
Copying 'Howdy.' to 10-byte buffer dest with truncation semantics
new contents of dest: 'Howdy.'
truncation did not occur
Secure template overload example:
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
new contents of dest: ''
示例：strncpy 和 strncpy_s
// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s
#include
#include
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 );
}
Original string:
'dogs like cats'
After strncpy (no null-termination):
'mice like cats'
After strncpy into middle of string:
'mice love cats'
After strncpy_s (with null-termination):
'mice'
另请参阅
字符串操作
区域设置
多字节字符序列的解释
_mbsnbcpy, _mbsnbcpy_l
strcat_s、 wcscat_s、、 _mbscat_s
strcmp、 wcscmp、、 _mbscmp
strcpy_s、 wcscpy_s、、 _mbscpy_s
strncat_s、、_strncat_s_lwcsncat_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
_strset、、_strset_l_wcsset、_wcsset_l、_mbsset、_mbsset_l
strspn、、wcsspn_mbsspn、、_mbsspn_l