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

Статья
06/09/2015

Получает длину строки, используя текущий или переданный в функцию языковой стандарт. Существуют более надежные и безопасные версии strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

Важно!

_mbsnlen, _mbsnlen_l, _mbstrnlen и _mbstrnlen_l нельзя использовать в приложениях, выполняемых в Среда выполнения Windows.Дополнительные сведения см. в разделе Функции CRT, не поддерживаемые с ключом /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 );

Параметры

str
Строка, завершающаяся символом NULL.
numberOfElements
Размер строкового буфера.
locale
Используемый языковой стандарт.

Возвращаемое значение

Эти функции возвращают число символов в строке, не включая завершающий символ NULL. Если в первых numberOfElements байтах строки (или расширенных символов для wcsnlen) нет завершающего символа NULL, возвращается numberOfElements, чтобы указать на условие ошибки; строки с завершающим символом NULL имеют длину, строго ограниченную numberOfElements.

_mbstrnlen и _mbstrnlen_l возвращают значение -1, если строка содержит недопустимый многобайтовый символ.

Заметки

Примечание

strnlen не является заменой strlen; функция strnlen предназначена только для вычисления размера входящих недоверенных данных в буфере известного размера, например в сетевом пакете.strnlen вычисляет длину, но не выходит за конец буфера, если строка не определена.В других ситуациях используйте strlen.(Это также применимо к функциям wcsnlen, _mbsnlen и _mbstrnlen.)

Каждая из этих функций возвращает число символов в str, не включая завершающий символ NULL. Однако strnlen и strnlen_s интерпретируют строку как строку однобайтовых символов, поэтому возвращаемое значение всегда равно числу байт, даже если строка содержит многобайтовые символы. wcsnlen и wcsnlen_s являются версиями strnlen и strnlen_s с расширенными символами; аргументы для wcsnlen и wcsnlen_s — строками расширенных символов, а число символов выражается в единицах расширенных символов. В противном случае поведение wcsnlen и strnlen идентично, как и strnlen_s и wcsnlen_s.

strnlen, wcsnlen, и _mbsnlen не проверяют свои параметры. Если значение параметра str — NULL, возникает нарушение доступа.

Функции strnlen_s и wcsnlen_s проверяют свои параметры. Если значение параметра str — NULL, функция возвращает значение 0.

_mbstrnlen также проверяет свои параметры. Если значение параметра str — NULL — или если numberOfElements больше INT_MAX, _mbstrnlen создает исключение недопустимого параметра, как описано в Проверка параметров. Если продолжение выполнения разрешено, _mbstrnlen задает для errno значение EINVAL и возвращает значение -1.

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE и _MBCS не определены	_MBCS определено	_UNICODE определено
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen	_mbsnlen_l	wcsnlen

_mbsnlen и _mbstrnlen возвращают число многобайтовых символов в строке многобайтовых символов. _mbsnlen распознает последовательности многобайтовых символов согласно используемой в данный момент кодовой странице многобайтовых символов или переданному в функцию языковому стандарту; она не проверяет допустимость многобайтовых символов. _mbstrnlen проверяет допустимость многобайтовых символов и распознает их последовательности. Если строка, передаваемая в _mbstrnlen, содержит недопустимый многобайтовый символ, для errno задается значение EILSEQ.

Выходное значение зависит от настройки категории LC_CTYPE языкового стандарта; дополнительные сведения см. в разделе setlocale, _wsetlocale. Версии этих функций идентичны за исключением того, что версии без суффикса _l используют текущий языковой стандарт для этого поведения, зависимого от языкового стандарта, а версии с суффиксом _l — параметр языкового стандарта, переданный в функцию. Для получения дополнительной информации см. Языковой стандарт.

Требования

Подпрограмма	Обязательный заголовок
strnlen, strnlen_s	<string.h>
wcsnlen, wcsnlen_s	<string.h> или <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

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