[PATCH] mbsrtowcs.3: add a note for conversion completion

[Andriy Utkin <andriy_utkin@xxxxxxxxxxxx>]

This adds a note to resolve a confusion I had.
Maintainers are most welcome to improve my wording.

I aimed for this function to work in such a manner so that
it would convert the entire string. So I allocated a destination buffer
to accommodate the string length in wide charaters and the terminating
null. The function was called with len equal to the length of the string
in wide characters, as returned by mbsrtowcs(NULL, ...).

This resulted in *src being updated to point at the trailing null
character, rather than NULL which I expected.

Here is an example which illustrates the point:

Code:

    #include <wchar.h>
    #include <stdio.h>
    int main(void) {
        const char *src = "Hello", *s1 = src, *s2 = src;
        wchar_t dest[6];
        int ret;
        printf("src is %p\n", src);
        ret = mbsrtowcs(NULL, &src, 0, NULL);
        printf("mbsrtowcs(src=NULL) returned %d\n", ret);
        ret = mbsrtowcs(dest, &s1, 5, NULL);
        printf("mbsrtowcs(len=5) returned %d, updated src is %p\n", ret, s1);
        ret = mbsrtowcs(dest, &s2, 6, NULL);
        printf("mbsrtowcs(len=6) returned %d, updated src is %p\n", ret, s2);
        return 0;
    }

Output:

    src is 0x402010
    mbsrtowcs(src=NULL) returned 5
    mbsrtowcs(len=5) returned 5, updated src is 0x402015
    mbsrtowcs(len=6) returned 5, updated src is (nil)
---
 man3/mbsrtowcs.3 | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3
index 11741d187..4718b335d 100644
--- a/man3/mbsrtowcs.3
+++ b/man3/mbsrtowcs.3
@@ -155,6 +155,15 @@ current locale.
 Passing NULL as
 .I ps
 is not multithread safe.
+.P
+Calling this function with
+.I len
+set to the value returned from
+.I mbsrtowcs(NULL, ...)
+behaves according to scenario #2 described above:
+.I *src
+is set to the address of the terminating null wide character, rather than to NULL.
+Add 1 to that value for it to work according to scenario #3 (complete conversion).
 .SH SEE ALSO
 .BR iconv (3),
 .BR mbrtowc (3),
-- 
2.41.0