funções strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

Artigo
08/25/2010

Copie caracteres de uma seqüência de caracteres para outro.Versões mais seguras dessas funções estão disponível; consulte strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l.

char *strncpy(
   char *strDest,
   const char *strSource,
   size_t count 
);
char *_strncpy_l(
   char *strDest,
   const char *strSource,
   size_t count,
   locale_t locale 
);
wchar_t *wcsncpy(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);
wchar_t *_wcsncpy_l(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
);
unsigned char *_mbsncpy(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count 
);
unsigned char *_mbsncpy_l(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
char *strncpy(
   char (&strDest)[size],
   const char *strSource,
   size_t count 
); // C++ only
template <size_t size>
char *_strncpy_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
wchar_t *wcsncpy(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
wchar_t *_wcsncpy_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

strDest
Seqüência de caracteres de destino.
strSource
Seqüência de caracteres de fonte.
count
Número de caracteres a serem copiados.
locale
Localidade usar.

Valor de retorno

RetornastrDest. Nenhum valor retornado é reservado para indicar um erro.

Comentários

The strncpy função copia a inicial count caracteres do strSource para strDest e retornos strDest. If count é menor ou igual ao comprimento do strSource, um caractere nulo não é automaticamente acrescentado à seqüência de caracteres copiada. If count é maior do que o comprimento de strSource, a seqüência de caracteres de destino é preenchida com caracteres nulo até comprimento count. O comportamento de strncpy é indefinido se sobreponham as seqüências de caracteres de fonte e destino.

Observação de segurança:
strncpy não verifica a existência de espaço suficiente no strDest; Portanto, é uma causa potencial de saturações de buffer. Tenha em mente que count limites de número de caracteres copiados; não é um limite no dimensionar do strDest. Consulte o exemplo abaixo.Para obter mais informações, consulte Evitar saturações de buffer.

If strDest ou strSource é um NULL ponteiro, ou se count é menor ou igual a zero, o manipulador de parâmetro inválido é invocado, sistema autônomo descrito em Validação de parâmetro. Se a execução for permitida para continuar, essas funções retornam -1 e conjunto errno para EINVAL

wcsncpy e _mbsncpysão versões de caractere largo e caracteres de multibyte de strncpy. Os argumentos e o valor retornado do wcsncpy e _mbsncpy variam de acordo. Esses seis funções se comportam exatamente caso contrário.

As versões dessas funções com o _l sufixo são idênticas exceto que eles usam a localidade do passado em vez da localidade corrente para seu comportamento dependente de localidade. For more information, see Localidade.

No C++, essas funções têm sobrecargas de modelo que invocam as suas similares do mais recentes, seguras dessas funções.For more information, see Proteger overloads de modelo.

Mapeamentos de rotina de texto genérica

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tcsncpy	strncpy	_mbsnbcpy	wcsncpy
_tcsncpy_l	_strncpy_l	_mbsnbcpy_l	_wcsncpy_l

Observação:
_strncpy_l e _wcsncpy_l não ter nenhuma dependência da localidade; eles são fornecidos apenas para _tcsncpy_l e não têm por objetivo ser chamado diretamente.

Requisitos

Rotina	Cabeçalho necessário
strncpy	<string.h>
wcsncpy	<string.h> ou <wchar.h>
_mbsncpy, _mbsncpy_l	<mbstring.h>

Para obter informações adicionais compatibilidade, consulte Compatibilidade na introdução.

Exemplo

// crt_strncpy_x86.c
// compile with: /WX /W3
// processor: x86
#include <stdio.h>
#include <string.h>

int main() {
   char a[20] = "test";
   char s[20];
   char *p = 0, *q = 0;

   strcpy_s( s, sizeof(s), "AA BB CC" );
   // Note: strncpy is deprecated; consider using strncpy_s instead
   strncpy( s, "aa", 2 );   // "aa BB CC"         C4996
   strncpy( s+3, "bb", 2 ); // "aa bb CC"         C4996
   strncpy( s, "ZZ", 3 );   // "ZZ",              C4996
                            // count greater than strSource, null added
   printf( "%s\n", s );

   strcpy_s( s, sizeof(s), "AA BB CC" );
   p = strstr(s, "BB");
   q = strstr(s, "CC");
   strncpy(s, "aa", p - s - 1);   // "aa BB CC"   C4996
   strncpy(p, "bb", q - p - 1);   // "aa bb CC"   C4996
   strncpy(q, "cc",  q - s);      // "aa bb cc"   C4996
   strncpy(q, "dd", strlen(q));   // "aa bb dd"   C4996
   printf( "%s\n", s );

   // some problems with strncpy
   strcpy_s( s, sizeof(s), "AA BB CC" );
   strncpy( s, "this is a very long string", 20 ); // C4996
   // Danger: at this point, s has no terminating null

   strcpy_s( s, sizeof(s), "dogs like cats" );
   strncpy( s+10, "to chase cars", 14); // C4996
   // strncpy has caused a buffer overrun and corrupted string a
   printf( "Buffer overrun: a = '%s' (should be 'test')\n", a );
   // In this case, a is just a char array, but if a were a function
   // pointer, this would be an exploitable buffer overrun.
}

ZZ aa bb dd Buffer overrun: a = 'ars' (should be 'test')

// crt_strncpy_x64.c
// compile with: /W3
// processor: x64 IPF
#include <stdio.h>
#include <string.h>

int main() {
   char a[20];
   char s[20];
   char b[20] = "test";
   char *p = 0, *q = 0;

   strcpy_s( s, sizeof(s), "AA BB CC" );
   // Note: strncpy is deprecated; consider using strncpy_s instead
   strncpy( s, "aa", 2 );   // "aa BB CC"         C4996
   strncpy( s+3, "bb", 2 ); // "aa bb CC"         C4996
   strncpy( s, "ZZ", 3 );   // "ZZ",              C4996
                            // count greater than strSource, null added
   printf( "%s\n", s );

   strcpy_s( s, sizeof(s), "AA BB CC" );
   p = strstr(s, "BB");
   q = strstr(s, "CC");
   strncpy(s, "aa", p - s - 1);   // "aa BB CC"   C4996
   strncpy(p, "bb", q - p - 1);   // "aa bb CC"   C4996
   strncpy(q, "cc",  q - s);      // "aa bb cc"   C4996
   strncpy(q, "dd", strlen(q));   // "aa bb dd"   C4996
   printf( "%s\n", s );

   // some problems with strncpy
   strcpy_s( s, sizeof(s), "AA BB CC" );
   strncpy( s, "this is a very long string", 20 ); // C4996
   // Danger: at this point, s has no terminating null

   strcpy_s( s, sizeof(s), "dogs like cats" );
   strncpy( s+10, "to chase cars and buses and things", 36);
   // strncpy has caused a buffer overrun and corrupted string b
   printf( "Buffer overrun: b = '%s' (should be 'test')\n", b );
   // In this case, b is just a char array, but if b were a function
   // pointer, this would be an exploitable buffer overrun.
}

ZZ aa bb dd Buffer overrun: b = 's and things' (should be 'test')