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

Artigo
03/12/2013

Obtém o comprimento de uma cadeia de caracteres usando a localidade atual ou que foram passadas em.Esses são mais seguros versões de strlen strlen_l, wcslen, wcslen_l, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

Importante
_mbsnlen, _mbsnlen_l, _mbstrnlen, e _mbstrnlen_l não podem ser usados em aplicativos executados em Tempo de Execução do Windows.Para obter mais informações, consulte Funções de CRT não suportadas com /ZW.

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
Cadeia de caracteres NULL-finalizada.
numberOfElements
O tamanho do buffer de cadeia de caracteres.
locale
A localidade usar.

Valor de retorno

Essas funções retorna o número de caracteres na cadeia de caracteres, não incluindo o caractere de terminação zero.Se não houver nenhum terminador de dentro do primeiro zero bytes de numberOfElements de cadeia de caracteres (ou de caracteres largos para wcsnlen), então numberOfElements é retornado para indicar a condição de erro; as cadeias de caracteres NULL- terminadas com os comprimentos que são estritamente menor que numberOfElements.

_mbstrnlen e _mbstrnlen_l retorna -1 se a cadeia de caracteres contém um caractere inválido de multibyte.

Comentários

Observação
strnlen não é uma substituição para strlen; strnlen destina-se a ser usado para calcular apenas o tamanho de dados não confiáveis de entrada em um buffer de conhecido tamanho- por exemplo, um conjunto de rede.strnlen calcula o tamanho mas não anda após ao final do buffer se a cadeia de caracteres é unterminated.Para outras situações, use strlen.(O mesmo se aplica a wcsnlen, a _mbsnlen, e a _mbstrnlen.)

strnlen não é uma substituição para strlen; strnlen destina-se a ser usado para calcular apenas o tamanho de dados não confiáveis de entrada em um buffer de conhecido tamanho- por exemplo, um conjunto de rede.strnlen calcula o tamanho mas não anda após ao final do buffer se a cadeia de caracteres é unterminated.Para outras situações, use strlen.(O mesmo se aplica a wcsnlen, a _mbsnlen, e a _mbstrnlen.)

Cada uma dessas funções retorna o número de caracteres em str, não incluindo o caractere de terminação zero.No entanto, strnlen e strnlen_l interpretam a cadeia de caracteres como uma cadeia de caracteres de byte único e como consequência, o valor de retorno é sempre igual ao número de bytes, mesmo se a cadeia de caracteres contém caracteres de multibyte.wcsnlen e wcsnlen_l são versões de largo- caractere de strnlen e de strnlen_l respectivamente; os argumentos para wcsnlen e wcsnlen_l são cadeias de caracteres de largo- caracteres e a contagem de caracteres está em unidades de largo- caractere.Caso contrário, wcsnlen, wcsnlen_l, strnlen e strnlen_l se comportam de forma idêntica.

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

strnlen_s e wcsnlen_s validam seus parâmetros.Se str é NULL, o retorno 0 de funções.

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

Mapeamentos da rotina de Genérico- texto

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

_mbsnlen e _mbstrnlen retorna o número de caracteres de multibyte em uma cadeia de caracteres de multibyte- caractere._mbsnlen reconhece sequências de multibyte- caractere de acordo com a página de código de multibyte que está atualmente em uso ou de acordo com a localidade que são passadas no; não testar validade de multibyte- caractere.os testes de_mbstrnlen validade de multibyte- caractere e reconhecem sequências de multibyte- caractere.Se a cadeia de caracteres que é passada a _mbstrnlen contém um caractere inválido de multibyte, errno é definido como EILSEQ.

O valor de saída é afetado pela configuração da categoria de LC_CTYPE de localidade; consulte setlocale, wsetlocale para mais informações.As versões dessas funções são idênticas, exceto as que não têm o uso do sufixo de _l a localidade atual para este comportamento de são dependentes e as versões que têm o sufixo de _l usar o parâmetro de localidade que é passado.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 informações extras de 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);
}