strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Artículo
04/10/2013

Caracteres de copia de una cadena a otra.Éstas son versiones de strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l con mejoras de seguridad como se describe en Características de seguridad en CRT.

Importante
_mbsncpy_s y _mbsncpy_s_l no se pueden utilizar en las aplicaciones que se ejecutan en tiempo de ejecución de Windows.Para obtener más información, vea Funciones CRT no compatibles 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
El tamaño de la cadena de destino, en caracteres.
strSource
Cadena de origen.
count
Número de caracteres que se copiarán, o _TRUNCATE.
locale
La configuración regional a utilizar.

Valor devuelto

Cero si es correcto, STRUNCATE si el truncamiento se produjo, si no es un 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

Intento de estas funciones para copiar los primeros caracteres de D de strSource a strDest, donde es menos D de count y longitud de strSource.Si esos caracteres de D caben dentro de strDest (cuyo tamaño se da como numberOfElements) y todavía salir de sitio para un terminador nulo, se copian los caracteres y se anexa un carácter null final; si no, strDest[0] se establece en el carácter null y el controlador no válido de parámetro se invoca, como se describe en Validación de parámetros.

Hay una excepción al párrafo anterior.Si count es _TRUNCATE, después tanto de strSource que caben en strDest se copia mientras todavía deja el sitio para la null final que se anexa siempre.

Por ejemplo,

char dst[5];

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

significa que se solicita a strncpy_s para copiar cinco caracteres en un búfer cinco bytes de longitud; esto no permitiría ningún espacio para el terminador, por tanto los ceros nulos de strncpy_s comentario la cadena y llama al controlador no válido del parámetro.

Si el comportamiento del truncamiento es necesario, utilice _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 es NOT completo con caracteres nulos hasta la longitud count.

El comportamiento de strncpy_s es indefinido si las cadenas de origen y de destino se superponen.

Si strDest o strSource es NULL, o numberOfElements es 0, se invoca el controlador no válido del parámetro.Si la ejecución puede continuar, la función devuelve EINVAL y establece errno a EINVAL.

wcsncpy_s y _mbsncpy_s son versiones de caracteres anchos y de multibyte- carácter de strncpy_s.Los argumentos y el valor devuelto de wcsncpy_s y mbsncpy_s varían en consecuencia.Estas seis funciones se comportan exactamente igual de otra manera.

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

En C++, mediante estas funciones es simplificado con sobrecargas de plantilla; las sobrecargas pueden deducir la longitud de búfer automáticamente (que elimina la necesidad de especificar un argumento de tamaño) y automáticamente pueden reemplazar anterior, funciones de no Secure con sus más recientes, seguros homólogos.Para obtener más información, vea Sobrecargas de plantilla de seguridad.

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

Asignaciones de la rutina de Genérico- texto

Rutina de 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]

el _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 y no están diseñados llamar 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 información adicional de compatibilidad, vea Compatibilidad en la Introducción.

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

}