strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

 

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

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.

System_CAPS_ICON_important.jpg Importante

_mbsncpy_s y _mbsncpy_s_l no se pueden usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para 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 va a copiar, o _TRUNCATE.

locale
Configuración regional que se va a usar.

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

strDestnumberOfElementsstrSourceValor devueltoContenido de strDest
NULLanycualquieraEINVALno modificado
anycualquieraNULLEINVALstrDest[0] se establece en 0
any0anyEINVALno modificado
no NULLdemasiado pequeñocualquieraERANGEstrDest[0] se establece en 0

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 D caracteres se ajusten a strDest (cuyo tamaño se expresa como numberOfElements) y dejar espacio para un terminador nulo, dichos caracteres se copian y un carácter nulo se anexa; en caso contrario, strDest[0] se establece en el carácter nulo y el parámetro no válido se invoca el controlador, 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 LC_CTYPE configuración de categoría 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 Locale.

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 el requisito 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, consulta Secure Template Overloads.

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_sstrncpy_s_mbsnbcpy_swcsncpy_s
_tcsncpy_s_l_strncpy_s_l_mbsnbcpy_s_l_wcsncpy_s_l
System_CAPS_ICON_note.jpg 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.

RutinaEncabezado 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.

// 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();  
}  

Copying 4 chars of 'howdy' to 10-byte buffer dest  
    new contents of dest: 'howd'  
  
Copying 5 chars of 'howdy' to 10-byte buffer dest  
    new contents of dest: 'howdy'  
  
Copying 6 chars of 'howdy' to 10-byte buffer dest  
    new contents of dest: 'howdy'  
  
Destination buffer too small:  
  
Copying 10 chars of 'Hi there!!' to 10-byte buffer dest  
Invalid parameter handler invoked: (L"Buffer is too small" && 0)  
    new contents of dest: ''  
  
Truncation examples:  
  
Copying 'How do you do?' to 10-byte buffer dest with truncation semantics  
    new contents of dest: 'How do yo'  
    truncation did occur  
  
Copying 'Howdy.' to 10-byte buffer dest with truncation semantics  
    new contents of dest: 'Howdy.'  
    truncation did not occur  
  
Secure template overload example:  
Invalid parameter handler invoked: (L"Buffer is too small" && 0)  
    new contents of dest: ''  

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

Original string:  
   'dogs like cats'  
After strncpy (no null-termination):  
   'mice like cats'  
After strncpy into middle of string:  
   'mice love cats'  
After strncpy_s (with null-termination):  
   'mice'  

System::String::Copy

Manipulación de cadenas
Configuración regional
Interpretación de secuencias de caracteres Multibyte
_mbsnbcpy, _mbsnbcpy_l
strcat_s, wcscat_s, _mbscat_s
strcmp, wcscmp, _mbscmp
strcpy_s, wcscpy_s, _mbscpy_s
strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_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

Mostrar: