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

Artigo
08/25/2010

Obter o tamanho de uma seqüência de caracteres, usando a localidade corrente ou um que foi passado no.Versões mais seguras de strlen, strlen_l, wcslen, wcslen_l, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

size_t strnlen(
   const char *str,
   size_t numberOfElements 
);
size_t strnlen_s(
   const char *str,
   size_t numberOfElements 
);
size_t strnlen_l(
   const char *str,
   size_t numberOfElements,
   _locale_t locale
);
size_t wcsnlen(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_s(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_l(
   const wchar_t *str,
   size_t numberOfElements,
   _locale_t locale
);
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
Seqüência de caracteres terminada com caractere nulo.
numberOfElements
O dimensionar do buffer de cadeia de caracteres.
locale
Localidade usar.

Valor de retorno

Essas funções retornam o número de caracteres na seqüência de caracteres (excluindo a terminação nula).Se não houver nenhum terminador nulo dentro da primeira numberOfElements bytes da seqüência de caracteres (ou caracteres largos para wcsnlen), em seguida, numberOfElements é retornado para indicar a condição de erro seqüências de terminação nula têm comprimentos estritamente menor que numberOfElements.

_mbstrnlen e _mbstrnlen_l retorne -1 se a seqüência de caracteres contém caractere inválido multibyte.

Comentários

Observação:
strnlen não é uma substituição para strlen; strnlen destina-se somente a ser usado para calcular o dimensionar dos dados de entrada não confiáveis em um buffer de dimensionar conhecido (sistema autônomo um pacote de rede). strnlen irá calcular o comprimento mas não passar após o participante do buffer de se a seqüência de caracteres for não finalizada. Para outras situações, use strlen. (O mesmo se aplica a wcsnlen, _mbsnlen, e _mbstrnlen.)

strnlen não é uma substituição para strlen; strnlen destina-se somente a ser usado para calcular o dimensionar dos dados de entrada não confiáveis em um buffer de dimensionar conhecido (sistema autônomo um pacote de rede). strnlen irá calcular o comprimento mas não passar após o participante do buffer de se a seqüência de caracteres for não finalizada. Para 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 o caractere nulo de terminação. No entanto, strnlen e strnlen_l interprete a seqüência de caractere sistema autônomo uma seqüência de caractere de byte único, portanto, seu valor retornado é sempre igual ao número de bytes, mesmo se a seqüência de caractere contém caractere de multibyte. wcsnlen e wcsnlen_l são versões de caractere largo das strnlen e strnlen_l respectivamente; os argumentos para wcsnlen e wcsnlen_l são seqüências de caracteres largos e a contagem de caracteres de unidades de caractere largo. wcsnlen, wcsnlen_l, strnlen e strnlen_l Caso contrário, tenham comportamento idêntico.

strnlen, wcsnlen, e _mbsnlen não validar seus parâmetros. If str é NULL, ocorrerá uma violação de acesso.

strnlen_s e wcsnlen_s Valide seus parâmetros. If str é NULL, as funções retornará 0.

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

Mapeamentos de rotina de texto genérica

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen_l	_mbsnlen_l	wcsnlen_l

_mbsnlen e _mbstrnlen retornar o número de caractere multibyte de uma seqüência de caractere de multibyte. _mbsnlen reconhece os caractere multibyte seqüências de acordo com a página de código multibyte atualmente em usam ou a localidade do passado; não testa a validade de caractere multibyte. _mbstrnlen testa a validade de caractere multibyte e reconhece seqüências de caractere de multibyte. Se a seqüência de caracteres passada para _mbstrnlen contém um caractere inválido multibyte, errno é definido como EILSEQ.

O valor de saída é afetado pela configuração do LC_CTYPE categoria de configuração da localidade; consulte setlocale para obter mais informações.As versões dessas funções sem o _l sufixo use a localidade corrente para esse comportamento dependente de localidade; as versões com o _l sufixo são idênticas exceto que usarem o parâmetro de localidade passado em vez disso. Para obter mais informações, consulte Localidade.

Requisitos

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

Para obter informações adicionais compatibilidade, consulte Compatibilidade na introdução.

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