Module Name: src
Committed By: martin
Date: Fri Oct 11 17:35:47 UTC 2024
Modified Files:
src/distrib/sets/lists/comp [netbsd-9]: mi
src/lib/libc/locale [netbsd-9]: Makefile.inc mbsrtowcs.3 wcsrtombs.3
Log Message:
Pull up following revision(s) (requested by riastradh in ticket #1897):
lib/libc/locale/mbsrtowcs.3: revision 1.14
lib/libc/locale/mbsrtowcs.3: revision 1.15
lib/libc/locale/wcsrtombs.3: revision 1.14
lib/libc/locale/wcsrtombs.3: revision 1.15
lib/libc/locale/wcsrtombs.3: revision 1.16
distrib/sets/lists/comp/mi: revision 1.2473
lib/libc/locale/Makefile.inc: revision 1.68
lib/libc/locale/mbsrtowcs.3: revision 1.13
mbsnrtowcs(3), wcsnrtombs(3): Add man pages for these mouthfuls.
Based on patch drafted by abhinav@, with a little additional tidying
by me.
PR standards/52343: wcsnrtombs missing man-page
mbsnrtowcs(3), wcsnrtombs(3): brush ip markup
SYNOPSIS fixes, uppercase NUL and NULL
To generate a diff of this commit:
cvs rdiff -u -r1.2278.2.8 -r1.2278.2.9 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.64 -r1.64.28.1 src/lib/libc/locale/Makefile.inc
cvs rdiff -u -r1.12 -r1.12.48.1 src/lib/libc/locale/mbsrtowcs.3
cvs rdiff -u -r1.13 -r1.13.48.1 src/lib/libc/locale/wcsrtombs.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2278.2.8 src/distrib/sets/lists/comp/mi:1.2278.2.9
--- src/distrib/sets/lists/comp/mi:1.2278.2.8 Sat Jul 20 16:57:51 2024
+++ src/distrib/sets/lists/comp/mi Fri Oct 11 17:35:46 2024
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2278.2.8 2024/07/20 16:57:51 martin Exp $
+# $NetBSD: mi,v 1.2278.2.9 2024/10/11 17:35:46 martin Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -8390,6 +8390,7 @@
./usr/share/man/cat3/mbrlen.0 comp-c-catman .cat
./usr/share/man/cat3/mbrtowc.0 comp-c-catman .cat
./usr/share/man/cat3/mbsinit.0 comp-c-catman .cat
+./usr/share/man/cat3/mbsnrtowcs.0 comp-c-catman .cat
./usr/share/man/cat3/mbsrtowcs.0 comp-c-catman .cat
./usr/share/man/cat3/mbstowcs.0 comp-c-catman .cat
./usr/share/man/cat3/mbtowc.0 comp-c-catman .cat
@@ -10314,6 +10315,7 @@
./usr/share/man/cat3/wcsncmp.0 comp-c-catman .cat
./usr/share/man/cat3/wcsncpy.0 comp-c-catman .cat
./usr/share/man/cat3/wcsnlen.0 comp-c-catman .cat
+./usr/share/man/cat3/wcsnrtombs.0 comp-c-catman .cat
./usr/share/man/cat3/wcspbrk.0 comp-c-catman .cat
./usr/share/man/cat3/wcsrchr.0 comp-c-catman .cat
./usr/share/man/cat3/wcsrtombs.0 comp-c-catman .cat
@@ -16382,6 +16384,7 @@
./usr/share/man/html3/mbrlen.html comp-c-htmlman html
./usr/share/man/html3/mbrtowc.html comp-c-htmlman html
./usr/share/man/html3/mbsinit.html comp-c-htmlman html
+./usr/share/man/html3/mbsnrtowcs.html comp-c-htmlman html
./usr/share/man/html3/mbsrtowcs.html comp-c-htmlman html
./usr/share/man/html3/mbstowcs.html comp-c-htmlman html
./usr/share/man/html3/mbtowc.html comp-c-htmlman html
@@ -18283,6 +18286,7 @@
./usr/share/man/html3/wcsncmp.html comp-c-htmlman html
./usr/share/man/html3/wcsncpy.html comp-c-htmlman html
./usr/share/man/html3/wcsnlen.html comp-c-htmlman html
+./usr/share/man/html3/wcsnrtombs.html comp-c-htmlman html
./usr/share/man/html3/wcspbrk.html comp-c-htmlman html
./usr/share/man/html3/wcsrchr.html comp-c-htmlman html
./usr/share/man/html3/wcsrtombs.html comp-c-htmlman html
@@ -24379,6 +24383,7 @@
./usr/share/man/man3/mbrlen.3 comp-c-man .man
./usr/share/man/man3/mbrtowc.3 comp-c-man .man
./usr/share/man/man3/mbsinit.3 comp-c-man .man
+./usr/share/man/man3/mbsnrtowcs.3 comp-c-man .man
./usr/share/man/man3/mbsrtowcs.3 comp-c-man .man
./usr/share/man/man3/mbstowcs.3 comp-c-man .man
./usr/share/man/man3/mbtowc.3 comp-c-man .man
@@ -26322,6 +26327,7 @@
./usr/share/man/man3/wcsncmp.3 comp-c-man .man
./usr/share/man/man3/wcsncpy.3 comp-c-man .man
./usr/share/man/man3/wcsnlen.3 comp-c-man .man
+./usr/share/man/man3/wcsnrtombs.3 comp-c-man .man
./usr/share/man/man3/wcspbrk.3 comp-c-man .man
./usr/share/man/man3/wcsrchr.3 comp-c-man .man
./usr/share/man/man3/wcsrtombs.3 comp-c-man .man
Index: src/lib/libc/locale/Makefile.inc
diff -u src/lib/libc/locale/Makefile.inc:1.64 src/lib/libc/locale/Makefile.inc:1.64.28.1
--- src/lib/libc/locale/Makefile.inc:1.64 Sun Aug 18 20:03:48 2013
+++ src/lib/libc/locale/Makefile.inc Fri Oct 11 17:35:46 2024
@@ -1,5 +1,5 @@
# from: @(#)Makefile.inc 5.1 (Berkeley) 2/18/91
-# $NetBSD: Makefile.inc,v 1.64 2013/08/18 20:03:48 joerg Exp $
+# $NetBSD: Makefile.inc,v 1.64.28.1 2024/10/11 17:35:46 martin Exp $
# locale sources
.PATH: ${ARCHDIR}/locale ${.CURDIR}/locale
@@ -52,4 +52,7 @@ MLINKS+=wcstod.3 wcstof.3 wcstod.3 wcsto
MLINKS+=wcstol.3 wcstoll.3 wcstol.3 wcstoimax.3 \
wcstol.3 wcstoul.3 wcstol.3 wcstoull.3 wcstol.3 wcstoumax.3
+MLINKS+=mbsrtowcs.3 mbsnrtowcs.3
+MLINKS+=wcsrtombs.3 wcsnrtombs.3
+
COPTS.wcsftime.c = -Wno-format-nonliteral
Index: src/lib/libc/locale/mbsrtowcs.3
diff -u src/lib/libc/locale/mbsrtowcs.3:1.12 src/lib/libc/locale/mbsrtowcs.3:1.12.48.1
--- src/lib/libc/locale/mbsrtowcs.3:1.12 Thu Dec 16 17:42:27 2010
+++ src/lib/libc/locale/mbsrtowcs.3 Fri Oct 11 17:35:46 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: mbsrtowcs.3,v 1.12 2010/12/16 17:42:27 wiz Exp $
+.\" $NetBSD: mbsrtowcs.3,v 1.12.48.1 2024/10/11 17:35:46 martin Exp $
.\"
.\" Copyright (c)2002 Citrus Project,
.\" All rights reserved.
@@ -24,12 +24,13 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd February 4, 2002
+.Dd September 9, 2024
.Dt MBSRTOWCS 3
.Os
.\" ----------------------------------------------------------------------
.Sh NAME
-.Nm mbsrtowcs
+.Nm mbsrtowcs ,
+.Nm mbsrntowcs
.Nd converts a multibyte character string to a wide-character string \
(restartable)
.\" ----------------------------------------------------------------------
@@ -37,15 +38,32 @@
.Lb libc
.\" ----------------------------------------------------------------------
.Sh SYNOPSIS
+.
.In wchar.h
+.
.Ft size_t
-.Fn mbsrtowcs "wchar_t * restrict pwcs" "const char ** restrict s" "size_t n" \
-"mbstate_t * restrict ps"
+.Fo mbsrtowcs
+.Fa "wchar_t * restrict pwcs"
+.Fa "const char ** restrict s"
+.Fa "size_t n"
+.Fa "mbstate_t * restrict ps"
+.Fc
+.
+.Ft size_t
+.Fo mbsnrtowcs
+.Fa "wchar_t * restrict pwcs"
+.Fa "const char ** restrict s"
+.Fa "size_t nmc"
+.Fa "size_t n"
+.Fa "mbstate_t * restrict ps"
+.Fc
+.
.\" ----------------------------------------------------------------------
.Sh DESCRIPTION
The
.Fn mbsrtowcs
-converts the multibyte character string indirectly pointed to by
+function converts the multibyte character string indirectly pointed to
+by
.Fa s
to the corresponding wide-character string, and stores it in the
array pointed to by
@@ -53,8 +71,8 @@ array pointed to by
The conversion stops due to the following reasons:
.Bl -bullet
.It
-The conversion reaches a nul byte.
-In this case, the nul byte is also converted.
+The conversion reaches a NUL byte.
+In this case, the NUL byte is also converted.
.It
The
.Fn mbsrtowcs
@@ -72,17 +90,18 @@ is continuously called.
After conversion,
if
.Fa pwcs
-is not a null pointer,
+is not a NULL pointer,
the pointer object pointed to by
.Fa s
-is a null pointer (if the conversion is stopped due to reaching a
-nul byte) or the first byte of the character just after the last
-character converted.
+is a NULL pointer
+.Pq if the conversion is stopped due to reaching a NUL byte
+or the first byte of the character just after the last character
+converted.
.Pp
If
.Fa pwcs
-is not a null pointer and the conversion is stopped due to reaching
-a nul byte, the
+is not a NULL pointer and the conversion is stopped due to reaching
+a NUL byte, the
.Fn mbsrtowcs
places the state object pointed to by
.Fa ps
@@ -95,10 +114,12 @@ is affected by the
category of the current locale.
.Pp
These are the special cases:
-.Bl -tag -width 012345678901
-.It "s == NULL || *s == NULL"
+.Bl -tag -width Li
+.
+.It Li "s == NULL || *s == NULL"
Undefined (may cause the program to crash).
-.It "pwcs == NULL"
+.
+.It Li "pwcs == NULL"
The conversion has taken place, but the resulting wide-character string
was discarded.
In this case, the pointer object pointed to by
@@ -106,7 +127,8 @@ In this case, the pointer object pointed
is not modified and
.Fa n
is ignored.
-.It "ps == NULL"
+.
+.It Li "ps == NULL"
The
.Fn mbsrtowcs
uses its own internal state object to keep the conversion state,
@@ -120,16 +142,28 @@ never changes the internal state of
.Fn mbsrtowcs ,
which is initialized at startup time of the program.
.El
+.Pp
+The
+.Fn mbsnrtowcs
+function behaves identically to
+.Fn mbsrtowcs ,
+except that the conversion stops after reading at most
+.Fa nmc
+characters from the buffer pointed to by
+.Fa s .
.\" ----------------------------------------------------------------------
.Sh RETURN VALUES
+The
.Fn mbsrtowcs
-returns:
-.Bl -tag -width 012345678901
-.It 0 or positive
+and
+.Fn mbsnrtowcs
+functions return:
+.Bl -tag -width Li
+.It Li 0 , No or positive
The value returned is the number of elements stored in the array
pointed to by
.Fa pwcs ,
-except for a terminating nul wide character (if any).
+except for a terminating NUL wide character (if any).
If
.Fa pwcs
is not
@@ -138,12 +172,12 @@ and the value returned is equal to
.Fa n ,
the wide-character string pointed to by
.Fa pwcs
-is not nul-terminated.
+is not NUL-terminated.
If
.Fa pwcs
-is a null pointer, the value returned is the number of elements to contain
-the whole string converted, except for a terminating nul wide character.
-.It (size_t)-1
+is a NULL pointer, the value returned is the number of elements to contain
+the whole string converted, except for a terminating NUL wide character.
+.It Li "(size_t)-1"
The array indirectly pointed to by
.Fa s
contains a byte sequence forming invalid character.
@@ -155,13 +189,16 @@ to indicate the error.
.El
.\" ----------------------------------------------------------------------
.Sh ERRORS
+The
.Fn mbsrtowcs
-may cause an error in the following case:
+and
+.Fn mbsnrtowcs
+functions may fail with the following errors:
.Bl -tag -width Er
.It Bq Er EILSEQ
-The pointer pointed to by
.Fa s
-points to an invalid or incomplete multibyte character.
+points to a string containing an invalid or incomplete multibyte
+character.
.It Bq Er EINVAL
.Fa ps
points to an invalid or uninitialized mbstate_t object.
@@ -177,5 +214,12 @@ The
.Fn mbsrtowcs
function conforms to
.St -isoC-amd1 .
-The restrict qualifier is added at
+The
+.Li restrict
+qualifier was added by
.St -isoC-99 .
+.Pp
+The
+.Fn mbsnrtowcs
+function conforms to
+.St -p1003.1-2008 .
Index: src/lib/libc/locale/wcsrtombs.3
diff -u src/lib/libc/locale/wcsrtombs.3:1.13 src/lib/libc/locale/wcsrtombs.3:1.13.48.1
--- src/lib/libc/locale/wcsrtombs.3:1.13 Thu Dec 16 17:42:27 2010
+++ src/lib/libc/locale/wcsrtombs.3 Fri Oct 11 17:35:46 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: wcsrtombs.3,v 1.13 2010/12/16 17:42:27 wiz Exp $
+.\" $NetBSD: wcsrtombs.3,v 1.13.48.1 2024/10/11 17:35:46 martin Exp $
.\"
.\" Copyright (c)2002 Citrus Project,
.\" All rights reserved.
@@ -24,12 +24,13 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd August 8, 2006
+.Dd August 27, 2017
.Dt WCSRTOMBS 3
.Os
.\" ----------------------------------------------------------------------
.Sh NAME
-.Nm wcsrtombs
+.Nm wcsrtombs ,
+.Nm wcsnrtombs
.Nd converts a wide-character string to a multibyte character string \
(restartable)
.\" ----------------------------------------------------------------------
@@ -37,16 +38,31 @@
.Lb libc
.\" ----------------------------------------------------------------------
.Sh SYNOPSIS
+.
.In wchar.h
+.
.Ft size_t
-.Fn wcsrtombs "char * restrict s" "const wchar_t ** restrict pwcs" \
-"size_t n" "mbstate_t * restrict ps"
+.Fo wcsrtombs
+.Fa "char * restrict s"
+.Fa "const wchar_t ** restrict pwcs"
+.Fa "size_t n" "mbstate_t * restrict ps"
+.Fc
+.
+.Ft size_t
+.Fo wcsnrtombs
+.Fa "char * restrict s"
+.Fa "const wchar_t ** restrict pwcs"
+.Fa "size_t nwc"
+.Fa "size_t n"
+.Fa "mbstat_t * restrict ps"
+.Fc
+.
.\" ----------------------------------------------------------------------
.Sh DESCRIPTION
The
.Fn wcsrtombs
-converts the nul-terminated wide-character string indirectly pointed
-to by
+function converts the NUL-terminated wide-character string indirectly
+pointed to by
.Fa pwcs
to the corresponding multibyte character string,
and stores it in the array pointed to by
@@ -54,8 +70,8 @@ and stores it in the array pointed to by
The conversion stops due to the following reasons:
.Bl -bullet
.It
-The conversion reaches a nul wide character.
-In this case, the nul wide character is also converted.
+The conversion reaches a NUL wide character.
+In this case, the NUL wide character is also converted.
.It
The
.Fn wcsrtombs
@@ -76,41 +92,42 @@ will not be affected.
After conversion,
if
.Fa s
-is not a null pointer, the pointer object pointed to by
+is not a NULL pointer, the pointer object pointed to by
.Fa pwcs
-is a null pointer (if the conversion is stopped due to reaching a
-nul wide character) or the first byte of the character just after
-the last character converted.
+is a NULL pointer
+.Pq if the conversion is stopped due to reaching a NUL wide character
+or points to the first byte of the character just after the last
+character converted.
.Pp
If
.Fa s
-is not a null pointer and the conversion is stopped due to reaching
-a nul wide character,
+is not a NULL pointer and the conversion is stopped due to reaching
+a NUL wide character,
.Fn wcsrtombs
places the state object pointed to by
.Fa ps
to an initial state after the conversion is taken place.
.Pp
-The behaviour of
+The behavior of
.Fn wcsrtombs
is affected by the
.Dv LC_CTYPE
category of the current locale.
.Pp
These are the special cases:
-.Bl -tag -width 012345678901
-.It "s == NULL"
+.Bl -tag -width Li
+.It Li "s == NULL"
.Fn wcsrtombs
returns the number of bytes to store the whole multibyte character string
corresponding to the wide-character string pointed to by
.Fa pwcs ,
-not including the terminating nul byte.
+not including the terminating NUL byte.
In this case,
.Fa n
is ignored.
-.It "pwcs == NULL || *pwcs == NULL"
+.It Li "pwcs == NULL || *pwcs == NULL"
Undefined (may cause the program to crash).
-.It "ps == NULL"
+.It Li "ps == NULL"
.Fn wcsrtombs
uses its own internal state object to keep the conversion state,
instead of
@@ -124,26 +141,40 @@ state of
.Fn wcsrtombs ,
which is initialized at startup time of the program.
.El
+.Pp
+The
+.Fn wcsnrtombs
+function behaves identically to
+.Fn wcsrtombs ,
+except that the conversion stops after reading at most
+.Fa nwc
+characters from the buffer pointed to by
+.Fa pwcs .
.\" ----------------------------------------------------------------------
.Sh RETURN VALUES
+The
.Fn wcsrtombs
-returns:
-.Bl -tag -width 012345678901
-.It 0 or positive
+and
+.Fn wcsnrtombs
+functions return:
+.Bl -tag -width Li
+.It Li 0 , No or positive
Number of bytes stored in the array pointed to by
.Fa s ,
-except for a nul byte.
+except for a NUL byte.
There are no cases that the value returned is greater than
.Fa n
-(unless
+.Po
+unless
.Fa s
-is a null pointer).
+is a NULL pointer
+.Pc .
If the return value is equal to
.Fa n ,
the string pointed to by
.Fa s
-will not be nul-terminated.
-.It (size_t)-1
+will not be NUL-terminated.
+.It Li "(size_t)-1"
.Fa pwcs
points to a string containing an invalid wide character.
The
@@ -154,12 +185,20 @@ to indicate the error.
.El
.\" ----------------------------------------------------------------------
.Sh ERRORS
+The
.Fn wcsrtombs
-may cause an error in the following case:
+and
+.Fn wcsnrtombs
+functions may fail with the following errors:
.Bl -tag -width Er
.It Bq Er EILSEQ
.Fa pwcs
points to a string containing an invalid wide character.
+.It Bq Er EINVAL
+.Fa ps
+points to an invalid or uninitialized
+.Vt mbstate_t
+object.
.El
.\" ----------------------------------------------------------------------
.Sh SEE ALSO
@@ -172,5 +211,12 @@ The
.Fn wcsrtombs
function conforms to
.St -ansiC .
-The restrict qualifier is added at
+The
+.Li restrict
+qualifier was added by
.St -isoC-99 .
+.Pp
+The
+.Fn wcsnrtombs
+function conforms to
+.St -p1003.1-2008 .
