Subject: manpages-dev: Difficult to understand in sscanf RETURN VALUE
Date: Tue, 5 Jul 2005 14:43:45 -0400
Package: manpages-dev
Severity: normal
I quote from the RETURN VALUE section of sscanf(3):
The value EOF is returned if an input failure occurs before any
conversion such as an end-of-file occurs.
This seems to imply that "end-of-file" is a "conversion", which I
think must be unintentional. I suggest the following replacement
text (which is probably what is intended):
The value EOF is returned if an input failure (such as end-of-file)
occurs before any conversion is assigned.
Justin
Subject: Re: Bug#317037: manpages-dev: Difficult to understand in sscanf RETURN VALUE
Date: Wed, 6 Jul 2005 07:56:17 +0200 (MEST)
tags 317037 fixed-upstream
tags 317037 pending
thanks
> I quote from the RETURN VALUE section of sscanf(3):
>
> The value EOF is returned if an input failure occurs before any
> conversion such as an end-of-file occurs.
>
> This seems to imply that "end-of-file" is a "conversion", which I
> think must be unintentional. I suggest the following replacement
> text (which is probably what is intended):
>
> The value EOF is returned if an input failure (such as end-of-file)
> occurs before any conversion is assigned.
Justin,
Thanks.
I agree. The text is confusing. I opted for a more extensive
description:
The value EOF is returned if the end of input
is reached before the first successful conver-
sion or matching failure. EOF is also
returned if a read error occurs, in which case
the error indicator for the stream (see fer-
ror(3)) is set, and errno is set indicate the
error.
Change will be in man-pages-2.06.
Cheers,
Michael
--
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7
Want to help with man page maintenance? Grab the latest
tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/
and grep the source files for 'FIXME'.
Weitersagen: GMX DSL-Flatrates mit Tempo-Garantie!
Ab 4,99 Euro/Monat: http://www.gmx.net/de/go/dsl
Subject: Re: Bug#317037: manpages-dev: Difficult to understand in sscanf RETURN VALUE
Date: Wed, 6 Jul 2005 11:47:28 -0400
On Wed, Jul 06, 2005 at 07:56:17AM +0200, Michael Kerrisk wrote:
> tags 317037 fixed-upstream
> tags 317037 pending
> thanks
>
> > I quote from the RETURN VALUE section of sscanf(3):
> >
> > The value EOF is returned if an input failure occurs before any
> > conversion such as an end-of-file occurs.
> >
> > This seems to imply that "end-of-file" is a "conversion", which I
> > think must be unintentional. I suggest the following replacement
> > text (which is probably what is intended):
> >
> > The value EOF is returned if an input failure (such as end-of-file)
> > occurs before any conversion is assigned.
>
> Justin,
>
> Thanks.
>
> I agree. The text is confusing. I opted for a more extensive
> description:
>
> The value EOF is returned if the end of input
> is reached before the first successful conver-
> sion or matching failure. EOF is also
> returned if a read error occurs, in which case
> the error indicator for the stream (see fer-
> ror(3)) is set, and errno is set indicate the
> error.
What is a matching failure, anyway?
Justin
Subject: Re: Bug#317037: manpages-dev: Difficult to understand in sscanf RETURN VALUE
Date: Wed, 6 Jul 2005 18:00:30 +0200 (MEST)
> > tags 317037 fixed-upstream
> > tags 317037 pending
> > thanks
> >
> > > I quote from the RETURN VALUE section of sscanf(3):
> > >
> > > The value EOF is returned if an input failure occurs before any
> > > conversion such as an end-of-file occurs.
> > >
> > > This seems to imply that "end-of-file" is a "conversion", which I
> > > think must be unintentional. I suggest the following replacement
> > > text (which is probably what is intended):
> > >
> > > The value EOF is returned if an input failure (such as end-of-file)
> > > occurs before any conversion is assigned.
> >
> > Justin,
> >
> > Thanks.
> >
> > I agree. The text is confusing. I opted for a more extensive
> > description:
> >
> > The value EOF is returned if the end of input
> > is reached before the first successful conver-
> > sion or matching failure. EOF is also
> > returned if a read error occurs, in which case
> > the error indicator for the stream (see fer-
> > ror(3)) is set, and errno is set indicate the
> > error.
> What is a matching failure, anyway?
Is it not clear when you read the entire page?
Cheers,
Michael
--
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7
Want to help with man page maintenance? Grab the latest
tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/
and grep the source files for 'FIXME'.
5 GB Mailbox, 50 FreeSMS http://www.gmx.net/de/go/promail
+++ GMX - die erste Adresse für Mail, Message, More +++
Subject: Re: Bug#317037: manpages-dev: Difficult to understand in sscanf RETURN VALUE
Date: Thu, 14 Jul 2005 15:47:39 +0200 (MEST)
Hello Justin.
[I restored the 'bugs' address on this mail, which I think
you must have trimed in your reply?]
> On Wed, Jul 06, 2005 at 06:00:30PM +0200, Michael Kerrisk wrote:
> > > > tags 317037 fixed-upstream
> > > > tags 317037 pending
> > > > thanks
> > > >
> > > > > I quote from the RETURN VALUE section of sscanf(3):
> > > > >
> > > > > The value EOF is returned if an input failure occurs before any
> > > > > conversion such as an end-of-file occurs.
> > > > >
> > > > > This seems to imply that "end-of-file" is a "conversion", which I
> > > > > think must be unintentional. I suggest the following replacement
> > > > > text (which is probably what is intended):
> > > > >
> > > > > The value EOF is returned if an input failure (such as
> > > > > end-of-file)
> > > > > occurs before any conversion is assigned.
> > > >
> > > > Justin,
> > > >
> > > > Thanks.
> > > >
> > > > I agree. The text is confusing. I opted for a more extensive
> > > > description:
> > > >
> > > > The value EOF is returned if the end of input
> > > > is reached before the first successful conver-
> > > > sion or matching failure. EOF is also
> > > > returned if a read error occurs, in which case
> > > > the error indicator for the stream (see fer-
> > > > ror(3)) is set, and errno is set indicate the
> > > > error.
> > > What is a matching failure, anyway?
> >
> > Is it not clear when you read the entire page?
> The phrase "matching failure" is used precisely once. And, in the
> text above, it is still confusing:
>
> The value EOF is returned if the end of input
> is reached before the first successful conver-
> sion or matching failure. EOF is also
> ^^
> occurs?
Not strictly necessary, but I added it anyway.
> If a matching failure occurs, isn't 0 returned?
>
> These functions return the number of input items assigned,
> which can be fewer than provided for, or even zero, in the
> event of a matching fail- ure. Zero indicates that, while
> there was input available, no conver- sions were assigned;
> typically this is due to an invalid input charac- ter, such as
> an alphabetic character for a `%d' conversion.
I have changed the text of this man page fairly substantially.
Hopefully it addresses your convcerns, at least partly.
Take a look at man-pages-2.06 when it comes out (soon).
Cheers,
Michael
--
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7
Want to help with man page maintenance? Grab the latest
tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/
and grep the source files for 'FIXME'.
GMX DSL = Maximale Leistung zum minimalen Preis!
2000 MB nur 2,99, Flatrate ab 4,99 Euro/Monat: http://www.gmx.net/de/go/dsl
Version: 2.09-1
These bugs are all reported fixed by the upstream manpages maintainer,
Michael Kerrisk. For my own convenience, I'm marking them all as
"fixed by version 2.09-1", even though some of them are fixed by
earlier uploads. The bug number, correct fixed-in version, and title
are listed below:
#317037 2.06 Difficult to understand in sscanf RETURN VALUE
#315411 2.09 New upstream release: 2.09
#209323 2.09 please include pty(4) manpage
#330877 2.09 read can return EINVAL when using O_DIRECT and buffer not aligned
#321131 2.08 exit.3 missing "is"
#299795 2.07 Some library functions' manpage use wrong hyphen
#295666 2.03 regex.7.gz: The word boundary regexps are unsupported
#326520 2.08 'man msgget' typo: one line not displayed
#306517 2.04 epoll_ctl(2) description differs from implementation
#291121 2.04 flock(2) second time by same process
#323851 2.08 getpwnam.3 manpage should clarify the scope of pw_dir
#323062 2.08 clone(2) CLONE_PARENT_SETTID description incorrect
#101433 2.04 "man setitimer" give bad informations
#113812 2.04 libc6-dev: iconv prototype
#317037 2.06 Difficult to understand in sscanf RETURN VALUE
#219695 2.04 sysconf(3): describes _SC_2_DEV, which doesn't exist
#294890 2.03 Typo in wait(2): "watpid"
--
Clear skies,
Justin