|
1 | 1 | --- |
2 | 2 | title: "_mbclen, mblen, _mblen_l, _mbclen_l" |
3 | | -ms.date: "01/22/2019" |
| 3 | +description: "Describes the Microsoft C Runtime Library (CRT) _mbclen, mblen, _mblen_l, and _mbclen_l functions." |
| 4 | +ms.date: "01/08/2020" |
4 | 5 | api_name: ["_mbclen", "mblen", "_mblen_l", "_mbclen_l"] |
5 | 6 | api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] |
6 | 7 | api_type: ["DLLExport"] |
@@ -39,29 +40,33 @@ int _mblen_l( |
39 | 40 |
|
40 | 41 | ### Parameters |
41 | 42 |
|
42 | | -*c*<br/> |
| 43 | +*c*\ |
43 | 44 | Multibyte character. |
44 | 45 |
|
45 | | -*mbstr*<br/> |
| 46 | +*mbstr*\ |
46 | 47 | Address of a multibyte-character byte sequence. |
47 | 48 |
|
48 | | -*count*<br/> |
| 49 | +*count*\ |
49 | 50 | Number of bytes to check. |
50 | 51 |
|
51 | | -*locale*<br/> |
| 52 | +*locale*\ |
52 | 53 | Locale to use. |
53 | 54 |
|
54 | 55 | ## Return Value |
55 | 56 |
|
56 | | -**_mbclen** returns 1 or 2, according to whether the multibyte character *c* is 1 or 2 bytes long. There is no error return for **_mbclen**. If *mbstr* isn't **NULL**, **mblen** returns the length, in bytes, of the multibyte character. If *mbstr* is **NULL** or it points to the wide-character null character, **mblen** returns 0. When the object that *mbstr* points to doesn't form a valid multibyte character within the first *count* characters, **mblen** returns -1. |
| 57 | +**_mbclen** and **_mbclen_l** return 1 or 2, according to the length of the multibyte character *c*. The functions always return 1 for UTF-8, whether *c* is multibyte or not. There's no error return for **_mbclen**. |
| 58 | + |
| 59 | +If *mbstr* isn't **NULL**, **mblen** and **_mblen_l** return the length, in bytes, of the multibyte character. The **mblen** and **_mblen_l** functions work correctly on UTF-8, and may return a value between 1 and 3. When *mbstr* is **NULL** (or it points to the wide-character null character), **mblen** and **_mblen_l** return 0. The object that *mbstr* points to must form a valid multibyte character within the first *count* characters, or **mblen** and **_mblen_l** return -1. |
57 | 60 |
|
58 | 61 | ## Remarks |
59 | 62 |
|
60 | | -The **_mbclen** function returns the length, in bytes, of the multibyte character *c*. If *c* doesn't point to the lead byte of a multibyte character as determined by an implicit call to **_ismbblead**, the result of **_mbclen** is unpredictable. |
| 63 | +The **_mbclen** function returns the length, in bytes, of the multibyte character *c*. If *c* doesn't point to the lead byte of a multibyte character (as determined by an implicit call to [_ismbblead](ismbblead-ismbblead-l.md), the result of **_mbclen** is unpredictable. |
| 64 | + |
| 65 | +**mblen** returns the length in bytes of *mbstr* if it's a valid multibyte character. It also determines multibyte-character validity associated with the code page. **mblen** examines *count* or fewer bytes contained in *mbstr*, but not more than **MB_CUR_MAX** bytes. |
61 | 66 |
|
62 | | -**mblen** returns the length in bytes of *mbstr* if it's a valid multibyte character and determines multibyte-character validity associated with the code page. **mblen** examines *count* or fewer bytes contained in *mbstr*, but not more than **MB_CUR_MAX** bytes. |
| 67 | +The output value is affected by the **LC_CTYPE** category setting of the locale. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior. The **_l** suffixed versions behave the same, but they use the locale parameter passed in instead. For more information, see [setlocale](setlocale-wsetlocale.md) and [Locale](../../c-runtime-library/locale.md). |
63 | 68 |
|
64 | | -The output value is affected by the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior. The **_l** suffixed versions behave the same, but they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). |
| 69 | +**_mbclen**, **_mblen_l**, and **_mbclen_l** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **mblen** or **mbrlen** instead. |
65 | 70 |
|
66 | 71 | ### Generic-Text Routine Mappings |
67 | 72 |
|
@@ -120,8 +125,9 @@ Length in bytes of NULL multibyte character 0: 0 |
120 | 125 |
|
121 | 126 | ## See also |
122 | 127 |
|
123 | | -[Character Classification](../../c-runtime-library/character-classification.md)<br/> |
124 | | -[Locale](../../c-runtime-library/locale.md)<br/> |
125 | | -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)<br/> |
126 | | -[_mbccpy, _mbccpy_l](mbccpy-mbccpy-l.md)<br/> |
127 | | -[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)<br/> |
| 128 | +[Character Classification](../../c-runtime-library/character-classification.md)\ |
| 129 | +[Locale](../../c-runtime-library/locale.md)\ |
| 130 | +[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ |
| 131 | +[_mbccpy, _mbccpy_l](mbccpy-mbccpy-l.md)\ |
| 132 | +[mbrlen](mbrlen.md)\ |
| 133 | +[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) |
0 commit comments