From 8e1af606d52ea1e5749a2fff2f20a10397d578bb Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Mon, 24 Aug 2015 18:16:34 +0200 Subject: [PATCH] mbintowcr.3: Mention missing functions. --- lib/libc/locale/Makefile.inc | 8 +++--- lib/libc/locale/mbintowcr.3 | 52 ++++++++++++++++++++++++++++++------ 2 files changed, 49 insertions(+), 11 deletions(-) diff --git a/lib/libc/locale/Makefile.inc b/lib/libc/locale/Makefile.inc index cba093f926..b3945245ed 100644 --- a/lib/libc/locale/Makefile.inc +++ b/lib/libc/locale/Makefile.inc @@ -100,9 +100,11 @@ MLINKS+=mbtowc.3 mbtowc_l.3 MLINKS+=nl_langinfo.3 nl_langinfo_l.3 MLINKS+=tolower.3 tolower_l.3 MLINKS+=toupper.3 toupper_l.3 -MLINKS+=mbintowcr.3 wcrtombin.3 -MLINKS+=mbintowcr.3 wcrtoutf8.3 -MLINKS+=mbintowcr.3 utf8towcr.3 +MLINKS+=mbintowcr.3 mbintowcr_l.3 \ + mbintowcr.3 utf8towcr.3 \ + mbintowcr.3 wcrtombin.3 \ + mbintowcr.3 wcrtombin_l.3 \ + mbintowcr.3 wcrtoutf8.3 MLINKS+=wcrtomb.3 c16rtomb.3 wcrtomb.3 c32rtomb.3 wcrtomb.3 wcrtomb_l.3 MLINKS+=wcsftime.3 wcsftime_l.3 MLINKS+=wcsrtombs.3 wcsnrtombs.3 wcsrtombs.3 wcsnrtombs_l.3 \ diff --git a/lib/libc/locale/mbintowcr.3 b/lib/libc/locale/mbintowcr.3 index bde9df25ee..40a8498596 100644 --- a/lib/libc/locale/mbintowcr.3 +++ b/lib/libc/locale/mbintowcr.3 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 16, 2015 +.Dd August 24, 2015 .Dt MBINTOWCR 3 .Os .Sh NAME @@ -57,6 +57,17 @@ .Fa "char * restrict dst" "const wchar_t * restrict src" .Fa "size_t dlen" "size_t *slen" "int flags" .Fc +.In xlocale.h +.Ft size_t +.Fo mbintowcr_l +.Fa "wchar_t * restrict dst" "const char * restrict src" +.Fa "size_t dlen" "size_t *slen" "locale_t locale" "int flags" +.Fc +.Ft size_t +.Fo wcrtombin_l +.Fa "char * restrict dst" "const wchar_t * restrict src" +.Fa "size_t dlen" "size_t *slen" "locale_t locale" "int flags" +.Fc .Sh DESCRIPTION The .Fn mbintowcr @@ -158,6 +169,15 @@ is not set surrogates in the escape range will be de-escaped (giving us our encodings. In WCSBIN_STRICT mode this flag works slightly differently. If not specified no surrogates are allowed at all (escaped or otherwise), and if specified all surrogates are allowed and will never be de-escaped. +.Pp +The _l-suffixed versions of +.Fn mbintowcr +and +.Fn wcrtombin +take an explicit +.Fa locale +argument, whereas the +non-suffixed versions use the current global or per-thread locale. .Sh UTF-8B ESCAPE SEQUENCES Escaping is handled by converting one or more bytes in the byte sequence to the UTF-8B escape wchar (U+DC80 - U+DCFF). Most illegal sequences escape @@ -229,9 +249,13 @@ buffer loading loop to distinguish between an incomplete buffer and an error. .El .Sh RETURN VALUES The -.Fn mbintowcr +.Fn mbintowcr , +.Fn mbintowcr_l , +.Fn utf8towcr , +.Fn wcrtombin , +.Fn wcrtombin_l and -.Fn wcrtombin +.Fn wcrtoutf8 functions return the number of output elements generated and set *slen to the number of input elements converted. If an error occurs but the output buffer has already been populated, @@ -240,11 +264,19 @@ the first element will return the error. The caller is responsible for processing any error conditions before continuing. .Pp The -.Fn mbintowcr function can return a (size_t)-1 error if WCSBIN_STRICT is +.Fn mbintowcr , +.Fn mbintowcr_l +and +.Fn utf8towcr +functions can return a (size_t)-1 error if WCSBIN_STRICT is specified, and otherwise cannot. +.Pp The -.Fn wcrtombin -function can return a (size_t)-1 error if given an illegal wchar code, +.Fn wcrtombin , +.Fn wcrtombin_l +and +.Fn wcrtoutf8 +functions can return a (size_t)-1 error if given an illegal wchar code, as modified by flags. Any wchar code >= 0x80000000U always causes an error to be returned. .Sh ERRORS @@ -257,7 +289,11 @@ If an error is returned, errno will be set to EILSEQ. .Xr xlocale 3 .Sh STANDARDS The -.Fn mbintowcr +.Fn mbintowcr , +.Fn mbintowcr_l , +.Fn utf8towcr , +.Fn wcrtombin , +.Fn wcrtombin_l and -.Fn wcrtombin +.Fn wcrtoutf8 functions are non-standard extensions to libc. -- 2.41.0