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

Articolo
06/09/2015

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

Importante

_mbsnlen, _mbsnlen_l, _mbstrnlen e _mbstrnlen_l non possono essere usati nelle applicazioni eseguite in Windows Runtime.Per altre informazioni, vedere l'argomento relativo alle funzioni CRT non supportate con /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 );

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 esiste un terminatore null entro i primi numberOfElements byte della stringa (o caratteri wide per wcsnlen), viene restituito numberOfElements per indicare la condizione di errore. La lunghezza delle stringhe con terminatore null è rigorosamente inferiore a numberOfElements.

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

Note

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, wcsnlen, e _mbsnlen non convalidano i propri 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 è NULL o se numberOfElements è maggiore di INT_MAX, _mbstrnlen genera un'eccezione di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, _mbstrnlen imposta errno su EINVAL e restituisce -1.

Mapping di routine di testo generico

Routine TCHAR.H	_UNICODE e _MBCS non definiti	_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 in uso o in base alle impostazioni locali passate, ma non testa 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 dalla configurazione dell'impostazione della categoria LC_CTYPE delle impostazioni locali. Per altre informazioni, vedere setlocale, _wsetlocale. 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 Impostazioni locali.

Requisiti

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

Per altre informazioni sulla compatibilità, vedere 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);
}