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

Copie los caracteres de una cadena en otra. Hay disponibles versiones más seguras de estas funciones; consulte strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l.

Sintaxis

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
Cadena de destino.

strSource
Cadena de origen.

count
Número de caracteres que se van a copiar.

locale
Configuración regional que se va a usar.

Valor devuelto

Devuelve strDest. No se reserva ningún valor devuelto para indicar un error.

Comentarios

La función strncpy copia los primeros count caracteres de strSource en strDest y devuelve strDest. Si count es menor o igual que la longitud de strSource, un carácter NULL no se anexa automáticamente a la cadena copiada. Si count es mayor que la longitud de strSource, a cadena de destino se completa con caracteres nulos hasta la longitud count. El comportamiento de strncpy no se define si las cadenas de origen y de destino se superponen.

Si strDest o strSource es un NULL puntero, o si count es menor o igual que cero, se invoca al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones devuelven -1 y establecen errno en EINVAL.

wcsncpy y _mbsncpy son versiones de caracteres anchos y multibyte de strncpy. Los argumentos y el valor devuelto de wcsncpy y _mbsncpy varían en consecuencia. Por lo demás, estas seis funciones se comportan exactamente igual.

Las versiones de estas funciones con el sufijo _l son idénticas salvo que usan la configuración regional pasada en lugar de la configuración regional de su comportamiento dependiente de la configuración regional. Para obtener más información, vea Locale.

En C++, estas funciones tienen sobrecargas de plantilla que invocan los homólogos seguros más recientes de estas funciones. Para obtener más información, consulte Sobrecargas de plantilla seguras.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Requisitos

Para obtener más información de compatibilidad de la plataforma, consulte Compatibilidad.

Ejemplo

En el ejemplo siguiente se muestra el uso de strncpy y cómo su uso incorrecto puede provocar errores de programa y problemas de seguridad. El compilador genera una advertencia para cada llamada a strncpy similar a crt_strncpy_x86.c(15) : Advertencia C4996: "strncpy": Esta función o variable puede no ser segura. Considere la posibilidad de usar strncpy_s en su lugar. Para deshabilitar el desuso, use _CRT_SECURE_NO_WARNINGS. Consulte la Ayuda en línea para más información.

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

Output

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')

El diseño de las variables automáticas y el nivel de detección de errores y protección del código pueden variar con la configuración de compilador modificada. Este ejemplo puede tener resultados diferentes si se crea en otros entornos de compilación o con otras opciones del compilador.

Consulte también

Manipulación de cadenas
Configuración regional
Interpretación de secuencias de caracteres de varios bytes
_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