strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l

Obtém o tamanho de uma cadeia de caracteres usando a localidade atual ou uma especificada. Versões mais seguras dessas funções estão disponíveis; confira strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l

Importante

_mbslen, _mbslen_l, _mbstrlen e _mbstrlen_l não podem ser usados em aplicativos que são executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

size_t strlen(
   const char *str
);
size_t wcslen(
   const wchar_t *str
);
size_t _mbslen(
   const unsigned char *str
);
size_t _mbslen_l(
   const unsigned char *str,
   _locale_t locale
);
size_t _mbstrlen(
   const char *str
);
size_t _mbstrlen_l(
   const char *str,
   _locale_t locale
);

Parâmetros

str
Cadeia de caracteres terminada em nulo.

locale
Localidade a usar.

Retornar valor

Cada uma dessas funções retorna o número de caracteres em str, excluindo o terminal null. Nenhum valor retornado é reservado para indicar um erro, exceto _mbstrlen e _mbstrlen_l, que retornarão ((size_t)(-1)) se a cadeia de caracteres contiver um caractere multibyte inválido.

Comentários

strlen interpreta a cadeia de caracteres como uma cadeia de caracteres de byte único, de forma que seu valor retornado seja sempre igual ao número de bytes, mesmo que a cadeia de caracteres contenha caracteres multibyte. wcslen é uma versão de caractere largo de strlen; o argumento de wcslen é uma cadeia de caracteres de caractere largo e a contagem de caracteres está em caracteres largos (dois bytes). Caso contrário, wcslen e strlen se comportam de forma idêntica.

Observação de segurança Essas funções acarretam uma ameaça em potencial em relação a um problema de estouro de buffer. Os problemas de estouro de buffer são um método frequente de ataque ao sistema, resultando em uma elevação de privilégio sem garantia. Para obter mais informações, consulte Evitando saturações de buffer.

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

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcslen	strlen	strlen	wcslen
_tcsclen	strlen	_mbslen	wcslen
_tcsclen_l	strlen	_mbslen_l	wcslen

_mbslen e _mbslen_l retornam o número de caracteres multibyte em uma cadeia de caracteres multibyte, mas eles não testam a validade de caracteres multibyte. _mbstrlen e _mbstrlen_l testam a validade do caractere multibyte e reconhecem sequências de caractere multibyte. Se a cadeia de caracteres for passada para _mbstrlen ou _mbstrlen_l contiver um caractere multibyte inválido para a página de código, a função retornará -1 e definirá errno como 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 sem o sufixo _l usam a localidade atual desse comportamento dependente da localidade. As versões com o sufixo _l são idênticas, exceto por usarem o parâmetro de localidade passado em seu lugar. Para obter mais informações, consulte Localidade.

Requisitos

Rotina	Cabeçalho necessário
strlen	<string.h>
wcslen	<string.h> ou <wchar.h>
_mbslen, _mbslen_l	<mbstring.h>
_mbstrlen, _mbstrlen_l	<stdlib.h>

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

Exemplo

// crt_strlen.c
// Determine the length of a string. For the multi-byte character
// example to work correctly, the Japanese language support for
// non-Unicode programs must be enabled by the operating system.

#include <string.h>
#include <locale.h>

int main()
{
   char* str1 = "Count.";
   wchar_t* wstr1 = L"Count.";
   char * mbstr1;
   char * locale_string;

   // strlen gives the length of single-byte character string
   printf("Length of '%s' : %d\n", str1, strlen(str1) );

   // wcslen gives the length of a wide character string
   wprintf(L"Length of '%s' : %d\n", wstr1, wcslen(wstr1) );

   // A multibyte string: [A] [B] [C] [katakana A] [D] [\0]
   // in Code Page 932. For this example to work correctly,
   // the Japanese language support must be enabled by the
   // operating system.
   mbstr1 = "ABC" "\x83\x40" "D";

   locale_string = setlocale(LC_CTYPE, "Japanese_Japan");

   if (locale_string == NULL)
   {
      printf("Japanese locale not enabled. Exiting.\n");
      exit(1);
   }
   else
   {
      printf("Locale set to %s\n", locale_string);
   }

   // _mbslen will recognize the Japanese multibyte character if the
   // current locale used by the operating system is Japanese
   printf("Length of '%s' : %d\n", mbstr1, _mbslen(mbstr1) );

   // _mbstrlen will recognize the Japanese multibyte character
   // since the CRT locale is set to Japanese even if the OS locale
   // isnot.
   printf("Length of '%s' : %d\n", mbstr1, _mbstrlen(mbstr1) );
   printf("Bytes in '%s' : %d\n", mbstr1, strlen(mbstr1) );

}

Length of 'Count.' : 6
Length of 'Count.' : 6
Length of 'ABCァD' : 5
Length of 'ABCァD' : 5
Bytes in 'ABCァD' : 6

Confira também

Manipulação de cadeia de caracteres
Interpretação de sequências de caracteres multibyte
Localidade
setlocale, _wsetlocale
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
Funções strcoll
strcpy, wcscpy, _mbscpy
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l