strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Artículo
06/09/2015

Copia caracteres de una cadena en otra. Estas versiones de strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

Importante

_mbsncpy_s y _mbsncpy_s_l no se pueden usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución.Para obtener más información, vea Funciones de CRT no admitidas con /ZW.

errno_t strncpy_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncpy_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncpy_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count 
);
errno_t _wcsncpy_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncpy_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count 
);
errno_t _mbsncpy_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   locale_t locale
);
template <size_t size>
errno_t strncpy_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncpy_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncpy_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcsncpy_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncpy_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbsncpy_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   locale_t locale
); // C++ only

Parámetros

strDest
Cadena de destino.
numberOfElements
Tamaño, en caracteres, de la cadena de destino.
strSource
Cadena de origen.
count
Número de caracteres que se van a copiar, o _TRUNCATE.
locale
Configuración regional que se va a usar.

Valor devuelto

Cero si la operación se ejecuta correctamente, STRUNCATE si se produjo truncamiento; en los demás casos, código de error.

Condiciones de error

strDest	numberOfElements	strSource	Valor devuelto	Contenido de strDest
NULL	any	any	EINVAL	no modificado
any	any	NULL	EINVAL	strDest[0] se establece en 0
any	0	any	EINVAL	no modificado
no NULL	demasiado pequeño	any	ERANGE	strDest[0] se establece en 0

Comentarios

Estas funciones intentan copiar los primeros caracteres D de strSource en strDest, donde D es el valor menor de count y la longitud de strSource. Si esos caracteres D caben en strDest (cuyo tamaño se da como numberOfElements) y queda espacio para un terminador nulo, dichos caracteres se copian y se anexa un carácter nulo final; de lo contrario, strDest[0] se establece en el carácter nulo y se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros.

Existe una excepción al comportamiento anterior. Si count es _TRUNCATE, toda la parte de strSource que quepa en strDest se copia, dejando espacio para carácter nulo final, que se anexa siempre.

Por ejemplo,

char dst[5];

strncpy_s(dst, 5, "a long string", 5);

indica que deseamos que strncpy_s copie cinco caracteres en un búfer de cinco bytes de longitud; así no quedaría espacio para el terminador nulo, por lo que strncpy_s pone la cadena a cero y llama al controlador de parámetros no válidos.

Si el comportamiento de truncamiento es necesario, use _TRUNCATE o (size – 1):

strncpy_s(dst, 5, "a long string", _TRUNCATE);

strncpy_s(dst, 5, "a long string", 4);

Observe que a diferencia de strncpy, si count es mayor que la longitud de strSource, la cadena de destino no se completa con caracteres nulos hasta tener la longitud de count.

El comportamiento de strncpy_s no se define si las cadenas de origen y de destino se superponen.

Si strDest o strSource es NULL, o numberOfElements es 0, se invoca el controlador de parámetros no válidos. Si la ejecución puede continuar, la función devuelve EINVAL y establece en errno en EINVAL.

wcsncpy_s y _mbsncpy_s son versiones de caracteres anchos y multibyte de strncpy_s. Los argumentos y el valor devuelto de wcsncpy_s y mbsncpy_svarían en consecuencia. Por lo demás, estas seis funciones se comportan exactamente igual.

El valor de salida se ve afectado por el valor de la categoría LC_CTYPE de la configuración regional; vea setlocale para obtener más información. Las versiones de estas funciones sin el sufijo _l usan la configuración regional actual de su comportamiento dependiente de la configuración regional; las versiones con el sufijo _l son idénticas salvo que usan el parámetro locale pasado en su lugar. Para obtener más información, vea Configuración regional.

En C++, el uso de estas funciones se simplifica con las sobrecargas de plantilla; las sobrecargas pueden realizar una inferencia automáticamente de la longitud de búfer (lo que elimina la necesidad de especificar un argumento de tamaño) y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros más recientes. Para obtener más información, vea Sobrecargas de plantilla seguras.

Las versiones de depuración de estas funciones rellenan primero el búfer con 0xFD. Para deshabilitar este comportamiento, use _CrtSetDebugFillThreshold.

Asignaciones de rutina de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tcsncpy_s	strncpy_s	_mbsnbcpy_s	wcsncpy_s
_tcsncpy_s_l	_strncpy_s_l	_mbsnbcpy_s_l	_wcsncpy_s_l

Nota

_strncpy_s_l, _wcsncpy_s_l y _mbsncpy_s_l no dependen de la configuración regional y se proporcionan solo para _tcsncpy_s_l. No se han diseñado para recibir llamadas directamente.

Requisitos

Rutina	Encabezado necesario
strncpy_s, _strncpy_s_l	<string.h>
wcsncpy_s, _wcsncpy_s_l	<string.h> o <wchar.h>
_mbsncpy_s, _mbsncpy_s_l	<mbstring.h>

Para obtener más información sobre compatibilidad, vea Compatibilidad.

Ejemplo

// crt_strncpy_s_1.cpp
// compile with: /MTd

// these #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

errno_t strncpy_s_tester( const char * src,
                          int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "Copying '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf( "Copying %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   errno_t err = strncpy_s( dest, _countof(dest), src, count );

   printf( "    new contents of dest: '%s'\n", dest );

   return err;
}


void Examples()
{
   strncpy_s_tester( "howdy", 4 );
   strncpy_s_tester( "howdy", 5 );
   strncpy_s_tester( "howdy", 6 );

   printf( "\nDestination buffer too small:\n" );
   strncpy_s_tester( "Hi there!!", 10 );

   printf( "\nTruncation examples:\n" );

   errno_t err = strncpy_s_tester( "How do you do?", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncpy_s_tester( "Howdy.", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf( "\nSecure template overload example:\n" );

   char dest[10];
   strncpy( dest, "very very very long", 15 );
   // With secure template overloads enabled (see #defines at
   // top of file), the preceding line is replaced by
   //    strncpy_s( dest, _countof(dest), "very very very long", 15 );
   // Instead of causing a buffer overrun, strncpy_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncpy would
   // copy 15 characters and overrun the dest buffer.
   printf( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function, 
   const wchar_t* file, 
   unsigned int line, 
   uintptr_t pReserved)
{
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}

// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char a[20] = "test";
   char s[20];

   // simple strncpy usage:

   strcpy_s( s, 20, "dogs like cats" );
   printf( "Original string:\n   '%s'\n", s );

   // Here we can't use strncpy_s since we don't 
   // want null termination
   strncpy( s, "mice", 4 );
   printf( "After strncpy (no null-termination):\n   '%s'\n", s );
   strncpy( s+5, "love", 4 );
   printf( "After strncpy into middle of string:\n   '%s'\n", s );

   // If we use strncpy_s, the string is terminated 
   strncpy_s( s, _countof(s), "mice", 4 );
   printf( "After strncpy_s (with null-termination):\n   '%s'\n", s );

}