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

Artículo
06/09/2015

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

Importante

_mbsnlen, _mbsnlen_l, _mbstrnlen y _mbstrnlen_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.

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 un carácter de terminación null en los primeros numberOfElements bytes de la cadena (o caracteres anchos, en el caso de wcsnlen), se devuelve numberOfElements para indicar que existe una situación de error. Las cadenas acabadas en null tienen longitudes estrictamente inferiores a numberOfElements.

_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, wcsnlen, y _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 NULL o numberOfElements es mayor que INT_MAX, _mbstrnlen genera una excepción de parámetro no válido, como se describe en Validación de parámetros. Si la ejecución puede continuar, _mbstrnlen establece errno en EINVAL y devuelve -1.

Asignaciones de rutina 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 en función de la página de códigos multibyte que se usa actualmente o según la configuración regional que se haya pasado. No comprueba la validez de los 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; vea setlocale, _wsetlocale para obtener más información. 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 Configuración regional.

Requisitos

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