`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`

Artykuł
10/12/2023

Kopiuje znaki jednego ciągu do innego. Te wersje programu strncpy, _strncpy_l, _wcsncpy_lwcsncpy, _mbsncpy_mbsncpy_l mają ulepszenia zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Ważne

_mbsncpy_snie można jej _mbsncpy_s_l używać w aplikacjach wykonywanych w środowisko wykonawcze systemu Windows. Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane w aplikacjach platforma uniwersalna systemu Windows.

Składnia

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

Parametry

strDest
Ciąg docelowy.

numberOfElements
Rozmiar ciągu docelowego w postaci znaków.

strSource
Ciąg źródłowy.

count
Liczba znaków do skopiowania lub _TRUNCATE.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Zero w przypadku pomyślnego obcinania, STRUNCATE w przeciwnym razie kod błędu.

Warunki błędu

`strDest`	`numberOfElements`	`strSource`	Wartość zwracana	Zawartość `strDest`
`NULL`	dowolny	dowolny	`EINVAL`	niezmodyfikowane
dowolny	dowolny	`NULL`	`EINVAL`	`strDest[0]` ustaw wartość 0
dowolny	0	dowolny	`EINVAL`	niezmodyfikowane
Nie `NULL`	za mały	dowolny	`ERANGE`	`strDest[0]` ustaw wartość 0

Uwagi

Te funkcje próbują skopiować pierwsze D znaki do strDeststrSource , gdzie D jest mniejsza count i długość strSource. Jeśli te D znaki będą mieścić się w obrębie strDest (którego rozmiar jest podany jako numberOfElements) i nadal pozostawiają miejsce na terminator o wartości null, te znaki są kopiowane, a wartość null zakończenia jest dołączana; w przeciwnym razie strDest[0] jest ustawiona na znak null, a wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Walidacja parametru.

Istnieje wyjątek od powyższego akapitu. Jeśli count parametr ma _TRUNCATEwartość , zostanie skopiowana tyle strSource , ile będzie mieścić się w strDest pliku , podczas gdy nadal pozostawia miejsce na wartość null zakończenia, która jest zawsze dołączana.

Przykład:

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

oznacza, że strncpy_s kopiuje pięć znaków do buforu 5 bajtów. Ta kopia nie pozostawi miejsca dla terminatora o wartości null, więc strncpy_s zeruje ciąg i wywołuje nieprawidłową procedurę obsługi parametrów.

Jeśli wymagane jest zachowanie obcięcia, użyj polecenia _TRUNCATE lub (size - 1):

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

W przeciwieństwie do strncpyparametru strSource, jeśli count jest większa niż długość ciągu docelowego , ciąg docelowy NIE jest wypełniony znakami null o długości do długości count.

Zachowanie elementu strncpy_s jest niezdefiniowane, jeśli ciągi źródłowe i docelowe nakładają się na siebie.

Jeśli strDest parametr lub strSource ma NULLwartość lub numberOfElements ma wartość 0, wywoływana jest nieprawidłowa procedura obsługi parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja zwraca EINVAL i ustawia wartość errnoEINVAL.

wcsncpy_si _mbsncpy_s są wersjami znaków wielobajtowych i wielobajtowych .strncpy_s Argumenty i zwracana wartość wcsncpy_s i mbsncpy_s różnią się odpowiednio. Te sześć funkcji zachowuje się identycznie inaczej.

Na wartość wyjściową ma wpływ ustawienie LC_CTYPE ustawienia kategorii ustawień regionalnych. W celu uzyskania więcej informacji, zobacz następujący temat: setlocale. Wersje tych funkcji bez sufiksu _l używają bieżących ustawień regionalnych dla tego zachowania zależnego od ustawień regionalnych. Wersje z _l sufiksem są identyczne, z tą różnicą, że używają parametru ustawień regionalnych przekazanych zamiast. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

W języku C++używanie tych funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując konieczność określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje nowszymi, bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Wersje biblioteki debugowania tych funkcji najpierw wypełniają bufor 0xFE. Aby wyłączyć to zachowanie, użyj polecenia _CrtSetDebugFillThreshold.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

`TCHAR.H` Rutynowych	`_UNICODE` i `_MBCS` niezdefiniowane	`_MBCS` Zdefiniowane	`_UNICODE` Zdefiniowane
`_tcsncpy_s`	`strncpy_s`	`_mbsnbcpy_s`	`wcsncpy_s`
`_tcsncpy_s_l`	`_strncpy_s_l`	`_mbsnbcpy_s_l`	`_wcsncpy_s_l`

Uwaga

_strncpy_s_li _wcsncpy_s_l_mbsncpy_s_l nie mają zależności od ustawień regionalnych. Są one udostępniane tylko dla _tcsncpy_s_l i nie mają być wywoływane bezpośrednio.

Wymagania

Procedura	Wymagany nagłówek
`strncpy_s`, `_strncpy_s_l`	`<string.h>`
`wcsncpy_s`, `_wcsncpy_s_l`	`<string.h>` lub `<wchar.h>`
`_mbsncpy_s`, `_mbsncpy_s_l`	`<mbstring.h>`

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład: kopiowanie znaków do buforu

// 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: ''

Przykład: `strncpy` i `strncpy_s`

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

Zobacz też

Manipulowanie ciągami
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
_mbsnbcpy, _mbsnbcpy_l
strcat_s, wcscat_s, _mbscat_s
strcmp, wcscmp, _mbscmp
strcpy_s, wcscpy_s, _mbscpy_s
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
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l

`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`

Składnia

Parametry

Wartość zwracana

Warunki błędu

Uwagi

Mapowania procedur tekstu ogólnego

Wymagania

Przykład: kopiowanie znaków do buforu

Przykład: `strncpy` i `strncpy_s`

Zobacz też

Opinia

Opinia

Dodatkowe zasoby

strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Składnia

Parametry

Wartość zwracana

Warunki błędu

Uwagi

Mapowania procedur tekstu ogólnego

Wymagania

Przykład: kopiowanie znaków do buforu

Przykład: strncpy i strncpy_s

Zobacz też

Opinia

Opinia

Dodatkowe zasoby

`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`

Przykład: `strncpy` i `strncpy_s`