Stefan Sperling writes: > On Tue, Oct 27, 2015 at 04:21:28PM +0100, Vadim Zhukov wrote: > > 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. > > Thanks. New diff including off-list feedback from jmc. > > This is looking much better now, I think. > > (@bentley, I would be grateful if you could give this another > look to see if it clarifies your questions)
Yes, this is much better. One tweak below: > 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 16:00:28 -0000 > @@ -40,27 +40,15 @@ > .Sh DESCRIPTION > The > .Fn mbtowc > -usually converts the multibyte character pointed to by > +function 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,52 +56,74 @@ 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. Maybe this should be "...before it can safely be used again." Either way, ok bentley@
