strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l

Obtiene la longitud de una cadena usando la configuración regional actual o una que se haya pasado. Estas funciones son versiones más seguras de , , _mbslenwcslen, _mbslen_l, _mbstrlen, _mbstrlen_l.strlen

Importante

_mbsnlen, _mbsnlen_l, _mbstrnleny _mbstrnlen_l no se pueden usar en aplicaciones que se ejecutan en Windows Runtime. Para obtener más información, vea Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows.

Sintaxis

size_t strnlen(
   const char *str,
   size_t numberOfElements
);
size_t strnlen_s(
   const char *str,
   size_t numberOfElements
);
size_t wcsnlen(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_s(
   const wchar_t *str,
   size_t numberOfElements
);
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 un valor nulo.

numberOfElements
Tamaño del búfer de cadena.

locale
Configuración regional que se va a usar.

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 numberOfElements bytes de la cadena (o caracteres anchos para wcsnlen), numberOfElements se devuelve para indicar la condición de error; las cadenas terminadas en null tienen longitudes que son estrictamente menores numberOfElementsque .

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

Comentarios

Nota:

strnlen no reemplaza a strlen; strnlen está pensado para usarse únicamente para calcular el tamaño de los datos entrantes que no son de confianza en un búfer con un tamaño conocido (por ejemplo, un paquete de red). strnlen calcula la longitud, pero no traspasa el final del búfer si la cadena está sin terminar. Para otras situaciones, vea strlen. (Esto mismo es válido para wcsnlen, _mbsnlen y _mbstrnlen).

Cada una de estas funciones devuelve el número de caracteres en str, sin incluir el carácter null de terminación. Con todo, strnlen y strnlen_s interpretan la cadena como una cadena de caracteres de un solo byte, de modo que el valor devuelto siempre es igual al número de bytes, incluso si la cadena contiene caracteres multibyte. wcsnlen y wcsnlen_s son las versiones con caracteres anchos de strnlen y strnlen_s respectivamente; los argumentos de wcsnlen y wcsnlen_s son cadenas de caracteres anchos y, como tal, el recuento de caracteres se muestra en unidades de caracteres anchos. De lo contrario, wcsnlen y strnlen se comportan de forma idéntica, al igual que strnlen_s y wcsnlen_s.

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

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

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

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

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

_mbsnlen y _mbstrnlen devuelven el número de caracteres multibyte en una cadena de caracteres multibyte. _mbsnlen reconoce secuencias de caracteres multibyte 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 prueba la validez de caracteres multibyte. _mbstrnlen comprueba la validez de los caracteres multibyte y reconoce secuencias de caracteres multibyte. Si la cadena que se pasa a _mbstrnlen contiene un carácter multibyte no válido, errno se establece en EILSEQ.

El valor de salida se ve afectado por el valor de la categoría LC_CTYPE de la configuración regional. Para obtener más información, vea setlocale. Las versiones de estas funciones son idénticas, salvo por el hecho de que las que no tienen el sufijo _l usan la configuración regional actual cuando el comportamiento depende de la configuración regional, y las que tienen el sufijo _l usan en su lugar el parámetro de configuración regional que se ha pasado. Para obtener más información, vea Locale.

Requisitos

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

Para obtener más información sobre compatibilidad, consulte 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);
}

The length of a string is the number of characters
excluding the terminating null.
Length: 82

strnlen takes a maximum size. If the string is longer
than the maximum size specified, the maximum size is
returned rather than the actual size of the string.
Length: 100

Consulte también

Manipulación de cadenas
Configuración regional
Interpretación de secuencias de caracteres multibyte
setlocale, _wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
Funciones strcoll
strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l