将一个字符串的字符复制给另一个。strncpy、_strncpy_l、wcsncpy、_wcsncpy_l、_mbsncpy、_mbsncpy_l 的这些版本如 CRT 中的安全功能 所述,其安全得到了增强。
![]() |
---|
_mbsncpy_s 和 _mbsncpy_s_l 不能在 Windows 运行时中执行的应用程序中使用。 有关详细信息,请参见 CRT functions not supported with /ZW(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
这些函数想要复制 strSource 的第一个字符 D 到 strDest,D 是 count的较小值 和 strSource的长度。 如果这些 D 字符将适合于 strDest (其大小是 numberOfElements),仍然留出 null结束符的位置,然后这些字符被复制并追加null结束符;否则,strDest[0] 设置为在 null 字符和无效的参数调用处理程序,如 参数验证 验证描述。
与上面段有异常。 如果 count 是 _TRUNCATE,则相同数量的 strSource 将复制到 strDest,同时仍然保留 null 结束符的空间。
例如,
char dst[5];
strncpy_s(dst, 5, "a long string", 5);
意味着我们请求 strncpy_s 复制五个字符到五个字节的缓冲区;这不会留下 null 结束符的空间,因此 strncpy_s 只有0空间的字符串和调用无效参数处理程序。
如果截断行为是必需的,请使用 _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 相应地改变。 否则这六个函数具有相同行为。
输出值受区域设置的 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 做准备和不打算直接调用。 |
// 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(); }
原始字符串:
“dogs like cats”
在 strncpy 之后 (而非 null 结束符):
“mice like cats”
strncpy 转换为字符串中间:
”mice love cats“
在 strncpy_s 后 (包含 null 结束符):
“mice”