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

Pobiera długość ciągu przy użyciu bieżących ustawień regionalnych lub tych, które zostały przekazane. Te funkcje są bezpieczniejsze wersje strlen, , wcslen, _mbslen_mbslen_l, _mbstrlen, _mbstrlen_l.

Ważne

_mbsnlen, _mbsnlen_l, _mbstrnleni _mbstrnlen_l nie można używać w aplikacjach wykonywanych w środowisko wykonawcze systemu Windows. Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane w aplikacjach platforma uniwersalna systemu Windows.

Składnia

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

Parametry

str
Ciąg zakończony wartością null.

numberOfElements
Rozmiar buforu ciągu.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Te funkcje zwracają liczbę znaków w ciągu, a nie w tym znak null zakończenia. Jeśli w pierwszych numberOfElements bajtach ciągu (lub znakach szerokich wcsnlen) nie ma wartości null, zwracany jest parametr , aby numberOfElements wskazać warunek błędu; ciągi zakończone wartością null mają długości, które są ściśle mniejsze niż numberOfElements.

_mbstrnlen i _mbstrnlen_l zwraca -1, jeśli ciąg zawiera nieprawidłowy znak wielobajtowy.

Uwagi

Uwaga

strnlen nie strlenzastępuje elementu ; strnlen ma być używany tylko do obliczania rozmiaru przychodzących niezaufanych danych w buforze o znanym rozmiarze — na przykład pakietu sieciowego. strnlen oblicza długość, ale nie przechodzi poza koniec buforu, jeśli ciąg jest nieokreślony. W innych sytuacjach użyj polecenia strlen. (To samo dotyczy wcsnlen, _mbsnleni _mbstrnlen.)

Każda z tych funkcji zwraca liczbę znaków w strelemecie , a nie zawiera znaku zerowego zakończenia. strnlen Jednak i strnlen_s interpretować ciąg jako ciąg znaków jednobajtowych, a zatem wartość zwracana jest zawsze równa liczbie bajtów, nawet jeśli ciąg zawiera znaki wielobajtowe. wcsnlen i wcsnlen_s są odpowiednio wersjami strnlen znaków i strnlen_s ; argumenty dla wcsnlen i wcsnlen_s są ciągami szerokoznakowymi, a liczba znaków jest w jednostkach szerokich znaków. wcsnlen W przeciwnym razie i strnlen zachowują się identycznie, jak strnlen_s i wcsnlen_s.

strnlen, wcsnleni _mbsnlen nie weryfikuj ich parametrów. Jeśli str jest NULLto , następuje naruszenie dostępu.

strnlen_s i wcsnlen_s zweryfikuj ich parametry. Jeśli str parametr ma NULLwartość , funkcje zwracają wartość 0.

_mbstrnlen weryfikuje również jego parametry. Jeśli str parametr ma NULLwartość , lub numberOfElements jest większy niż INT_MAX, _mbstrnlen generuje nieprawidłowy wyjątek parametru, zgodnie z opisem w temacie Walidacja parametru. Jeśli wykonywanie jest dozwolone do kontynuowania, _mbstrnlen ustawia wartość EINVALerrno i zwraca wartość -1.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

TCHAR.H Rutynowych	_UNICODE i _MBCS niezdefiniowane	_MBCS Zdefiniowane	_UNICODE Zdefiniowane
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen	_mbsnlen_l	wcsnlen

_mbsnlen i _mbstrnlen zwraca liczbę znaków wielobajtowych w ciągu wielobajtowym. _mbsnlen rozpoznaje sekwencje wielobajtowe według strony kodowej wielobajtowej, która jest obecnie używana lub zgodnie z ustawieniami regionalnymi, które są przekazywane; nie testuje ważności znaków wielobajtowych. _mbstrnlen testuje ważność znaków wielobajtowych i rozpoznaje sekwencje znaków wielobajtowych. Jeśli przekazany _mbstrnlen ciąg zawiera nieprawidłowy znak wielobajtowy, errno jest ustawiony na EILSEQwartość .

Na wartość wyjściową ma wpływ ustawienie LC_CTYPE ustawienia kategorii ustawień regionalnych. W celu uzyskania więcej informacji, zobacz następujący temat: setlocale. Wersje tych funkcji są identyczne, z tą różnicą, że te, które nie mają _l sufiksu, używają bieżących ustawień regionalnych dla tego zachowania zależnego od ustawień regionalnych i wersji, które mają _l sufiks, zamiast tego używają parametru ustawień regionalnych, który jest przekazywany. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

Wymagania

Procedura	Wymagany nagłówek
strnlen, strnlen_s	<string.h>
wcsnlen, wcsnlen_s	<string.h> lub <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład

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

Zobacz też

Manipulowanie ciągami
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
setlocale, _wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strcoll, funkcje
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