Re: standards/52343: wcsnrtombs missing man-page

[Abhinav Upadhyay <er.abhinav.upadhyay%gmail.com@localhost>]

On Tue, Jun 27, 2017 at 6:25 PM, Christos Zoulas <christos%zoulas.com@localhost> wrote:
> The following reply was made to PR standards/52343; it has been noted by GNATS.
>
> From: christos%zoulas.com@localhost (Christos Zoulas)
> To: gnats-bugs%NetBSD.org@localhost, standards-manager%netbsd.org@localhost,
>         gnats-admin%netbsd.org@localhost, netbsd-bugs%netbsd.org@localhost, n54%gmx.com@localhost
> Cc:
> Subject: Re: standards/52343: wcsnrtombs missing man-page
> Date: Tue, 27 Jun 2017 08:53:02 -0400
>
>  On Jun 27, 11:05am, er.abhinav.upadhyay%gmail.com@localhost (Abhinav Upadhyay) wrote:
>  -- Subject: Re: standards/52343: wcsnrtombs missing man-page
>
>  |  OpenBSD and FreeBSD have a man page for this. Can we take it from
>  |  either of them?
>
>  Yes, we usually take libc stuff from FreeBSD.
>

Does this look fine? Mostly based on the FreeBSD man page. (I will add
set entries for wcsnrtombs.3)

FreeBSD man page also says that these functions may have EINVAL as a
possible error but I am not sure if our implementation does that or
not, so left that part as it is.

Index: wcsrtombs.3
===================================================================
RCS file: /cvsroot/src/lib/libc/locale/wcsrtombs.3,v
retrieving revision 1.13
diff -u -r1.13 wcsrtombs.3
--- wcsrtombs.3 16 Dec 2010 17:42:27 -0000      1.13
+++ wcsrtombs.3 27 Aug 2017 10:00:58 -0000
@@ -24,12 +24,12 @@
 .\" 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, wcsnrtombs
 .Nd converts a wide-character string to a multibyte character string \
 (restartable)
 .\" ----------------------------------------------------------------------
@@ -41,11 +41,14 @@
 .Ft size_t
 .Fn wcsrtombs "char * restrict s" "const wchar_t ** restrict pwcs" \
 "size_t n" "mbstate_t * restrict ps"
+.Ft size_t
+.Fn wcsnrtombs "char * restrict s" "const wchar_t ** restrict pwcs" \
+"size_t in" "size_t n" "mbstat_t * restrict ps"
 .\" ----------------------------------------------------------------------
 .Sh DESCRIPTION
 The
 .Fn wcsrtombs
-converts the nul-terminated wide-character string indirectly pointed
+function converts the nul-terminated wide-character string indirectly pointed
 to by
 .Fa pwcs
 to the corresponding multibyte character string,
@@ -124,10 +127,22 @@
 .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 in
+characters from the buffer pointed to by
+.Fa pwcs .
 .\" ----------------------------------------------------------------------
 .Sh RETURN VALUES
+The
 .Fn wcsrtombs
-returns:
+and
+.Fn wcsnrtombs
+functions return:
 .Bl -tag -width 012345678901
 .It 0 or positive
 Number of bytes stored in the array pointed to by
@@ -154,8 +169,11 @@
 .El
 .\" ----------------------------------------------------------------------
 .Sh ERRORS
+The
 .Fn wcsrtombs
-may cause an error in the following case:
+and
+.Fn wcsnrtombs
+functions may cause an error in the following case:
 .Bl -tag -width Er
 .It Bq Er EILSEQ
 .Fa pwcs
@@ -174,3 +192,7 @@
 .St -ansiC .
 The restrict qualifier is added at
 .St -isoC-99 .
+.Pp
+The
+.Fn wcsnrtombs
+is an extension to the standard.
Index: Makefile.inc
===================================================================
RCS file: /cvsroot/src/lib/libc/locale/Makefile.inc,v
retrieving revision 1.64
diff -u -r1.64 Makefile.inc
--- Makefile.inc        18 Aug 2013 20:03:48 -0000      1.64
+++ Makefile.inc        27 Aug 2017 10:00:58 -0000
@@ -52,4 +52,6 @@
 MLINKS+=wcstol.3 wcstoll.3 wcstol.3 wcstoimax.3 \
        wcstol.3 wcstoul.3 wcstol.3 wcstoull.3 wcstol.3 wcstoumax.3

+MLINKS+=wcsrtombs.3 wcsnrtombs.3
+
 COPTS.wcsftime.c = -Wno-format-nonliteral