strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

Artigo
03/12/2013

Caracteres de impressão de uma cadeia de caracteres para outra.Versões mais seguros 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 em Tempo de Execução do Windows.Para obter mais informações, consulte Funções de CRT não suportadas com /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
A localidade usar.

Valor de retorno

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

Comentários

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

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

Se strDest ou strSource são um ponteiro de NULL , ou se count é menor ou igual a zero, o manipulador inválido do parâmetro é invocado, como descrito em Validação de parâmetro.Se a execução é permitida continuar, essas funções retornam -1 e errno definido como EINVAL

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

As versões dessas funções com o sufixo de _l são idênticas exceto que usam a localidade passada em vez de localidade atual para o comportamento do são dependentes.Para obter mais informações, consulte Localidade.

Em C++, essas funções têm as sobrecargas de modelo que chamam as novas contrapartes mais seguros, essas funções.Para obter mais informações, consulte Proteger Overloads de modelo.

Mapeamentos da rotina de Genérico- texto

Rotina de TCHAR.H	_UNICODE & _MBCS não definidos	_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 dependerem de localidade; são fornecidos apenas para _tcsncpy_l e não precisam 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 extras de compatibilidade da plataforma, consulte Compatibilidade.

Exemplo

O exemplo a seguir demonstra o uso de strncpy e como ele pode ser empregado errado para causar erros e problemas de segurança do programa.O compilador gerará 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

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