2015-10-27 13:40 GMT+01:00 Stefan Sperling <s...@stsp.name>: > 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 .
Since we're already talking about "s==NULL" case, stating it again is extraneous. IMHO, better would be: .Fa pwc -is completely ignored. +is ignored. > .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. IMHO, this should clarify if this would modify internal state. Other than that, looks okay to me. -- WBR, Vadim Zhukov
