Re: standards/52343: wcsnrtombs missing man-page

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

The following reply was made to PR standards/52343; it has been noted by GNATS.

From: Abhinav Upadhyay <er.abhinav.upadhyay%gmail.com@localhost>
To: NetBSD GNATS <gnats-bugs%netbsd.org@localhost>
Cc: standards-manager%netbsd.org@localhost, gnats-admin%netbsd.org@localhost, 
	netbsd-bugs%netbsd.org@localhost, n54%gmx.com@localhost
Subject: Re: standards/52343: wcsnrtombs missing man-page
Date: Sun, 27 Aug 2017 15:36:24 +0530

 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