From 7d3de48c6627bb72c991c76cd5d8a010211db77a Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Fri, 27 Dec 2013 16:15:13 +0100 Subject: [PATCH] libc: Document some more *_l() functions. mbrtowc_l() mbsinit_l() mbstowcs_l() mbtowc_l() ungetwc_l() wcrtomb_l() wcsftime_l() wcstombs_l() wcswidth_l() wctomb_l() wcwidth_l() --- lib/libc/locale/Makefile.inc | 11 +++++++-- lib/libc/locale/mbrtowc.3 | 23 ++++++++++++++++-- lib/libc/locale/mbsinit.3 | 27 +++++++++++++++++---- lib/libc/locale/mbstowcs.3 | 34 +++++++++++++++++++++----- lib/libc/locale/mbtowc.3 | 46 ++++++++++++++++++++++++++++-------- lib/libc/locale/wcrtomb.3 | 19 +++++++++++++-- lib/libc/locale/wcsftime.3 | 31 ++++++++++++++++++++---- lib/libc/locale/wcstombs.3 | 36 ++++++++++++++++++++++------ lib/libc/locale/wctomb.3 | 41 +++++++++++++++++++++++++------- lib/libc/locale/wcwidth.3 | 29 ++++++++++++++++++----- lib/libc/stdio/Makefile.inc | 1 + lib/libc/stdio/ungetwc.3 | 29 +++++++++++++++++------ lib/libc/string/Makefile.inc | 1 + lib/libc/string/wcswidth.3 | 29 ++++++++++++++++++----- 14 files changed, 290 insertions(+), 67 deletions(-) diff --git a/lib/libc/locale/Makefile.inc b/lib/libc/locale/Makefile.inc index 03959a2fbb..be11c59755 100644 --- a/lib/libc/locale/Makefile.inc +++ b/lib/libc/locale/Makefile.inc @@ -88,13 +88,17 @@ MLINKS+=isxdigit.3 ishexnumber.3 isxdigit.3 ishexnumber_l.3 \ MLINKS+=localeconv.3 localeconv_l.3 MLINKS+=mblen.3 mblen_l.3 MLINKS+=mbrlen.3 mbrlen_l.3 -MLINKS+=mbrtowc.3 mbrtoc16.3 mbrtowc.3 mbrtoc32.3 +MLINKS+=mbrtowc.3 mbrtoc16.3 mbrtowc.3 mbrtoc32.3 mbrtowc.3 mbrtowc_l.3 +MLINKS+=mbsinit.3 mbsinit_l.3 MLINKS+=mbsrtowcs.3 mbsnrtowcs.3 mbsrtowcs.3 mbsnrtowcs_l.3 \ mbsrtowcs.3 mbsrtowcs_l.3 +MLINKS+=mbstowcs.3 mbstowcs_l.3 +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+=wcrtomb.3 c16rtomb.3 wcrtomb.3 c32rtomb.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 \ wcsrtombs.3 wcsrtombs_l.3 MLINKS+=wcstod.3 wcstod_l.3 wcstod.3 wcstof.3 wcstod.3 wcstof_l.3 \ @@ -103,6 +107,9 @@ MLINKS+=wcstol.3 wcstol_l.3 wcstol.3 wcstoul.3 wcstol.3 wcstoul_l.3 \ wcstol.3 wcstoll.3 wcstol.3 wcstoll_l.3 wcstol.3 wcstoull.3 \ wcstol.3 wcstoull_l.3 wcstol.3 wcstoimax.3 wcstol.3 wcstoimax_l.3 \ wcstol.3 wcstoumax.3 wcstol.3 wcstoumax_l.3 +MLINKS+=wcstombs.3 wcstombs_l.3 +MLINKS+=wctomb.3 wctomb_l.3 MLINKS+=wctrans.3 towctrans.3 MLINKS+=wctype.3 iswctype.3 +MLINKS+=wcwidth.3 wcwidth_l.3 .endif diff --git a/lib/libc/locale/mbrtowc.3 b/lib/libc/locale/mbrtowc.3 index c997479117..42c18c8dff 100644 --- a/lib/libc/locale/mbrtowc.3 +++ b/lib/libc/locale/mbrtowc.3 @@ -24,11 +24,12 @@ .\" .\" $FreeBSD: head/lib/libc/locale/mbrtowc.3 250883 2013-05-21 19:59:37Z ed $ .\" -.Dd May 21, 2013 +.Dd December 26, 2013 .Dt MBRTOWC 3 .Os .Sh NAME .Nm mbrtowc , +.Nm mbrtowc_l , .Nm mbrtoc16 , .Nm mbrtoc32 .Nd "convert a character to a wide-character code (restartable)" @@ -52,9 +53,16 @@ .Fa "char32_t * restrict pc" "const char * restrict s" "size_t n" .Fa "mbstate_t * restrict ps" .Fc +.In xlocale.h +.Ft size_t +.Fo mbrtowc_l +.Fa "wchar_t * restrict pc" "const char * restrict s" "size_t n" +.Fa "mbstate_t * restrict ps" "locale_t locale" +.Fc .Sh DESCRIPTION The .Fn mbrtowc , +.Fn mbrtowc_l , .Fn mbrtoc16 and .Fn mbrtoc32 @@ -110,9 +118,18 @@ is not large enough to represent certain multibyte characters, the .Fn mbrtoc16 function may need to be invoked multiple times to convert a single multibyte character sequence. +.Pp +The +.Fn mbrtowc_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn mbrtowc +function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn mbrtowc , +.Fn mbrtowc_l , .Fn mbrtoc16 and .Fn mbrtoc32 @@ -154,6 +171,7 @@ No bytes from the input have been consumed. .Sh ERRORS The .Fn mbrtowc , +.Fn mbrtowc_l , .Fn mbrtoc16 and .Fn mbrtoc32 @@ -168,7 +186,8 @@ The conversion state is invalid. .Xr mbtowc 3 , .Xr multibyte 3 , .Xr setlocale 3 , -.Xr wcrtomb 3 +.Xr wcrtomb 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn mbrtowc , diff --git a/lib/libc/locale/mbsinit.3 b/lib/libc/locale/mbsinit.3 index 0951aee073..56e882567e 100644 --- a/lib/libc/locale/mbsinit.3 +++ b/lib/libc/locale/mbsinit.3 @@ -24,11 +24,12 @@ .\" .\" $FreeBSD: head/lib/libc/locale/mbsinit.3 128032 2004-04-08 09:59:02Z tjr $ .\" -.Dd April 8, 2004 +.Dd December 26, 2013 .Dt MBSINIT 3 .Os .Sh NAME -.Nm mbsinit +.Nm mbsinit , +.Nm mbsinit_l .Nd "determine conversion object status" .Sh LIBRARY .Lb libc @@ -36,18 +37,33 @@ .In wchar.h .Ft int .Fn mbsinit "const mbstate_t *ps" +.In xlocale.h +.Ft int +.Fn mbsinit_l "const mbstate_t *ps" "locale_t locale" .Sh DESCRIPTION The .Fn mbsinit -function determines whether the +and +.Fn mbsinit_l +functions determine whether the .Vt mbstate_t object pointed to by .Fa ps describes an initial conversion state. +.Pp +The +.Fn mbsinit_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn mbsinit +function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn mbsinit -function returns non-zero if +and +.Fn mbsinit_l +functions return non-zero if .Fa ps is .Dv NULL @@ -59,7 +75,8 @@ otherwise it returns zero. .Xr mbsrtowcs 3 , .Xr multibyte 3 , .Xr wcrtomb 3 , -.Xr wcsrtombs 3 +.Xr wcsrtombs 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn mbsinit diff --git a/lib/libc/locale/mbstowcs.3 b/lib/libc/locale/mbstowcs.3 index a148382ce9..2e5473e682 100644 --- a/lib/libc/locale/mbstowcs.3 +++ b/lib/libc/locale/mbstowcs.3 @@ -33,11 +33,12 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD: head/lib/libc/locale/mbstowcs.3 165903 2007-01-09 00:28:16Z imp $ .\" -.Dd April 8, 2004 +.Dd December 26, 2013 .Dt MBSTOWCS 3 .Os .Sh NAME -.Nm mbstowcs +.Nm mbstowcs , +.Nm mbstowcs_l .Nd convert a character string to a wide-character string .Sh LIBRARY .Lb libc @@ -48,10 +49,18 @@ .Fa "wchar_t * restrict wcstring" "const char * restrict mbstring" .Fa "size_t nwchars" .Fc +.In xlocale.h +.Ft size_t +.Fo mbstowcs_l +.Fa "wchar_t * restrict wcstring" "const char * restrict mbstring" +.Fa "size_t nwchars" "locale_t locale" +.Fc .Sh DESCRIPTION The .Fn mbstowcs -function converts a multibyte character string +and +.Fn mbstowcs_l +functions convert a multibyte character string .Fa mbstring beginning in the initial conversion state into a wide character string @@ -60,16 +69,28 @@ No more than .Fa nwchars wide characters are stored. A terminating null wide character is appended if there is room. +.Pp +The +.Fn mbstowcs_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn mbstowcs +function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn mbstowcs -function returns the number of wide characters converted, +and +.Fn mbstowcs_l +functions return the number of wide characters converted, not counting any terminating null wide character, or \-1 if an invalid multibyte character was encountered. .Sh ERRORS The .Fn mbstowcs -function will fail if: +and +.Fn mbstowcs_l +functions will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid multibyte sequence was detected. @@ -79,7 +100,8 @@ The conversion state is invalid. .Sh SEE ALSO .Xr mbsrtowcs 3 , .Xr mbtowc 3 , -.Xr multibyte 3 +.Xr multibyte 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn mbstowcs diff --git a/lib/libc/locale/mbtowc.3 b/lib/libc/locale/mbtowc.3 index 885b960db4..b86da4e8ac 100644 --- a/lib/libc/locale/mbtowc.3 +++ b/lib/libc/locale/mbtowc.3 @@ -33,11 +33,12 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD: head/lib/libc/locale/mbtowc.3 165903 2007-01-09 00:28:16Z imp $ .\" -.Dd April 11, 2004 +.Dd December 26, 2013 .Dt MBTOWC 3 .Os .Sh NAME -.Nm mbtowc +.Nm mbtowc , +.Nm mbtowc_l .Nd convert a character to a wide-character code .Sh LIBRARY .Lb libc @@ -48,10 +49,18 @@ .Fa "wchar_t * restrict wcharp" "const char * restrict mbchar" .Fa "size_t nbytes" .Fc +.In xlocale.h +.Ft int +.Fo mbtowc_l +.Fa "wchar_t * restrict wcharp" "const char * restrict mbchar" +.Fa "size_t nbytes" "locale_t locale" +.Fc .Sh DESCRIPTION The .Fn mbtowc -function converts a multibyte character +and +.Fn mbtowc_l +functions convert a multibyte character .Fa mbchar into a wide character according to the current conversion state, and stores the result @@ -66,6 +75,14 @@ A call with a null pointer returns nonzero if the current encoding requires shift states, zero otherwise; if shift states are required, the shift state is reset to the initial state. +.Pp +The +.Fn mbtowc_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn mbtowc +function uses the current global or per-thread locale. .Sh RETURN VALUES If .Fa mbchar @@ -73,27 +90,35 @@ is .Dv NULL , the .Fn mbtowc -function returns nonzero if shift states are supported, +and +.Fn mbtowc_l +functions return nonzero if shift states are supported, zero otherwise. .Pp Otherwise, if .Fa mbchar is not a null pointer, .Fn mbtowc -either returns 0 if +and +.Fn mbtowc_l +either return 0 if .Fa mbchar -represents the null wide character, or returns +represents the null wide character, or return the number of bytes processed in .Fa mbchar , -or returns \-1 if no multibyte character +or return \-1 if no multibyte character could be recognized or converted. In this case, .Fn mbtowc Ns 's -internal conversion state is undefined. +and +.Fn mbtowc_l Ns 's +internal conversion states are undefined. .Sh ERRORS The .Fn mbtowc -function will fail if: +and +.Fn mbtowc_l +functions will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid multibyte sequence was detected. @@ -106,7 +131,8 @@ The internal conversion state is invalid. .Xr mbrtowc 3 , .Xr mbstowcs 3 , .Xr multibyte 3 , -.Xr wctomb 3 +.Xr wctomb 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn mbtowc diff --git a/lib/libc/locale/wcrtomb.3 b/lib/libc/locale/wcrtomb.3 index e7d9859de6..b0abf22b02 100644 --- a/lib/libc/locale/wcrtomb.3 +++ b/lib/libc/locale/wcrtomb.3 @@ -24,11 +24,12 @@ .\" .\" $FreeBSD: head/lib/libc/locale/wcrtomb.3 250883 2013-05-21 19:59:37Z ed $ .\" -.Dd May 21, 2013 +.Dd December 26, 2013 .Dt WCRTOMB 3 .Os .Sh NAME .Nm wcrtomb , +.Nm wcrtomb_l , .Nm c16rtomb , .Nm c32rtomb .Nd "convert a wide-character code to a character (restartable)" @@ -43,9 +44,13 @@ .Fn c16rtomb "char * restrict s" "char16_t c" "mbstate_t * restrict ps" .Ft size_t .Fn c32rtomb "char * restrict s" "char32_t c" "mbstate_t * restrict ps" +.In xlocale.h +.Ft size_t +.Fn wcrtomb_l "char * restrict s" "wchar_t c" "mbstate_t * restrict ps" "locale_t locale" .Sh DESCRIPTION The .Fn wcrtomb , +.Fn wcrtomb_l , .Fn c16rtomb and .Fn c32rtomb @@ -86,6 +91,14 @@ As certain multibyte characters may only be represented by a series of .Fn c16rtomb may need to invoked multiple times before a multibyte sequence is returned. +.Pp +The +.Fn wcrtomb_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn wcrtomb +function uses the current global or per-thread locale. .Sh RETURN VALUES These functions return the length (in bytes) of the multibyte sequence needed to represent @@ -98,6 +111,7 @@ is not a valid wide character code. .Sh ERRORS The .Fn wcrtomb , +.Fn wcrtomb_l , .Fn c16rtomb and .Fn c32rtomb @@ -112,7 +126,8 @@ The conversion state is invalid. .Xr mbrtowc 3 , .Xr multibyte 3 , .Xr setlocale 3 , -.Xr wctomb 3 +.Xr wctomb 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn wcrtomb , diff --git a/lib/libc/locale/wcsftime.3 b/lib/libc/locale/wcsftime.3 index 67a12c6291..462948de48 100644 --- a/lib/libc/locale/wcsftime.3 +++ b/lib/libc/locale/wcsftime.3 @@ -24,11 +24,12 @@ .\" .\" $FreeBSD: head/lib/libc/locale/wcsftime.3 107392 2002-11-29 17:35:09Z ru $ .\" -.Dd September 8, 2002 +.Dd December 26, 2013 .Dt WCSFTIME 3 .Os .Sh NAME -.Nm wcsftime +.Nm wcsftime , +.Nm wcsftime_l .Nd "convert date and time to a wide-character string" .Sh LIBRARY .Lb libc @@ -39,15 +40,34 @@ .Fa "wchar_t * restrict wcs" "size_t maxsize" .Fa "const wchar_t * restrict format" "const struct tm * restrict timeptr" .Fc +.In xlocale.h +.Ft size_t +.Fo wcsftime_l +.Fa "wchar_t * restrict wcs" "size_t maxsize" +.Fa "const wchar_t * restrict format" "const struct tm * restrict timeptr" +.Fa "locale_t locale" +.Fc .Sh DESCRIPTION The .Fn wcsftime -function is equivalent to the +and +.Fn wcsftime_l +functions are equivalent to the .Fn strftime -function except for the types of its arguments. +and +.Fn strftime_l +functions except for the types of their arguments. Refer to .Xr strftime 3 for a detailed description. +.Pp +The +.Fn wcsftime_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn wcsftime +function uses the current global or per-thread locale. .Sh COMPATIBILITY Some early implementations of .Fn wcsftime @@ -58,7 +78,8 @@ argument with type instead of .Vt "const wchar_t *" . .Sh SEE ALSO -.Xr strftime 3 +.Xr strftime 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn wcsftime diff --git a/lib/libc/locale/wcstombs.3 b/lib/libc/locale/wcstombs.3 index 18c23dacce..70c705683e 100644 --- a/lib/libc/locale/wcstombs.3 +++ b/lib/libc/locale/wcstombs.3 @@ -33,11 +33,12 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD: head/lib/libc/locale/wcstombs.3 165903 2007-01-09 00:28:16Z imp $ .\" -.Dd April 8, 2004 +.Dd December 27, 2013 .Dt WCSTOMBS 3 .Os .Sh NAME -.Nm wcstombs +.Nm wcstombs , +.Nm wcstombs_l .Nd convert a wide-character string to a character string .Sh LIBRARY .Lb libc @@ -48,10 +49,18 @@ .Fa "char * restrict mbstring" "const wchar_t * restrict wcstring" .Fa "size_t nbytes" .Fc +.In xlocale.h +.Ft size_t +.Fo wcstombs_l +.Fa "char * restrict mbstring" "const wchar_t * restrict wcstring" +.Fa "size_t nbytes" "locale_t locale" +.Fc .Sh DESCRIPTION The .Fn wcstombs -function converts a wide character string +and +.Fn wcstombs_l +functions convert a wide character string .Fa wcstring into a multibyte character string, .Fa mbstring , @@ -62,16 +71,28 @@ bytes are stored in .Fa mbstring . Partial multibyte characters at the end of the string are not stored. The multibyte character string is null terminated if there is room. +.Pp +The +.Fn wcstombs_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn wcstombs +function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn wcstombs -function returns the number of bytes converted -(not including any terminating null), if successful, otherwise it returns +and +.Fn wcstombs_l +functions return the number of bytes converted +(not including any terminating null), if successful, otherwise they return .Po Vt size_t Pc Ns \-1 . .Sh ERRORS The .Fn wcstombs -function will fail if: +and +.Fn wcstombs_l +functions will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid wide character was encountered. @@ -82,7 +103,8 @@ The conversion state is invalid. .Xr mbstowcs 3 , .Xr multibyte 3 , .Xr wcsrtombs 3 , -.Xr wctomb 3 +.Xr wctomb 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn wcstombs diff --git a/lib/libc/locale/wctomb.3 b/lib/libc/locale/wctomb.3 index 64a45d121e..1ef58e5d3c 100644 --- a/lib/libc/locale/wctomb.3 +++ b/lib/libc/locale/wctomb.3 @@ -33,11 +33,12 @@ .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD: head/lib/libc/locale/wctomb.3 165903 2007-01-09 00:28:16Z imp $ .\" -.Dd April 8, 2004 +.Dd December 27, 2013 .Dt WCTOMB 3 .Os .Sh NAME -.Nm wctomb +.Nm wctomb , +.Nm wctomb_l .Nd convert a wide-character code to a character .Sh LIBRARY .Lb libc @@ -45,12 +46,17 @@ .In stdlib.h .Ft int .Fn wctomb "char *mbchar" "wchar_t wchar" +.In xlocale.h +.Ft int +.Fn wctomb_l "char *mbchar" "wchar_t wchar" "locale_t locale" .Sh DESCRIPTION The .Fn wctomb -function converts a wide character +and +.Fn wctomb_l +functions convert a wide character .Fa wchar -into a multibyte character and stores +into a multibyte character and store the result in .Fa mbchar . The object pointed to by @@ -65,6 +71,14 @@ A call with a null pointer returns nonzero if the current locale requires shift states, zero otherwise; if shift states are required, the shift state is reset to the initial state. +.Pp +The +.Fn wctomb_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn wctomb +function uses the current global or per-thread locale. .Sh RETURN VALUES If .Fa mbchar @@ -72,24 +86,32 @@ is .Dv NULL , the .Fn wctomb -function returns nonzero if shift states are supported, +and +.Fn wctomb_l +functions return nonzero if shift states are supported, zero otherwise. If .Fa mbchar is valid, .Fn wctomb -returns +and +.Fn wctomb_l +return the number of bytes processed in .Fa mbchar , or \-1 if no multibyte character could be recognized or converted. In this case, .Fn wctomb Ns 's -internal conversion state is undefined. +and +.Fn wctomb_l Ns 's +internal conversion states are undefined. .Sh ERRORS The .Fn wctomb -function will fail if: +and +.Fn wctomb_l +functions will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid multibyte sequence was detected. @@ -100,7 +122,8 @@ The internal conversion state is invalid. .Xr mbtowc 3 , .Xr wcrtomb 3 , .Xr wcstombs 3 , -.Xr wctob 3 +.Xr wctob 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn wctomb diff --git a/lib/libc/locale/wcwidth.3 b/lib/libc/locale/wcwidth.3 index a3bbc7f5d6..3784eaa664 100644 --- a/lib/libc/locale/wcwidth.3 +++ b/lib/libc/locale/wcwidth.3 @@ -24,11 +24,12 @@ .\" .\" $FreeBSD: head/lib/libc/locale/wcwidth.3 133915 2004-08-17 04:56:03Z trhodes $ .\" -.Dd August 17, 2004 +.Dd December 27, 2013 .Dt WCWIDTH 3 .Os .Sh NAME -.Nm wcwidth +.Nm wcwidth , +.Nm wcwidth_l .Nd "number of column positions of a wide-character code" .Sh LIBRARY .Lb libc @@ -36,22 +37,37 @@ .In wchar.h .Ft int .Fn wcwidth "wchar_t wc" +.In xlocale.h +.Ft int +.Fn wcwidth_l "wchar_t wc" "locale_t locale" .Sh DESCRIPTION The .Fn wcwidth -function determines the number of column positions required to +and +.Fn wcwidth_l +functions determine the number of column positions required to display the wide character .Fa wc . +.Pp +The +.Fn wcwidth_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn wcwidth +function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn wcwidth -function returns 0 if the +and +.Fn wcwidth_l +functions return 0 if the .Fa wc argument is a null wide character (L'\e0'), \-1 if .Fa wc is not printable, -otherwise it returns the number of column positions the +otherwise they return the number of column positions the character occupies. .Sh EXAMPLES This code fragment reads text from standard input and @@ -79,7 +95,8 @@ while ((ch = getwchar()) != WEOF) { .Ed .Sh SEE ALSO .Xr iswprint 3 , -.Xr wcswidth 3 +.Xr wcswidth 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn wcwidth diff --git a/lib/libc/stdio/Makefile.inc b/lib/libc/stdio/Makefile.inc index 47688d8ad8..a349b86838 100644 --- a/lib/libc/stdio/Makefile.inc +++ b/lib/libc/stdio/Makefile.inc @@ -82,6 +82,7 @@ MLINKS+=scanf_l.3 fscanf_l.3 scanf_l.3 sscanf_l.3 scanf_l.3 vfscanf_l.3 \ scanf_l.3 vscanf_l.3 scanf_l.3 vsscanf_l.3 MLINKS+=setbuf.3 setbuffer.3 setbuf.3 setlinebuf.3 setbuf.3 setvbuf.3 MLINKS+=tmpnam.3 tempnam.3 tmpnam.3 tmpfile.3 +MLINKS+=ungetwc.3 ungetwc_l.3 MLINKS+=wprintf.3 fwprintf.3 wprintf.3 swprintf.3 wprintf.3 vwprintf.3 \ wprintf.3 vfwprintf.3 wprintf.3 vswprintf.3 MLINKS+=wprintf_l.3 fwprintf_l.3 wprintf_l.3 swprintf_l.3 \ diff --git a/lib/libc/stdio/ungetwc.3 b/lib/libc/stdio/ungetwc.3 index 0a1720ad47..c180aa0a04 100644 --- a/lib/libc/stdio/ungetwc.3 +++ b/lib/libc/stdio/ungetwc.3 @@ -34,11 +34,12 @@ .\" @(#)ungetc.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD: head/lib/libc/stdio/ungetwc.3 165903 2007-01-09 00:28:16Z imp $ .\" -.Dd March 3, 2004 +.Dd December 26, 2013 .Dt UNGETWC 3 .Os .Sh NAME -.Nm ungetwc +.Nm ungetwc , +.Nm ungetwc_l .Nd un-get wide character from input stream .Sh LIBRARY .Lb libc @@ -47,10 +48,15 @@ .In wchar.h .Ft wint_t .Fn ungetwc "wint_t wc" "FILE *stream" +.In xlocale.h +.Ft wint_t +.Fn ungetwc_l "wint_t wc" "FILE *stream" "locale_t locale" .Sh DESCRIPTION The .Fn ungetwc -function pushes the wide character +and +.Fn ungetwc_l +functions push the wide character .Fa wc (converted to an .Vt wchar_t ) @@ -72,12 +78,20 @@ sufficient memory, an effectively infinite amount of pushback is allowed. .Pp If a character is successfully pushed-back, the end-of-file indicator for the stream is cleared. +.Pp +The +.Fn ungetwc_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn ungetwc +function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn ungetwc -function -returns -the wide character pushed-back after the conversion, or +and +.Fn ungetwc_l +functions return the wide character pushed-back after the conversion, or .Dv WEOF if the operation fails. If the value of the argument @@ -87,7 +101,8 @@ character equals the operation will fail and the stream will remain unchanged. .Sh SEE ALSO .Xr fseek 3 , -.Xr getwc 3 +.Xr getwc 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn ungetwc diff --git a/lib/libc/string/Makefile.inc b/lib/libc/string/Makefile.inc index ba9289f80f..93a1ee8b0c 100644 --- a/lib/libc/string/Makefile.inc +++ b/lib/libc/string/Makefile.inc @@ -69,6 +69,7 @@ MLINKS+=strstr.3 strcasestr.3 \ MLINKS+=strtok.3 strtok_r.3 MLINKS+=strxfrm.3 strxfrm_l.3 MLINKS+=wcscoll.3 wcscoll_l.3 +MLINKS+=wcswidth.3 wcswidth_l.3 MLINKS+=wcsxfrm.3 wcsxfrm_l.3 MLINKS+=wmemchr.3 wcpcpy.3 \ wmemchr.3 wcpncpy.3 \ diff --git a/lib/libc/string/wcswidth.3 b/lib/libc/string/wcswidth.3 index a1f049fec4..9e3dad6ef0 100644 --- a/lib/libc/string/wcswidth.3 +++ b/lib/libc/string/wcswidth.3 @@ -24,11 +24,12 @@ .\" .\" $FreeBSD: head/lib/libc/string/wcswidth.3 107706 2002-12-09 14:04:05Z ru $ .\" -.Dd August 20, 2002 +.Dd December 27, 2013 .Dt WCSWIDTH 3 .Os .Sh NAME -.Nm wcswidth +.Nm wcswidth , +.Nm wcswidth_l .Nd "number of column positions in wide-character string" .Sh LIBRARY .Lb libc @@ -36,25 +37,41 @@ .In wchar.h .Ft int .Fn wcswidth "const wchar_t *pwcs" "size_t n" +.In xlocale.h +.Ft int +.Fn wcswidth_l "const wchar_t *pwcs" "size_t n" "locale_t locale" .Sh DESCRIPTION The .Fn wcswidth -function determines the number of column positions required for the first +and +.Fn wcswidth_l +functions determine the number of column positions required for the first .Fa n characters of .Fa pwcs , or until a null wide character (L'\e0') is encountered. +.Pp +The +.Fn wcswidth_l +function takes an explicit +.Fa locale +argument, whereas the +.Fn wcswidth +function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn wcswidth -function returns 0 if +and +.Fn wcswidth_l +functions return 0 if .Fa pwcs is an empty string (L""), \-1 if a non-printing wide character is encountered, -otherwise it returns the number of column positions occupied. +otherwise they return the number of column positions occupied. .Sh SEE ALSO .Xr iswprint 3 , -.Xr wcwidth 3 +.Xr wcwidth 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn wcswidth -- 2.41.0