strncpy_s、_strncpy_s_l、wcsncpy_s、_wcsncpy_s_l、_mbsncpy_s、_mbsncpy_s_lstrncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

文字列の文字を他の文字列にコピーします。Copies characters of one string to another. これらの strncpy、_strncpy_l、wcsncpy、_wcsncpy_l、_mbsncpy、_mbsncpy_l のバージョンは、「CRT のセキュリティ機能」で説明されているように、セキュリティが強化されています。These versions of strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l have security enhancements, as described in Security Features in the CRT.

重要

_mbsncpy_s_mbsncpy_s_l Windows ランタイムで実行するアプリケーションでは使用できません。_mbsncpy_s and _mbsncpy_s_l cannot be used in applications that execute in the Windows Runtime. 詳細については、「ユニバーサル Windows プラットフォーム アプリでサポートされていない CRT 関数」を参照してください。For more information, see CRT functions not supported in Universal Windows Platform apps.

構文Syntax

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

パラメーターParameters

strDeststrDest
対象文字列。Destination string.

numberOfElementsnumberOfElements
対象文字列のサイズ (文字数)。The size of the destination string, in characters.

strSourcestrSource
ソース文字列。Source string.

countcount
コピーする文字数または _TRUNCATENumber of characters to be copied, or _TRUNCATE.

localelocale
使用するロケール。The locale to use.

戻り値Return Value

成功した場合は 0 STRUNCATE切り捨てが発生した場合、それ以外の場合、エラー コード。Zero if successful, STRUNCATE if truncation occurred, otherwise an error code.

エラー条件Error Conditions

strDeststrDest numberOfElementsnumberOfElements strSourcestrSource 戻り値Return value 内容追加される文字Contents of strDest
NULLNULL 任意any 任意any EINVALEINVAL 変更されないnot modified
任意any 任意any NULLNULL EINVALEINVAL 追加される文字[0] が 0 に設定strDest[0] set to 0
任意any 00 任意any EINVALEINVAL 変更されないnot modified
いないNULLnot NULL 小さすぎるtoo small 任意any ERANGEERANGE 追加される文字[0] が 0 に設定strDest[0] set to 0

RemarksRemarks

これらの関数が 1 つ目のコピーを試行Dの文字strSource追加される文字ここで、 Dはより小さく、の長さとstrSourceします。These functions try to copy the first D characters of strSource to strDest, where D is the lesser of count and the length of strSource. 場合は、これらD内に収まる文字追加される文字(として、サイズが指定numberOfElements) これらの文字をコピーし、引き続き、null の終端文字の分のままにして終端の null が追加されます。それ以外の場合、追加される文字[0] 設定は、null 文字を無効なパラメーター ハンドラーが呼び出される」の説明に従ってパラメーターの検証です。If those D characters will fit within strDest (whose size is given as numberOfElements) and still leave room for a null terminator, then those characters are copied and a terminating null is appended; otherwise, strDest[0] is set to the null character and the invalid parameter handler is invoked, as described in Parameter Validation.

これには例外があります。There is an exception to the above paragraph. 場合カウント_TRUNCATE、だけのstrSourceに収まる追加される文字の空きを残して、コピーが、追加される常に null を終了しています。If count is _TRUNCATE, then as much of strSource as will fit into strDest is copied while still leaving room for the terminating null which is always appended.

例えば以下のようにします。For example,

char dst[5];
strncpy_s(dst, 5, "a long string", 5);

確認していることを意味strncpy_s 5 つをコピーする文字をバッファーに 5 バイト長これは余裕がありません、null の終端ためstrncpy_s 、文字列をゼロと無効な呼び出し。パラメーターのハンドラー。means that we are asking strncpy_s to copy five characters into a buffer five bytes long; this would leave no space for the null terminator, hence strncpy_s zeroes out the string and calls the invalid parameter handler.

切り捨て動作が必要な場合は _TRUNCATEまたは (サイズ- 1)。If truncation behavior is needed, use _TRUNCATE or (size - 1):

strncpy_s(dst, 5, "a long string", _TRUNCATE);
strncpy_s(dst, 5, "a long string", 4);

異なりstrncpy場合は、カウントがの長さより大きいstrSource、コピー先文字列がまでnull文字が埋め込まれませんカウントします。Note that unlike strncpy, if count is greater than the length of strSource, the destination string is NOT padded with null characters up to length count.

