Index: mbtowc.3
===================================================================
RCS file: /cvs/src/lib/libc/locale/mbtowc.3,v
retrieving revision 1.4
diff -u -p -r1.4 mbtowc.3
--- mbtowc.3 5 Jun 2013 03:39:22 -0000 1.4
+++ mbtowc.3 27 Oct 2015 12:20:49 -0000
@@ -40,27 +40,15 @@
.Sh DESCRIPTION
The
.Fn mbtowc
-usually converts the multibyte character pointed to by
+converts the multibyte character pointed to by
.Fa s
to a wide character, and stores it in the wchar_t object pointed to by
-.Fa pwc
-if
-.Fa pwc
-is non-null and
-.Fa s
-points to a valid character.
-This function may inspect at most n bytes of the array beginning from
+.Fa pwc .
+This function may inspect at most
+.Fa n
+bytes of the array pointed to by
.Fa s .
.Pp
-In state-dependent encodings,
-.Fa s
-may point to the special sequence bytes to change the shift-state.
-Although such sequence bytes correspond to no individual
-wide-character code,
-.Fn mbtowc
-changes its own state by the sequence bytes and treats them
-as if they are a part of the subsequence multibyte character.
-.Pp
Unlike
.Xr mbrtowc 3 ,
the first
@@ -68,8 +56,24 @@ the first
bytes pointed to by
.Fa s
need to form an entire multibyte character.
-Otherwise, this function causes an error.
+Otherwise, this function returns an error and the internal state will
+be undefined.
+.Pp
+If a call to
+.Fn mbtowc
+resulted in an undefined internal state,
+.Fn mbtowc
+must be called with
+.Ar s
+set to
+.Dv NULL
+to reset the internal state before being used again for other purposes.
.Pp
+The behaviour of
+.Fn mbtowc
+is affected by the
+.Dv LC_CTYPE
+category of the current locale.
Calling any other functions in
.Em libc
never change the internal
@@ -79,41 +83,46 @@ except for calling
.Xr setlocale 3
with the
.Dv LC_CTYPE
-category changed to that of the current locale.
+category set to a different locale.
Such
.Xr setlocale 3
-calls cause the internal state of this function to be indeterminate.
+calls cause the internal state of this function to be undefined.
.Pp
-The behaviour of
+In state-dependent encodings such as Shift-JIS,
+.Fa s
+may point to the special sequence of bytes to change the shift-state.
+Because such sequence bytes correspond to no individual wide-character,
.Fn mbtowc
-is affected by the
-.Dv LC_CTYPE
-category of the current locale.
+treats them as if they were part of the subsequent multibyte character.
.Pp
-These are the special cases:
+The following special cases apply to the arguments:
.Bl -tag -width 012345678901
.It s == NULL
.Fn mbtowc
initializes its own internal state to an initial state, and
determines whether the current encoding is state-dependent.
-This function returns 0 if the encoding is state-independent,
+.Fn mbtowc
+returns 0 if the encoding is state-independent,
otherwise non-zero.
-In this case,
.Fa pwc
-is completely ignored.
+is ignored if
+.Fa s
+is
+.Dv NULL .
.It pwc == NULL
.Fn mbtowc
executes the conversion as if
.Fa pwc
-is non-null, but a result of the conversion is discarded.
+was not
+.Dv NULL ,
+but the result of the conversion is discarded.
.It n == 0
In this case,
the first
.Fa n
bytes of the array pointed to by
.Fa s
-never form a complete character.
-Thus, the
+never form a complete character and
.Fn mbtowc
always fails.
.El
@@ -137,14 +146,14 @@ macro.
.It -1
.Fa s
points to an invalid or an incomplete multibyte character.
-The
-.Fn mbtowc
-also sets errno to indicate the error.
+.Va errno
+is set to indicate the error.
.El
.Pp
When
.Fa s
-is equal to NULL,
+is
+.Dv NULL ,
.Fn mbtowc
returns:
.Bl -tag -width 0123456789
@@ -156,7 +165,9 @@ The current encoding is state-dependent.
.\" ----------------------------------------------------------------------
.Sh ERRORS
.Fn mbtowc
-may cause an error in the following cases:
+will set
+.Va errno
+in the following cases:
.Bl -tag -width Er
.It Bq Er EILSEQ
.Fa s
