strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Artykuł
06/09/2015

Kopiowanie znaków z jednego ciągu do innego. Te wersje strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w CRT.

Ważne
_mbsncpy_s i _mbsncpy_s_l nie można używać w aplikacjach korzystających ze środowiska wykonawczego systemu Windows.Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane przez /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

Parametry

strDest
Ciąg docelowy.
numberOfElements
Rozmiar ciągu docelowego, w znakach.
strSource
Ciąg źródłowy.
count
Liczba znaków, które mają być skopiowane lub _TRUNCATE.
locale
Ustawienia regionalne do użycia.

Wartość zwracana

Jeżeli operacja się powiedzie zero, jeżeli wystąpi obcięcie STRUNCATE, w przeciwnym razie kod błędu.

Warunki błędów

strDest	numberOfElements	strSource	Wartość zwrócona	ZawartośćstrDest
NULL	jakakolwiek	jakakolwiek	EINVAL	nie zmodyfikowano
jakakolwiek	jakakolwiek	NULL	EINVAL	strDest[0] ustawiony na 0
jakakolwiek	0	jakakolwiek	EINVAL	nie zmodyfikowano
inna niż NULL	za mała	jakakolwiek	ERANGE	strDest[0] ustawiony na 0

Uwagi

Funkcje te próbują kopiować pierwsze D znaków z strSource do strDest, gdzie D jest wartością minimalną z count i długości strSource.Jeśli te D znaków zmieści się w strDest (którego rozmiar jest określony jako numberOfElements) i nadal pozostawia miejsce dla znaku kończącego null, to następnie te znaki są kopiowane i znak kończący null jest dodawany; w przeciwnym razie strDest[0] jest ustawiony na znak null i zostanie wywołana procedura obsługi nieprawidłowego parametru, zgodnie z opisem w Sprawdzanie poprawności parametru.

Istnieje wyjątek od powyższego akapitu.Jeśli count jest _TRUNCATE, następnie tyle strSource ile zmieści się w strDest jest kopiowane, pozostawiając miejsce dla kończącego znaku null, który jest zawsze dołączany.

Na przykład:

char dst[5];

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

oznacza, że prosimy strncpy_s o skopiowanie pięciu znaków do buforu o długości pięciu bajtów; to może oznaczać brak miejsca dla znaku kończącego null, w skutek czego strncpy_s wypełnia ciąg zerami i wywołuje procedurę obsługi nieprawidłowego parametru.

Jeśli wymagane jest zachowanie polegające na obcinaniu, należy użyć _TRUNCATE lub (size -1):

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

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

Należy zauważyć, że w przeciwieństwie do strncpy, jeśli count jest większa niż długość strSource, ciąg docelowy nie jest wypełniany znakami null do długości count.

Zachowanie strncpy_s jest niezdefiniowane, jeżeli ciągi źródłowe i docelowe nakładają się.

Jeśli strDest lub strSource jest NULL, lub numberOfElements jest 0, wywoływana jest procedura obsługi nieprawidłowego parametru.Jeśli wykonanie może być kontynuowane, funkcja zwraca EINVAL i ustawia errno jako EINVAL.

wcsncpy_s i _mbsncpy_s są wersjami znaków dwubajtowych i znaków wielobajtowych strncpy_s.Argumenty i wartości zwracane przez wcsncpy_s i mbsncpy_sróżnią się odpowiednio.W innych przypadkach te sześć funkcji zachowuje się identycznie.

Wartość wyjściowa jest zależna od konfiguracji ustawień kategorii LC_CTYPE ustawień regionalnych; zobacz setlocale, aby uzyskać więcej informacji.Wersje tych funkcji, które nie mają przyrostka _l używają bieżących ustawień regionalnych dla wszelkich zachowań zależnych od ustawień lokalnych; wersje, które mają przyrostek _l są identyczne, z tą różnicą, że w zamian korzystają z przekazanego parametru ustawień regionalnych.Aby uzyskać więcej informacji, zobacz Regionalne.

W języku programowania C++ korzystanie z tych funkcji jest uproszczone przez przeciążania szablonu; przeciążania mogą automatycznie wywnioskować długość buforu (tak, aby nie było konieczne określenie argumentu rozmiaru), ponadto te funkcje mogą automatycznie zastąpić starsze, niezabezpieczone funkcje nowszymi, bardziej bezpiecznymi odpowiednikami.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

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

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_tcsncpy_s	strncpy_s	_mbsnbcpy_s	wcsncpy_s
_tcsncpy_s_l	_strncpy_s_l	_mbsnbcpy_s_l	_wcsncpy_s_l

[!UWAGA]

_strncpy_s_l, _wcsncpy_s_l i _mbsncpy_s_l nie mają zależności w ustawieniach regionalnych i są dostarczane tylko dla _tcsncpy_s_l i nie są przeznaczone do bezpośredniego wywoływania.

Wymagania

Procedura	Wymagany nagłówek
strncpy_s, _strncpy_s_l	<Ciąg>
wcsncpy_s, _wcsncpy_s_l	<ciągo.h> lub <wchar.h>
_mbsncpy_s, _mbsncpy_s_l	<mbCiąg.h>

Dodatkowe informacje o zgodności – zobacz: Zgodność.

Przykład

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

}