動作strncpy_s元とコピー先文字列が重なり合う場合は定義されません。The behavior of strncpy_s is undefined if the source and destination strings overlap.

場合追加される文字またはstrSourceNULL、またはnumberOfElementsが 0 の場合、無効なパラメーター ハンドラーが呼び出されます。If strDest or strSource is NULL, or numberOfElements is 0, the invalid parameter handler is invoked. かどうかは、引き続き実行が許可された、関数を返しますEINVAL設定とerrnoEINVALします。If execution is allowed to continue, the function returns EINVAL and sets errno to EINVAL.

wcsncpy_s_mbsncpy_sのワイド文字とマルチバイト文字バージョンstrncpy_sします。wcsncpy_s and _mbsncpy_s are wide-character and multibyte-character versions of strncpy_s. 引数と戻り値のwcsncpy_smbsncpy_sはそれに応じて異なります。The arguments and return value of wcsncpy_s and mbsncpy_s do vary accordingly. それ以外では、これらの関数の動作は同じです。These six functions behave identically otherwise.

出力値は、ロケールの LC_CTYPE カテゴリの設定に影響されます。詳細については、「setlocale」を参照してください。The output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale for more information. _l サフィックスが付いていないこれらの関数のバージョンでは、このロケールに依存する動作に現在のロケールを使用します。_l サフィックスが付いているバージョンは、渡されたロケール パラメーターを代わりに使用する点を除いて同じです。The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. 詳細については、「 Locale」を参照してください。For more information, see Locale.

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

これらの関数のデバッグ バージョンは、最初にバッファーを 0xFD で埋めます。The debug versions of these functions first fill the buffer with 0xFD. この動作を無効にするには、_CrtSetDebugFillThreshold を使用します。To disable this behavior, use _CrtSetDebugFillThreshold.

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_tcsncpy_s_tcsncpy_s strncpy_sstrncpy_s _mbsnbcpy_s_mbsnbcpy_s wcsncpy_swcsncpy_s
_tcsncpy_s_l_tcsncpy_s_l _strncpy_s_l_strncpy_s_l _mbsnbcpy_s_l_mbsnbcpy_s_l _wcsncpy_s_l_wcsncpy_s_l

注意

_strncpy_s_l_wcsncpy_s_l_mbsncpy_s_lロケールの依存関係がない、だけで提供されて _tcsncpy_s_lとするものはありません直接呼び出されます。_strncpy_s_l, _wcsncpy_s_l and _mbsncpy_s_l have no locale dependence and are provided just for _tcsncpy_s_l and are not intended to be called directly.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
strncpy_s_strncpy_s_lstrncpy_s, _strncpy_s_l <string.h><string.h>
wcsncpy_s_wcsncpy_s_lwcsncpy_s, _wcsncpy_s_l <string.h> または <wchar.h><string.h> or <wchar.h>
_mbsncpy_s, _mbsncpy_s_l_mbsncpy_s, _mbsncpy_s_l <mbstring.h><mbstring.h>

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

// 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();
}
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: ''

Example

// 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 );

}
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'

関連項目See also

文字列操作String Manipulation
ロケールLocale
マルチバイト文字のシーケンスの解釈Interpretation of Multibyte-Character Sequences
_mbsnbcpy、_mbsnbcpy_l_mbsnbcpy, _mbsnbcpy_l
strcat_s、wcscat_s、_mbscat_sstrcat_s, wcscat_s, _mbscat_s
strcmp、wcscmp、_mbscmpstrcmp, wcscmp, _mbscmp
strcpy_s、wcscpy_s、_mbscpy_sstrcpy_s, wcscpy_s, _mbscpy_s
strncat_s、_strncat_s_l、wcsncat_s、_wcsncat_s_l、_mbsncat_s、_mbsncat_s_lstrncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l
strncmp、wcsncmp、_mbsncmp、_mbsncmp_lstrncmp, wcsncmp, _mbsncmp, _mbsncmp_l
_strnicmp、_wcsnicmp、_mbsnicmp、_strnicmp_l、_wcsnicmp_l、_mbsnicmp_l_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr、wcsrchr、_mbsrchr、_mbsrchr_lstrrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset、_strset_l、_wcsset、_wcsset_l、_mbsset、_mbsset_l_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn、wcsspn、_mbsspn、_mbsspn_lstrspn, wcsspn, _mbsspn, _mbsspn_l