strnlen, los strnlen_s, strnlen_l, wcsnlen, los wcsnlen_s, wcsnlen_l, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l

Artículo
04/10/2013

Obtiene la longitud de una cadena con la configuración regional o la actual que se ha pasado.Éstas son versiones más seguras de strlen, strlen_l, wcslen, wcslen_l, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

Importante
_mbsnlen, _mbsnlen_l, _mbstrnlen, y _mbstrnlen_l no se pueden utilizar en las aplicaciones que se ejecutan en Windows en tiempo de ejecución.Para obtener más información, vea Funciones CRT no compatibles con /ZW.

size_t strnlen(
   const char *str,
   size_t numberOfElements 
);
size_t strnlen_s(
   const char *str,
   size_t numberOfElements 
);
size_t strnlen_l(
   const char *str,
   size_t numberOfElements,
   _locale_t locale
);
size_t wcsnlen(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_s(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_l(
   const wchar_t *str,
   size_t numberOfElements,
   _locale_t locale
);
size_t _mbsnlen(
   const unsigned char *str,
   size_t numberOfElements
);
size_t _mbsnlen_l(
   const unsigned char *str,
   size_t numberOfElements,
   _locale_t locale
);
size_t _mbstrnlen(
   const char *str,
   size_t numberOfElements
);
size_t _mbstrnlen_l(
   const char *str,
   size_t numberOfElements,
   _locale_t locale
);

Parámetros

str
Cadena terminada en null.
numberOfElements
El tamaño del búfer de cadena.
locale
Configuración regional a utilizar.

Valor devuelto

Estas funciones devuelven el número de caracteres de la cadena, sin incluir el carácter null de terminación.Si no hay ningún terminador nulo dentro de los primeros bytes de numberOfElements de la cadena (o de caracteres anchos para wcsnlen), después numberOfElements se devuelve para indicar la condición de error; las cadenas terminadas en null tienen longitudes que son estrictamente menor que numberOfElements.

_mbstrnlen y _mbstrnlen_l devuelve -1 si la cadena contiene un carácter no válido multibyte.

Comentarios

[!NOTA]

strnlen no es un reemplazo para strlen; strnlen está diseñado para usarse para calcular solo el tamaño de datos que no son de confianza de entrada en un búfer de conocido calibre- para el ejemplo, un paquete de red.strnlen calcula la longitud pero no recorre del fin del búfer si la cadena es e indefinida.En otras situaciones, utilice strlen.(El mismo se aplica a wcsnlen, a _mbsnlen, y a _mbstrnlen.)

Cada una de estas funciones devuelve el número de caracteres de str, sin incluir el carácter null de terminación.Sin embargo, strnlen y strnlen_l interpretan la cadena como una cadena de caracteres de solo- byte y por consiguiente, el valor devuelto siempre es igual al número de bytes, incluso si la cadena contiene caracteres multibyte.wcsnlen y wcsnlen_l son versiones de caracteres anchos de strnlen y de strnlen_l respectivamente; los argumentos para wcsnlen y wcsnlen_l son cadenas de caracteres y el recuento de caracteres está en unidades de caracteres anchos.Si no, wcsnlen, wcsnlen_l, strnlen y strnlen_l se comportan exactamente igual.

strnlen, wcsnlen, y _mbsnlen no validan sus parámetros.Si str es NULL, una infracción de acceso.

strnlen_s y wcsnlen_s validan sus parámetros.Si str es NULL, devuelven 0 de funciones.

_mbstrnlen también valida sus parámetros.Si str es NULL, o si numberOfElements es mayor que INT_MAX, _mbstrnlen genera una excepción no válida del parámetro, como se describe en Validación de parámetros.Si la ejecución puede continuar, _mbstrnlen establece errno a EINVAL y devuelve -1.

Asignaciones de la rutina de Genérico- texto

Rutina de TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen_l	_mbsnlen_l	wcsnlen_l

_mbsnlen y _mbstrnlen devuelve el número de caracteres multibyte en una cadena de multibyte- carácter._mbsnlen reconoce secuencias de multibyte- carácter según la página de códigos multibyte que está actualmente en uso o según la configuración regional que se pasa; no comprueba la validez del multibyte- carácter._mbstrnlen prueba para la validez del multibyte- carácter y reconoce secuencias de multibyte- carácter.Si la cadena que se pasa a _mbstrnlen contiene un carácter no válido multibyte, errno se establece en EILSEQ.

El valor de salida se ve afectado por el valor de la categoría de LC_CTYPE de configuración regional; vea setlocale, _wsetlocale para obtener más información.Las versiones de estas funciones son idénticas, excepto en que las que no tienen el uso del sufijo de _l la configuración regional actual para este comportamiento configuración regional- dependiente y versiones que tienen el sufijo de _l en su lugar utilice el parámetro de configuración regional que se pasa.Para obtener más información, vea Configuración regional.

Requisitos

Rutina	Encabezado necesario
strnlen, strnlen_s, strnlen_l	<string.h>
wcsnlen, wcsnlen_s, wcsnlen_l	<string.h> o <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

Para obtener información adicional de compatibilidad, vea Compatibilidad.

Ejemplo

// crt_strnlen.c

#include <string.h>

int main()
{
   // str1 is 82 characters long. str2 is 159 characters long 

   char* str1 = "The length of a string is the number of characters\n"
               "excluding the terminating null.";
   char* str2 = "strnlen takes a maximum size. If the string is longer\n"
                "than the maximum size specified, the maximum size is\n"
                "returned rather than the actual size of the string.";
   size_t len;
   size_t maxsize = 100;

   len = strnlen(str1, maxsize);
   printf("%s\n Length: %d \n\n", str1, len);
   
   len = strnlen(str2, maxsize);
   printf("%s\n Length: %d \n", str2, len);
}