strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Artigo
06/09/2015

Copia caracteres de uma cadeia de caracteres para outra. Essas versões de strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

_mbsncpy_s e _mbsncpy_s_l não podem ser usados em aplicativos executados no Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /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

Parâmetros

strDest
Cadeia de caracteres de destino.
numberOfElements
O tamanho da cadeia de caracteres de destino, em caracteres.
strSource
Cadeia de caracteres de origem.
count
Número de caracteres a serem copiados, ou _TRUNCATE.
locale
A localidade a ser usada.

Valor de retorno

Zero se tiver êxito, STRUNCATE se houver truncamento, se não for um código de erro.

Condições de erro

strDest	numberOfElements	strSource	Valor de retorno	Conteúdo de strDest
NULL	any	any	EINVAL	não modificado
any	any	NULL	EINVAL	strDest[0] definido como 0
any	0	any	EINVAL	não modificado
não NULL	muito pequeno	any	ERANGE	strDest[0] definido como 0

Comentários

Essas funções tentam copiar os primeiros caracteres de D de strSource a strDest, onde D é o menor de count e o comprimento de strSource. Se esses caracteres de D se ajustarem dentro de strDest (cujo tamanho é fornecido como numberOfElements) e deixar ainda de espaço para um terminador nulo, esses caracteres serão copiados e um nulo de término está anexado; caso contrário, strDest[0] é definido como o caractere nulo e o manipulador inválido do parâmetro é chamado, conforme descrito em Validação do parâmetro.

Há uma exceção no parágrafo anterior. Se count é _TRUNCATE, então tanto quanto de strSource quanto caiba em strDest é copiado para o ainda deixar de espaço para o encerramento zero que é anexado sempre.

Por exemplo,

char dst[5];

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

significa que nós estamos solicitando strncpy_s para copiar long cinco caracteres em um buffer cinco bytes; isso não permite nenhum espaço para o terminador, portanto os zeros nulos de strncpy_s para substituir a cadeia de caracteres e chama o manipulador inválido do parâmetro.

Se o comportamento de truncamento é necessário, use _TRUNCATE ousize (– 1):

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

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

Observe que ao contrário de strncpy, se count for maior que o comprimento de strSource, a cadeia de caracteres de destino não for preenchido com caracteres nulos até o comprimento count.

O comportamento de strncpy_s será indefinido se as cadeias de caracteres de origem e de destino se sobrepuserem.

Se strDest ou strSource são NULL, ou numberOfElements é 0, o manipulador inválido do parâmetro é invocado. Se a execução puder continuar, a função retornará EINVAL e definirá errno como EINVAL.

wcsncpy_s e _mbsncpy_s são versões de caracteres largos e de multibyte de strncpy_s. Os argumentos e o valor de retorno de wcsncpy_s e mbsncpy_svariam de acordo. Essas seis funções se comportam idêntica de outra forma.

O valor de saída é afetado pela configuração da categoria LC_CTYPE de localidade. Para obter mais informações, consulte setlocale. As versões dessas funções sem o sufixo _l usam a localidade atual para esse comportamento dependente da localidade; as versões com o sufixo _l são idênticas, exceto que elas usam o parâmetro de localidade informado. Para obter mais informações, consulte Localidade.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de depuração dessas funções preenchem primeiro o buffer com 0xFD. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tcsncpy_s	strncpy_s	_mbsnbcpy_s	wcsncpy_s
_tcsncpy_s_l	_strncpy_s_l	_mbsnbcpy_s_l	_wcsncpy_s_l

Dica

o _strncpy_s_l, _wcsncpy_s_l e _mbsncpy_s_l não têm dependências de localidade e são fornecidos apenas para _tcsncpy_s_l e não se destinam ser chamados diretamente.

Requisitos

Rotina	Cabeçalho necessário
strncpy_s, _strncpy_s_l	<string.h>
wcsncpy_s, _wcsncpy_s_l	<string.h> ou <wchar.h>
_mbsncpy_s, _mbsncpy_s_l	<mbstring.h>

Para informações adicionais de compatibilidade, consulte Compatibilidade.

Exemplo

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

}