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

Obtient la longueur d'une chaîne en utilisant les paramètres régionaux actuels ou ceux qui ont été passés. Ces fonctions sont des versions plus sécurisées de strlen, , _mbslenwcslen, _mbslen_l, _mbstrlen, . _mbstrlen_l

Important

_mbsnlen, _mbsnlen_l, _mbstrnlenet _mbstrnlen_l ne peut pas être utilisé dans les applications qui s’exécutent dans Windows Runtime. Pour plus d’informations, consultez Fonctions CRT non prises en charge dans les applications de la plateforme Windows universelle.

Syntaxe

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

Paramètres

str
Chaîne terminée par un caractère Null.

numberOfElements
Taille de la mémoire tampon de chaîne.

locale
Paramètres régionaux à utiliser.

Valeur retournée

Ces fonctions retournent le nombre de caractères dans la chaîne, sans le caractère Null de fin. S’il n’y a pas de terminateur Null dans les premiers numberOfElements octets de la chaîne (ou des caractères larges pour wcsnlen), numberOfElements est retourné pour indiquer la condition d’erreur ; les chaînes terminées par null ont des longueurs qui sont strictement inférieures à numberOfElements.

_mbstrnlen et _mbstrnlen_l retournent -1 si la chaîne contient un caractère multioctet non valide.

Notes

Remarque

strnlen ne remplace pas strlen ; strnlen est destiné à être utilisé uniquement pour calculer la taille des données entrantes non fiables dans une mémoire tampon de taille connue, par exemple un paquet réseau. strnlen calcule la longueur mais ne continue pas après la fin de la mémoire tampon si la chaîne n'est pas terminée. Pour d'autres situations, utilisez strlen. (Également applicable à wcsnlen, _mbsnlen et _mbstrnlen.)

Chacune de ces fonctions retourne le nombre de caractères dans str, sans le caractère Null de fin. Toutefois, strnlen et strnlen_s interprètent la chaîne comme une chaîne de caractères composée d'un unique octet et la valeur de retour est donc toujours égale au nombre d'octets, même si la chaîne contient des caractères multioctets. wcsnlen et wcsnlen_s sont des versions à caractères larges de strnlen et strnlen_s respectivement ; les arguments pour wcsnlen et wcsnlen_s sont des chaînes à caractères larges et le nombre de caractères est établi en unités à caractères larges. Sinon, wcsnlen et strnlen se comportent de la même façon, comme strnlen_s et wcsnlen_s.

strnlen, wcsnlenet _mbsnlen ne valident pas leurs paramètres. Si str a la valeur NULL, une violation d'accès se produit.

strnlen_s et wcsnlen_s valident leurs paramètres. Si str a la valeur NULL, les fonctions retournent 0.

_mbstrnlen valide également ses paramètres. Si str c’est le cas, ou s’il numberOfElements est NULLsupérieur INT_MAXà , _mbstrnlen génère une exception de paramètre non valide, comme décrit dans la validation des paramètres. Si l'exécution est autorisée à se poursuivre, _mbstrnlen affecte à errno la valeur EINVAL et retourne -1.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Mappages de routine de texte générique

TCHAR.H Routine	_UNICODE et _MBCS non défini	_MBCS Défini	_UNICODE Défini
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen	_mbsnlen_l	wcsnlen

_mbsnlen et _mbstrnlen retournent le nombre de caractères multioctets dans une chaîne de caractères multioctets. _mbsnlen reconnaît les séquences de caractères multioctets en fonction de la page de codes multioctets actuellement utilisée ou en fonction des paramètres régionaux passés ; il ne teste pas la validité de caractères multioctets. _mbstrnlen teste la validité des caractères multioctets et identifie les séquences de caractères multioctets. Si la chaîne transmise à _mbstrnlen contient un caractère multioctet non valide, errno prend la valeur EILSEQ.

La valeur de sortie est affectée par le paramètre de catégorie LC_CTYPE des paramètres régionaux. Pour plus d’informations, consultez setlocale. Les versions de ces fonctions sont identiques, excepté que celles qui n'ont pas le suffixe _l utilisent les paramètres régionaux actuels pour ce comportement dépendant de ces paramètres, et les versions qui ont le suffixe _l utilisent plutôt les paramètres régionaux qui ont été passés. Pour plus d’informations, consultez Locale.

Spécifications

Routine	En-tête requis
strnlen, strnlen_s	<string.h>
wcsnlen, wcsnlen_s	<string.h> ou <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple

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

Voir aussi

Manipulation de chaîne
Paramètres régionaux
Interprétation des séquences de caractères multioctets
setlocale, _wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strcoll, fonctions
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