strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

Artigo
06/09/2015

Caracteres de cópia de uma cadeia de caracteres para outra. Versões mais seguras dessas funções estão disponíveis; consulte strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l.

Importante

_mbsncpy e _mbsncpy_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.

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
Cadeia de caracteres de destino.
strSource
Cadeia de caracteres de origem.
count
Número de caracteres a serem copiados.
locale
Localidade a ser usada.

Valor de retorno

Retorna strDest. Nenhum valor de retorno é reservado para indicar um erro.

Comentários

A função de strncpy copia os caracteres iniciais de count de strSource a strDest e retorna strDest. Se count é menor ou igual ao comprimento de strSource, um caractere nulo não é acrescentado automaticamente à cadeia de caracteres copiada. Se count for maior que o comprimento de strSource, a cadeia de caracteres de destino é preenchida com caracteres nulos até o comprimento count. O comportamento de strncpy será indefinido se as cadeias de caracteres de origem e de destino se sobrepuserem.

Observação de segurança
strncpy não verifica se há espaço suficiente em strDest; isso torna uma causa potencial de excesso de buffer.O argumento de count limita o número de caracteres copiados; não é um limite para o tamanho de strDest.Consulte o exemplo a seguir.Para obter mais informações, consulte Evitando saturações de buffer.

Se strDest ou strSource é um ponteiro de NULL , ou se count é menor ou igual a zero, o manipulador inválido do parâmetro será chamado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções retornarão -1 e definirão errno a EINVAL

wcsncpy e _mbsncpy são versões de caracteres largos e de multibyte de strncpy. Os argumentos e o valor de retorno de wcsncpy e _mbsncpy variam de acordo. Essas seis funções se comportam idêntica de outra forma.

As versões dessas funções com o sufixo _l são idênticas, exceto que elas usam a localidade informada em vez da localidade atual de seu comportamento dependente da localidade. Para obter mais informações, consulte Localidade.

No C++, essas funções têm as sobrecargas de modelo que invocam as correspondentes seguras mais recentes dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos da rotina de texto genérico

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

Dica

_strncpy_l e _wcsncpy_l não têm dependências de localidade; são fornecidos apenas para _tcsncpy_l e não se destinam ser chamados diretamente.

Requisitos

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

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

Exemplo

O exemplo a seguir demonstra o uso de strncpy e como pode ser implantada incorretamente para causar bugs e problemas de segurança do programa. O compilador gerencie um aviso para cada chamada a strncpy semelhante ao crt_strncpy_x86.c(15) : warning C4996: 'strncpy': This function or variable may be unsafe. Consider using strncpy_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.

// crt_strncpy_x86.c
// Use this command in an x86 developer command prompt to compile: 
// cl /TC /W3 crt_strncpy_x86.c

#include <stdio.h>
#include <string.h>

int main() {
   char t[20];
   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), "test");
   strncpy(t, "this is a very long string", 20 ); // C4996
   // Danger: at this point, t has no terminating null,
   // so the printf continues until it runs into one.
   // In this case, it will print "this is a very long test"
   printf("%s\n", t);

   strcpy_s(t, sizeof(t), "dogs like cats");
   printf("%s\n", t);

   strncpy(t + 10, "to chase cars.", 14); // C4996
   printf("%s\n", t);

   // strncpy has caused a buffer overrun and corrupted string s
   printf("Buffer overrun: s = '%s' (should be 'test')\n", s);
   // Since the stack grows from higher to lower addresses, buffer
   // overruns can corrupt function return addresses on the stack,
   // which can be exploited to run arbitrary code.
}

Saída

O layout de variáveis automático e o nível de detecção de erros e de proteção do código pode variar com configurações alteradas do compilador. Este exemplo pode ter resultados diferentes quando interno outros ambientes de criação ou com outras opções do compilador.