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

Artigo
06/09/2015

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

Importante

_mbsnlen, _mbsnlen_l, _mbstrnlen e _mbstrnlen_l não podem ser usados em aplicativos executados no Tempo de Execução do Windows.Para obter mais informações, consulte Funções de CRT sem suporte com /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
Cadeia de caracteres terminada em nulo.
numberOfElements
O tamanho do buffer da cadeia de caracteres.
locale
Localidade a usar.

Valor de retorno

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 terminador nulo dentro dos primeiros numberOfElements bytes da cadeia de caracteres (ou caracteres largos para wcsnlen), numberOfElements é retornado para indicar a condição de erro; a cadeia de caracteres de terminação nula tem comprimento estritamente menor que numberOfElements.

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

Comentários

Dica

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, wcsnlen, e _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álido, como descrito em Validação do parâmetro. Se a execução puder continuar, _mbstrnlen define errno para EINVAL e retorna -1.

Mapeamentos da 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. O _mbsnlen reconhece sequências de caracteres multibyte de acordo com a página de código multibyte que está em uso no momento ou com a localidade informada; 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 definição da configuração de categoria LC_CTYPE da localidade. Consulte setlocale, _wsetlocale para obter mais informações. 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 adicionais 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);
}