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

Ottiene la lunghezza di una stringa, usando le impostazioni locali correnti o quelle che sono state passate. Queste funzioni sono versioni più sicure di strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

Importante

_mbsnlen, _mbsnlen_l, _mbstrnlene _mbstrnlen_l non possono essere usati nelle applicazioni eseguite in Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).

Sintassi

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
);

Parametri

str
Stringa con terminazione Null.

numberOfElements
Dimensione del buffer di stringa.

locale
Impostazioni locali da usare.

Valore restituito

Queste funzioni restituiscono il numero di caratteri nella stringa, escluso il valore null finale. Se non è presente alcun carattere di terminazione Null entro i primi numberOfElements byte della stringa (o caratteri wide per wcsnlen), numberOfElements viene restituito per indicare la condizione di errore. Le stringhe con terminazione Null hanno lunghezze rigorosamente minori di numberOfElements.

_mbstrnlen e _mbstrnlen_l restituiscono -1 se la stringa contiene un carattere multibyte non valido.

Osservazioni:

Nota

strnlen non è un sostituto di strlen; strnlen è pensato per essere usato solo per il calcolo della dimensione dei dati non attendibili entranti in un buffer di dimensione nota, ad esempio un pacchetto di rete. strnlen calcola la lunghezza ma non oltrepassa la fine del buffer se la stringa è priva di terminazione. In situazioni di altro tipo, usare strlen (lo stesso vale per wcsnlen, _mbsnlen e _mbstrnlen).

Ognuna di questa funzioni restituisce il numero di caratteri in str, escluso il carattere null di terminazione. Tuttavia, strnlen e strnlen_s interpretano la stringa come stringa di caratteri a byte singolo, per cui il valore restituito sarà sempre uguale al numero di byte, anche se la stringa contiene caratteri multibyte. wcsnlen e wcsnlen_s sono versioni a caratteri wide di strnlen e strnlen_s rispettivamente. Gli argomenti per wcsnlen e wcsnlen_s sono stringhe a caratteri wide e il numero di caratteri è espresso in unità a caratteri wide. Per il resto, wcsnlen e strnlen si comportano in modo identico, come strnlen_s e wcsnlen_s.

strnlen, wcsnlene _mbsnlen non convalidano i relativi parametri. Se str è NULL, si verifica una violazione di accesso.

strnlen_s e wcsnlen_s convalidano i propri parametri. Se str è NULL, le funzioni restituiscono 0.

Anche _mbstrnlen convalida i propri parametri. Se str è o se numberOfElements è NULLmaggiore di INT_MAX, _mbstrnlen genera un'eccezione di parametro non valida, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, _mbstrnlen imposta errno su EINVAL e restituisce -1.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

TCHAR.H Routine	_UNICODE e _MBCS non definito	_MBCS Definito	_UNICODE Definito
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen	_mbsnlen_l	wcsnlen

_mbsnlen e _mbstrnlen restituiscono il numero di caratteri multibyte in una stringa di caratteri multibyte. _mbsnlen riconosce le sequenze di caratteri multibyte in base alla tabella codici multibyte attualmente in uso o in base alle impostazioni locali passate; non verifica la validità dei caratteri multibyte. _mbstrnlen testa la validità dei caratteri multibyte e riconosce le sequenze di caratteri multibyte. Se la stringa passata a _mbstrnlen contiene un carattere multibyte non valido, errno viene impostato su EILSEQ.

Il valore di output è interessato dall'impostazione dell'impostazione LC_CTYPE della categoria delle impostazioni locali. Per ulteriori informazioni, vedere setlocale. Le versioni di queste funzioni sono identiche, tranne per il fatto che quelle prive del suffisso _l usano le impostazioni locali correnti per questo comportamento dipendente dalle impostazioni locali e le versioni con il suffisso _l usano il parametro delle impostazioni locali passato. Per altre informazioni, vedere Locale.

Requisiti

Ciclo	Intestazione obbligatoria
strnlen, strnlen_s	<string.h>
wcsnlen, wcsnlen_s	<string.h> oppure <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

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

Vedi anche

Manipolazione delle stringhe
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
setlocale, _wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
Funzioni 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