strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, , _mbsncpy_l

Copia caracteres de uma cadeia de caracteres para outra. Estão disponíveis versões mais seguras dessas funções. Para obter informações, confira 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 Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

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
O número de caracteres a ser copiado.

locale
Localidade a usar.

Valor retornado

Retorna strDest. Nenhum valor retornado é reservado para indicar um erro.

Comentários

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

Importante

strncpy não verifica se há espaço suficiente em strDest; isso torna uma causa potencial de sobrecargas de buffer. O argumento count limita o número de caracteres acrescentado; não é um limite no tamanho de strDest. Veja o exemplo a seguir. Para obter mais informações, confira Como evitar sobrecargas de buffer.

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

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

As versões dessas funções com o sufixo _l são idênticas, exceto por usarem a localidade passada em vez da localidade atual para seu comportamento que depende da localidade. Para obter mais informações, consulte Localidade.

No C++, essas funções têm sobrecargas de modelo que invocam os equivalentes mais novos e seguros dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _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 têm nenhuma dependência de localidade; são fornecidas apenas para _tcsncpy_l e não se destinam a serem chamadas diretamente.

Requisitos

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

Para obter mais informações sobre compatibilidade de plataforma, consulte Compatibilidade.

Exemplo

O exemplo a seguir demonstra o uso de strncpy e como ele pode ser usado indevidamente para causar bugs de programa e problemas de segurança. O compilador gera um aviso para cada chamada de strncpy semelhante a crt_strncpy_x86.c(15): aviso C4996: "strncpy": essa função ou variável pode não ser segura. Considere usar strncpy_s. Para desabilitar o preterimento, use _CRT_SECURE_NO_WARNINGS. Veja a ajuda online para obter detalhes.

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

ZZ
aa bb dd
this is a very long test
dogs like cats
dogs like to chase cars.
Buffer overrun: s = 'ars.' (should be 'test')

O layout de variáveis automáticas, o nível de proteção de detecção e o código de erro podem variar com as configurações de compilador alteradas. Este exemplo pode ter resultados diferentes quando criados em outros ambientes de compilação ou com outras opções do compilador.

Confira também

Manipulação de cadeia de caracteres
Localidade
Interpretação de sequências de caracteres multibyte
_mbsnbcpy, _mbsnbcpy_l
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
strcpy, wcscpy, _mbscpy
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, , _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, , _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, , _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l
strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, , _mbsncpy_s_l
strcpy_s, wcscpy_s, _mbscpy_s