Bug#839705: manpages-dev: "initial state" in mbstowcs(3) and wcstombs(3)
On 10/06/2016 10:13 AM, Igor Liferenko wrote:
> Dear Maintainer,
>
> According to definitions of mbstowcs and wcstombs (see below), the phrase
> ``The conversion starts in the initial state.''
See my earlier reply.
> may be left in mbstowcs(3) and wcstombs(3), but the phrase
> ``In this case, the conversion ends in the initial state.''
> should be removed from wcstombs(3) (because there is no such sentence
> in corresponding section of mbstowcs(3) and because this sentence
> makes no sense):
>
> http://code.metager.de/source/xref/gnu/glibc/stdlib/mbstowcs.c
>
> http://code.metager.de/source/xref/gnu/glibc/stdlib/wcstombs.c
I'm not sure that the sentence makes no sense. I did change "initial state"
to "initial shift state". Still not sure if that's correct though.
> BTW, in mbstowcs(3) the phrase
>
> including the terminating null wide character ('\0')
>
> should be changed to
>
> including the terminating null byte ('\0')
I fixed this. Thanks.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Bug#839705: manpages-dev: "initial state" in mbstowcs(3) and wcstombs(3)
tags 839705 fixed-upstream thanks On 10/04/2016 09:30 AM, Igor Liferenko wrote: > Package: manpages-dev > Version: 4.07-1 > Severity: normal > > Dear Maintainer, > > In mbstowcs(3) there is this sentence: > > The conversion starts in the initial state. > > And in wcstombs(3) there are these sentences: > > The conversion starts in the initial state. > > In this case, the conversion ends in the initial state. > > "Initial state" is associated only with mbstate_t, but mbstowcs and wcstombs > are stateless (in contrast with mbsrtowcs and wcsrtombs). Looking at your later reply, you seem to understand that "Initial state" here is sort of okay. But really, the language could be clearer. I applied the patch below. (Still not sure if it's 100% correct, but I believe it's an improvement.) Cheers, Michael diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3 index e02f7df..bdd624a 100644 --- a/man3/mbstowcs.3 +++ b/man3/mbstowcs.3 @@ -39,8 +39,9 @@ At most .I n wide characters are written to .IR dest . -The conversion starts -in the initial state. +The sequence of characters in the string +.I src +shall begin in the initial shift state. The conversion can stop for three reasons: .IP 1. 3 An invalid multibyte sequence has been encountered. diff --git a/man3/wcstombs.3 b/man3/wcstombs.3 index e5498b3..073cc9b 100644 --- a/man3/wcstombs.3 +++ b/man3/wcstombs.3 @@ -36,8 +36,9 @@ At most .I n bytes are written to .IR dest . -The conversion -starts in the initial state. +The sequence of characters placed in +.IR dest +begins in the initial shift state. The conversion can stop for three reasons: .IP 1. 3 A wide character has been encountered that can not be represented as a @@ -53,7 +54,7 @@ is returned, but the shift state at this point is lost. .IP 3. The wide-character string has been completely converted, including the terminating null wide character (L\(aq\\0\(aq). -In this case, the conversion ends in the initial state. +In this case, the conversion ends in the initial shift state. The number of bytes written to .IR dest , excluding the terminating null byte (\(aq\\0\(aq), is returned. -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Bug#839705: manpages-dev: "initial state" in mbstowcs(3) and wcstombs(3)
Dear Maintainer,
According to definitions of mbstowcs and wcstombs (see below), the phrase
``The conversion starts in the initial state.''
may be left in mbstowcs(3) and wcstombs(3), but the phrase
``In this case, the conversion ends in the initial state.''
should be removed from wcstombs(3) (because there is no such sentence
in corresponding section of mbstowcs(3) and because this sentence
makes no sense):
http://code.metager.de/source/xref/gnu/glibc/stdlib/mbstowcs.c
http://code.metager.de/source/xref/gnu/glibc/stdlib/wcstombs.c
BTW, in mbstowcs(3) the phrase
including the terminating null wide character ('\0')
should be changed to
including the terminating null byte ('\0')
Regards,
Igor
Bug#839705: manpages-dev: "initial state" in mbstowcs(3) and wcstombs(3)
Package: manpages-dev Version: 4.07-1 Severity: normal Dear Maintainer, In mbstowcs(3) there is this sentence: The conversion starts in the initial state. And in wcstombs(3) there are these sentences: The conversion starts in the initial state. In this case, the conversion ends in the initial state. "Initial state" is associated only with mbstate_t, but mbstowcs and wcstombs are stateless (in contrast with mbsrtowcs and wcsrtombs). -- System Information: Debian Release: stretch/sid APT prefers testing APT policy: (500, 'testing') Architecture: amd64 (x86_64) Kernel: Linux 4.7.0-1-amd64 (SMP w/4 CPU cores) Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash Init: systemd (via /run/systemd/system) Versions of packages manpages-dev depends on: ii manpages 4.07-1 manpages-dev recommends no packages. Versions of packages manpages-dev suggests: ii man-db [man-browser] 2.7.5-1 -- no debconf information
