From a7379e0996ef14c7153f70e8576cd7f002cb2a31 Mon Sep 17 00:00:00 2001
From: gbe <gbe@FreeBSD.org>
Date: Fri, 7 Aug 2020 16:56:43 +0000
Subject: [PATCH] mbsrtowcs(3): Clarify the RETURN VALUES section

PR:		215848
Submitted by:	Andrew Stevenson <andrew at ugh dot net dot au>
MFC after:	1 week
---
 lib/libc/locale/mbsrtowcs.3 | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/lib/libc/locale/mbsrtowcs.3 b/lib/libc/locale/mbsrtowcs.3
index eaf9f909305..fb2076f98cd 100644
--- a/lib/libc/locale/mbsrtowcs.3
+++ b/lib/libc/locale/mbsrtowcs.3
@@ -23,7 +23,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\" $FreeBSD$
-.Dd July 21, 2004
+.Dd August 7, 2020
 .Dt MBSRTOWCS 3
 .Os
 .Sh NAME
@@ -98,15 +98,29 @@ except that conversion stops after reading at most
 bytes from the buffer pointed to by
 .Fa src .
 .Sh RETURN VALUES
-The
+If successful, and
+.Fa dst
+is not NULL, the
 .Fn mbsrtowcs
 and
 .Fn mbsnrtowcs
 functions return the number of wide characters stored in
 the array pointed to by
+.Fa dst .
+.Pp
+If
 .Fa dst
-if successful, otherwise it returns
-.Po Vt size_t Pc Ns \-1 .
+was NULL then the functions
+.Fn mbsrtowcs
+and
+.Fn mbsnrtowcs
+return the number of wide characters that would have been stored where
+.Fa dst
+points to an infinitely large array.
+.Pp
+If either one of the functions is not successful then
+.Po Vt size_t Pc Ns \-1
+is returned.
 .Sh ERRORS
 The
 .Fn mbsrtowcs
-- 
2.45.0