mbstowcs: Document, test, and fix null pointer dst semantics (Bug 25219)

The function mbstowcs, by an XSI extension to POSIX, accepts a null
pointer for the destination wchar_t array.  This API behaviour allows
you to use the function to compute the length of the required wchar_t
array i.e. does the conversion without storing it and returns the
number of wide characters required.

We remove the __write_only__ markup for the first argument because it
is not true since the destination may be a null pointer, and so the
length argument may not apply.  We remove the markup otherwise the new
test case cannot be compiled with -Werror=nonnull.

We add a new test case for mbstowcs which exercises the destination is
a null pointer behaviour which we have now explicitly documented.

The mbsrtowcs and mbsnrtowcs behave similarly, and mbsrtowcs is
documented as doing this in C11, even if the standard doesn't come out
and call out this specific use case.  We add one note to each of
mbsrtowcs and mbsnrtowcs to call out that they support a null pointer
for the destination.

The wcsrtombs function behaves similarly but in the other way around
and allows you to use a null destination pointer to compute how many
bytes you would need to convert the wide character input.  We document
this particular case also, but leave wcsnrtombs as a references to
wcsrtombs, so the reader must still read the details of the semantics
for wcsrtombs.

1 files changed, 19 insertions, 4 deletions

diff --git a/manual/charset.texi b/manual/charset.texi
index 9fd0166115..b638323fc2 100644
--- a/manual/charset.texi
+++ b/manual/charset.texi
@@ -1026,6 +1026,10 @@ stores in the pointer pointed to by @var{src} either a null pointer (if
 the NUL byte in the input string was reached) or the address of the byte
 following the last converted multibyte character.
 
+Like @code{mbstowcs} the @var{dst} parameter may be a null pointer and
+the function can be used to count the number of wide characters that
+would be required.
+
 @pindex wchar.h
 @code{mbsrtowcs} was introduced in @w{Amendment 1} to @w{ISO C90} and is
 declared in @file{wchar.h}.
@@ -1101,10 +1105,11 @@ successfully converted.
 
 Except in the case of an encoding error the return value of the
 @code{wcsrtombs} function is the number of bytes in all the multibyte
-character sequences stored in @var{dst}.  Before returning, the state in
-the object pointed to by @var{ps} (or the internal object in case
-@var{ps} is a null pointer) is updated to reflect the state after the
-last conversion.  The state is the initial shift state in case the
+character sequences which were or would have been (if @var{dst} was
+not a null) stored in @var{dst}.  Before returning, the state in the
+object pointed to by @var{ps} (or the internal object in case @var{ps}
+is a null pointer) is updated to reflect the state after the last
+conversion.  The state is the initial shift state in case the
 terminating NUL wide character was converted.
 
 @pindex wchar.h
@@ -1131,6 +1136,10 @@ string @code{*@var{src}} need not be NUL-terminated.  But if a NUL byte
 is found within the @var{nmc} first bytes of the string, the conversion
 stops there.
 
+Like @code{mbstowcs} the @var{dst} parameter may be a null pointer and
+the function can be used to count the number of wide characters that
+would be required.
+
 This function is a GNU extension.  It is meant to work around the
 problems mentioned above.  Now it is possible to convert a buffer with
 multibyte character text piece by piece without having to care about
@@ -1465,6 +1474,12 @@ mbstowcs_alloc (const char *string)
 @}
 @end smallexample
 
+If @var{wstring} is a null pointer then no output is written and the
+conversion proceeds as above, and the result is returned.  In practice
+such behaviour is useful for calculating the exact number of wide
+characters required to convert @var{string}.  This behaviour of
+accepting a null pointer for @var{wstring} is an @w{XPG4.2} extension
+that is not specified in @w{ISO C} and is optional in @w{POSIX}.
 @end deftypefun
 
 @deftypefun size_t wcstombs (char *@var{string}, const wchar_t *@var{wstring}, size_t @var{size})