Debian Bug report logs - #317037
manpages-dev: Difficult to understand in sscanf RETURN VALUE

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>

To: submit@bugs.debian.org

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

Message #10 received at 317037@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Justin Pryzby <justinpryzby@users.sourceforge.net>, 317037@bugs.debian.org

Cc: control@bugs.debian.org

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

Message #19 received at 317037@bugs.debian.org (full text, mbox, reply):

From: Justin Pryzby <justinpryzby@users.sf.net>

To: Michael Kerrisk <mtk-manpages@gmx.net>

Cc: 317037@bugs.debian.org

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

Message #24 received at 317037@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Justin Pryzby <justinpryzby@users.sf.net>

Cc: 317037@bugs.debian.org

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 +++

Message #29 received at 317037@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Justin Pryzby <justinpryzby@users.sf.net>

Cc: 317037@bugs.debian.org

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

Message #34 received at 317037-done@bugs.debian.org (full text, mbox, reply):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>

To: 317037-done@bugs.debian.org, 315411-done@bugs.debian.org, 209323-done@bugs.debian.org, 330877-done@bugs.debian.org, 321131-done@bugs.debian.org, 299795-done@bugs.debian.org, 295666-done@bugs.debian.org, 326520-done@bugs.debian.org, 306517-done@bugs.debian.org, 291121-done@bugs.debian.org, 323851-done@bugs.debian.org, 323062-done@bugs.debian.org, 101433-done@bugs.debian.org, 113812-done@bugs.debian.org, 219695-done@bugs.debian.org, 294890-done@bugs.debian.org

Cc: Martin Schulze <joey@debian.org>, Michael Kerrisk <mtk-manpages@gmx.net>

Subject: fixed in recent uploads of manpages

Date: Tue, 22 Nov 2005 11:35:39 -0500

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

Send a report that this bug log contains spam.