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

Article
03/26/2013

Obtient la longueur d'une chaîne à l'aide de les paramètres régionaux actuels ou les qui ont été passés.Ce sont des versions plus sûres de strlen, strlen_l, wcslen, wcslen_l, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

Important

_mbsnlen, _mbsnlen_l, _mbstrnlen, et _mbstrnlen_l ne peuvent pas être utilisés dans les applications qui s'exécutent dans Windows Runtime.Pour plus d'informations, consultez Fonctions CRT non prises en charge avec /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
);

Paramètres

str
Chaîne terminée par le caractère NULL.
numberOfElements
La taille de la mémoire tampon de chaîne.
locale
Paramètres régionaux à utiliser.

Valeur de retour

Ces fonctions retournent le nombre de caractères dans la chaîne, sans le caractère NULL de fin.S'il n'existe aucune marque de fin null dans les premiers octets d' numberOfElements de la chaîne (ou de caractères larges pour wcsnlen), alors numberOfElements est retourné pour indiquer la condition d'erreur ; les chaînes terminée par le caractère NULL ont des longueurs qui sont strictement inférieure qu' numberOfElements.

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

Notes

[!REMARQUE]

strnlen n'est pas un remplacement pour strlen; strnlen est conçu pour être utilisé pour calculer uniquement la taille des données non fiables entrantes dans une mémoire tampon de taille- pour l'exemple, un paquet réseau.strnlen calcule la longueur mais ne démarre pas après la fin de la mémoire tampon si la chaîne est unterminated.Pour d'autres cas, utilisez strlen.(Le même s'applique à 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_l interpréter la chaîne comme une chaîne de caractères codé sur un octet et par conséquent, la valeur de retour est toujours égale au nombre d'octets, même si la chaîne contient des caractères multioctets.wcsnlen et wcsnlen_l sont des versions à caractères larges d' strnlen et d' strnlen_l respectivement ; les arguments pour wcsnlen et wcsnlen_l sont des chaînes à caractères larges et le nombre de caractères sont dans des unités à caractères larges.Sinon, wcsnlen, wcsnlen_l, strnlen et strnlen_l se comportent de la même façon.

strnlen, wcsnlen, et _mbsnlen ne valident pas leurs paramètres.Si str est NULL, une violation d'accès se produit.

strnlen_s et wcsnlen_s validez leurs paramètres.Si str est NULL, retournent 0 de fonctions.

_mbstrnlen valide également ses paramètres.Si str est NULL, ou si numberOfElements est supérieur INT_MAX, _mbstrnlen génère une exception de paramètre non valide, comme décrit dans Validation des paramètres.Si est autorisé à l'exécution pour continuer, _mbstrnlen définit errno à EINVAL et retourne -1.

Mappages de routines de texte générique

Routine de TCHAR.H	_UNICODE et non définis _MBCS	_MBCS défini	_UNICODE défini
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen_l	_mbsnlen_l	wcsnlen_l

_mbsnlen et _mbstrnlen retournent le nombre de caractères multioctets dans une chaîne de caractères multioctets._mbsnlen identifie les séquences de caractères multioctets d'après la page de codes multioctets qui est en cours de utilisation ou en fonction de les paramètres régionaux passés dans ; ils ne déterminent pas la validité à caractères multioctets._mbstrnlen détermine la validité à caractères multioctets et identifie les séquences de caractères multioctets.Si la chaîne passée à _mbstrnlen contient un caractère multioctet non valide, errno a la valeur EILSEQ.

La valeur de sortie est affectée par la configuration de la définition de catégorie d' LC_CTYPE des paramètres régionaux ; consultez setlocale, _wsetlocale pour plus d'informations.Les versions de ces fonctions sont identiques, mais que celles qui n'ont pas l'utilisation de suffixe d' _l les paramètres régionaux définis pour ce comportement dépendant des paramètres régionaux et des versions qui font utiliser le suffixe d' _l à la place le paramètre de paramètres régionaux qui est passé.Pour plus d'informations, consultez Paramètres régionaux.

Configuration requise

Routine	En-tête requis
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>

Pour des informations de compatibilité supplémentaires, consultez Compatibilité.

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