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

Obtém o tamanho de uma cadeia de caracteres usando a localidade atual ou uma que foi enviada. Essas funções são versões mais seguras de strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, , _mbstrlen_l.

Importante

_mbsnlen, _mbsnlen_l, _mbstrnlene _mbstrnlen_l não pode ser usado em aplicativos executados no Tempo de Execução do Windows. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

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
Cadeia de caracteres terminada em nulo.

numberOfElements
O tamanho do buffer da cadeia de caracteres.

locale
Localidade a usar.

Valor retornado

Essas funções retornam o número de caracteres na cadeia de caracteres, sem incluir o caractere de terminação nula. Se não houver nenhum terminador nulo nos primeiros numberOfElements bytes da cadeia de caracteres (ou caracteres largos para wcsnlen), então numberOfElements será retornado para indicar a condição de erro; as cadeias de caracteres terminadas em nulo têm comprimentos estritamente menores que numberOfElements.

_mbstrnlen e _mbstrnlen_l retornam -1 se a cadeia de caracteres contiver um caractere multibyte inválido.

Comentários

Observação

strnlen não é uma substituição de strlen; strnlen é feito para ser usado apenas para calcular o tamanho dos dados não confiáveis recebidos em um buffer de tamanho conhecido, por exemplo, um pacote de rede. strnlen calcula o tamanho, mas não passa do fim do buffer se a cadeia de caracteres não estiver terminada. Para ter outras situações, use strlen. (O mesmo se aplica a wcsnlen, _mbsnlen e _mbstrnlen.)

Cada uma dessas funções retorna o número de caracteres em str, sem incluir o caractere de terminação nula. Porém, strnlen e strnlen_s interpretam a cadeia de caracteres como uma cadeia de caracteres de byte único e, portanto, o valor retornado é sempre igual ao número de bytes, mesmo que a cadeia de caracteres contenha caracteres multibyte. wcsnlen e wcsnlen_s são versões de caractere largo de strnlen e strnlen_s, respectivamente; os argumentos para wcsnlen e wcsnlen_s são cadeia de caracteres larga e a contagem de caracteres ficam em unidades de caractere largo. Caso contrário, wcsnlen e strnlen comportam-se de modo idêntico, assim como strnlen_s e wcsnlen_s.

strnlen, wcsnlene _mbsnlen não validam seus parâmetros. Se str for NULL, ocorre uma violação de acesso.

strnlen_s e wcsnlen_s validam seus parâmetros. Se str for NULL, as funções retornam 0.

_mbstrnlen também valida seus parâmetros. Se str for NULL, ou se numberOfElements for maior que INT_MAX, _mbstrnlen gera uma exceção de parâmetro inválida, conforme descrito em Validação de parâmetro. Se a execução puder continuar, _mbstrnlen define errno para EINVAL e retorna -1.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen	_mbsnlen_l	wcsnlen

_mbsnlen e _mbstrnlen retorna o número de caracteres multibyte em uma cadeia de caracteres multibyte. _mbsnlen reconhece sequências de caracteres multibyte de acordo com a página de código multibyte que está em uso no momento ou de acordo com a localidade passada; ele não testa a validade de caracteres multibyte. O _mbstrnlen testa a validade de caracteres multibyte e reconhece sequências de caracteres multibyte. Se a cadeia de caracteres enviada para _mbstrnlen contiver um caractere multibyte inválido, errno é definido para EILSEQ.

O valor de saída é afetado pela configuração da categoria LC_CTYPE da localidade. Para obter mais informações, consulte setlocale. As versões dessas funções são idênticas, exceto que aquelas que não têm o sufixo _l usam a localidade atual para esse comportamento dependente de localidade e as versões com um sufixo _l usam o parâmetro de localidade informado. Para obter mais informações, consulte Localidade.

Requisitos

Rotina	Cabeçalho necessário
strnlen, strnlen_s	<string.h>
wcsnlen, wcsnlen_s	<string.h> ou <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// 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

Confira também

Manipulação de cadeia de caracteres
Localidade
Interpretação de sequências de caracteres multibyte
setlocale, _wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, , _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
Funções 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