Debian Bug report logs - #609033
manpages-dev: please improve isgreater(3) description

Toggle useless messages

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

From: Vincent Lefevre <vincent@vinc17.net>

To: Debian Bug Tracking System <submit@bugs.debian.org>

Subject: manpages-dev: please improve isgreater(3) description

Date: Wed, 5 Jan 2011 17:38:06 +0100

Package: manpages-dev
Version: 3.27-1
Severity: wishlist

The isgreater(3) man page says:

  The  normal  relation operations (like <, "less than") will fail if one
  of the operands is NaN.  This will cause an exception.  To avoid  this,
  C99  defines these macros.  The macros are guaranteed to evaluate their
  operands only once.  The operands can be  of  any  real  floating-point
  type.

It should probably be emphasised that the operands must not be of
integer types.

FYI, the current C1x committee draft N1547 has the following footnote
added:

242) If any argument is of integer type, or any other type that is not
     a real floating type, the behavior is undefined.

BTW, "argument" may be a better word than "operand" here, because
"operand" suggests that the usual arithmetic conversions will be done,
but this isn't the case here.

-- System Information:
Debian Release: 6.0
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.32-5-amd64 (SMP w/8 CPU cores)
Locale: LANG=POSIX, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages manpages-dev depends on:
ii  manpages                      3.27-1     Manual pages about using a GNU/Lin

manpages-dev recommends no packages.

Versions of packages manpages-dev suggests:
ii  man-db [man-browser]          2.5.7-8    on-line manual pager

-- no debconf information

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

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

To: Vincent Lefevre <vincent@vinc17.net>, 609033@bugs.debian.org

Cc: Debian Bug Tracking System <submit@bugs.debian.org>

Subject: Re: Bug#609033: manpages-dev: please improve isgreater(3) description

Date: Tue, 24 Apr 2012 22:13:11 +1200

Vincent,

On Thu, Jan 6, 2011 at 5:38 AM, Vincent Lefevre <vincent@vinc17.net> wrote:
> Package: manpages-dev
> Version: 3.27-1
> Severity: wishlist
>
> The isgreater(3) man page says:
>
>  The  normal  relation operations (like <, "less than") will fail if one
>  of the operands is NaN.  This will cause an exception.  To avoid  this,
>  C99  defines these macros.  The macros are guaranteed to evaluate their
>  operands only once.  The operands can be  of  any  real  floating-point
>  type.
>
> It should probably be emphasised that the operands must not be of
> integer types.

The man page already says: "The operands can be of any real
floating-point type." Is that not emphasis enough?

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

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

From: Vincent Lefevre <vincent@vinc17.net>

To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

Cc: 609033@bugs.debian.org

Subject: Re: Bug#609033: manpages-dev: please improve isgreater(3) description

Date: Tue, 24 Apr 2012 15:50:27 +0200

On 2012-04-24 22:13:11 +1200, Michael Kerrisk (man-pages) wrote:
> Vincent,
> 
> On Thu, Jan 6, 2011 at 5:38 AM, Vincent Lefevre <vincent@vinc17.net> wrote:
> > The isgreater(3) man page says:
> >
> >  The  normal  relation operations (like <, "less than") will fail if one
> >  of the operands is NaN.  This will cause an exception.  To avoid  this,
> >  C99  defines these macros.  The macros are guaranteed to evaluate their
> >  operands only once.  The operands can be  of  any  real  floating-point
> >  type.
> >
> > It should probably be emphasised that the operands must not be of
> > integer types.
> 
> The man page already says: "The operands can be of any real
> floating-point type." Is that not emphasis enough?

This is a bit ambiguous, as "can" is not necessarily exclusive.
Macros often have a function-like interface: for instance, if a
real floating-point type is expected and the user provides an
integer, then the integer will automatically be converted to a
real floating-point type. This is not the case here.

Also, the beginning of the paragraph is a bit like saying that
"isgreater" is a safe replacement for ">" to avoid a possible
exception. However, while with ">" the user doesn't need to take
care of the types, this is not the case for "isgreater". For
instance, in order to avoid a possible exception, one should
do the following replacements:

With

  double x
  int i;

replace

  x > i
  x > 0

by

  isgreater (x, (double) i)
  isgreater (x, 0.0)

Users may easily forget to do the change on the second argument.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <http://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <http://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

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

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

To: Vincent Lefevre <vincent@vinc17.net>

Cc: 609033@bugs.debian.org

Subject: Re: Bug#609033: manpages-dev: please improve isgreater(3) description

Date: Sat, 5 May 2012 23:53:08 +1200

On Wed, Apr 25, 2012 at 1:50 AM, Vincent Lefevre <vincent@vinc17.net> wrote:
> On 2012-04-24 22:13:11 +1200, Michael Kerrisk (man-pages) wrote:
>> Vincent,
>>
>> On Thu, Jan 6, 2011 at 5:38 AM, Vincent Lefevre <vincent@vinc17.net> wrote:
>> > The isgreater(3) man page says:
>> >
>> >  The  normal  relation operations (like <, "less than") will fail if one
>> >  of the operands is NaN.  This will cause an exception.  To avoid  this,
>> >  C99  defines these macros.  The macros are guaranteed to evaluate their
>> >  operands only once.  The operands can be  of  any  real  floating-point
>> >  type.
>> >
>> > It should probably be emphasised that the operands must not be of
>> > integer types.
>>
>> The man page already says: "The operands can be of any real
>> floating-point type." Is that not emphasis enough?
>
> This is a bit ambiguous, as "can" is not necessarily exclusive.
> Macros often have a function-like interface: for instance, if a
> real floating-point type is expected and the user provides an
> integer, then the integer will automatically be converted to a
> real floating-point type. This is not the case here.
>
> Also, the beginning of the paragraph is a bit like saying that
> "isgreater" is a safe replacement for ">" to avoid a possible
> exception. However, while with ">" the user doesn't need to take
> care of the types, this is not the case for "isgreater". For
> instance, in order to avoid a possible exception, one should
> do the following replacements:
>
> With
>
>  double x
>  int i;
>
> replace
>
>  x > i
>  x > 0
>
> by
>
>  isgreater (x, (double) i)
>  isgreater (x, 0.0)
>
> Users may easily forget to do the change on the second argument.

So, how about the following replacement text:

[[
The macros are guaranteed to evaluate their arguments only once.  The
arguments must be of real  floating-point type (note: do not pass
integer values as arguments to these macros, since the arguments will
*not* be promoted to real-floating types).
]]

?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

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

From: Vincent Lefevre <vincent@vinc17.net>

To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

Cc: 609033@bugs.debian.org

Subject: Re: Bug#609033: manpages-dev: please improve isgreater(3) description

Date: Sun, 6 May 2012 00:34:34 +0200

On 2012-05-05 23:53:08 +1200, Michael Kerrisk (man-pages) wrote:
> So, how about the following replacement text:
> 
> [[
> The macros are guaranteed to evaluate their arguments only once.  The
> arguments must be of real  floating-point type (note: do not pass
> integer values as arguments to these macros, since the arguments will
> *not* be promoted to real-floating types).
> ]]
> 
> ?

Perfect!

Thanks,

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <http://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <http://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

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

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

To: Vincent Lefevre <vincent@vinc17.net>

Cc: 609033@bugs.debian.org, control@bugs.debian.org

Subject: Re: Bug#609033: manpages-dev: please improve isgreater(3) description

Date: Sun, 6 May 2012 11:15:56 +1200

tags 609033 fixed-upstream
thanks

Vincent, I've made this change for upstream 3.41.

Thanks,

Michael

On Sun, May 6, 2012 at 10:34 AM, Vincent Lefevre <vincent@vinc17.net> wrote:
> On 2012-05-05 23:53:08 +1200, Michael Kerrisk (man-pages) wrote:
>> So, how about the following replacement text:
>>
>> [[
>> The macros are guaranteed to evaluate their arguments only once.  The
>> arguments must be of real  floating-point type (note: do not pass
>> integer values as arguments to these macros, since the arguments will
>> *not* be promoted to real-floating types).
>> ]]
>>
>> ?
>
> Perfect!
>
> Thanks,
>
> --
> Vincent Lefèvre <vincent@vinc17.net> - Web: <http://www.vinc17.net/>
> 100% accessible validated (X)HTML - Blog: <http://www.vinc17.net/blog/>
> Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Message #44 received at 609033-close@bugs.debian.org (full text, mbox, reply):

From: Simon Paillard <spaillard@debian.org>

To: 609033-close@bugs.debian.org

Subject: Bug#609033: fixed in manpages 3.42-1

Date: Sat, 25 Aug 2012 16:17:41 +0000

Source: manpages
Source-Version: 3.42-1

We believe that the bug you reported is fixed in the latest version of
manpages, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 609033@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Simon Paillard <spaillard@debian.org> (supplier of updated manpages package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Format: 1.8
Date: Thu, 23 Aug 2012 21:50:38 +0200
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 3.42-1
Distribution: unstable
Urgency: low
Maintainer: Martin Schulze <joey@debian.org>
Changed-By: Simon Paillard <spaillard@debian.org>
Description: 
 manpages   - Manual pages about using a GNU/Linux system
 manpages-dev - Manual pages about using GNU/Linux for development
Closes: 383296 526778 538641 609033 660479 671514 671515 673436 673873 673875 674051 679498
Changes: 
 manpages (3.42-1) unstable; urgency=low
 .
   [ Simon Paillard ]
   * Add myself to Uploaders
   * Imported Upstream version 3.42:
     . new manpages: get_robust_list.2 mallinfo.3 malloc_info.3 malloc_stats.3
     . remove outdated links: path_resolution.2 epoll.4 fifo.4 futex.4
       complex.5 environ.5
     . Fix repeated word in memchr.3 (Closes: #679498)
     . isgreater.3: arguments must be real-floating (Closes: #609033)
     . utf-8.7: clarifications (Closes: #538641)
     . getaddrinfo.3: note that AI_ADDRCONFIG is not affected by loopback
       addresses (Closes: #660479)
     . Fix "rtnetlink(7): Line in table too long" (Closes: #674051)
     . Fix "netlink(7): Line in table is too long" (Closes: #673875)
     . Fix "netdevice(7): Line in table too long" (Closes: #673873)
     . Fix "suffixes(7): Warnings from "grotty"" (Closes: #673436)
     . Fix "ioctl_list(2): table wider than line width" (Closes: #671515)
     . Fix groff warnings console_codes(4) (Closes: #671514)
     . netlink.7: *_pid fields are not process but port id (Closes: #383296)
   * Drop obsolete formatting patch: gettimeofday.2 wprintf.3 setnetgrent.3
   * Drop patch getgid.2, getuid.2: now documented by upstream credentials(7)
   * Drop inconsistent coding style patch: bsearch.3 qsort.3
   * iconv.3: remove Debian patch, accepted upstream and moved to NOTES
   * Remove old links added 10y ago due to debian specific man-db
   * fclose.3: drop debian patches, mark the remaining as rejected upstream
   * Remove mallinfo.3 from missing.7, added in upstream 3.41
   * Drop outdated debian/readme
   * getifaddrs.3, rtnetlink.7: stats interface is struct rtnl_link_stats, not
     net_device_stats (Closes: #526778) - thanks to Julien Cristau
Checksums-Sha1: 
 adc626704fe11d2d1ee87264e6ffd82b01424448 1904 manpages_3.42-1.dsc
 ca33acaa9708ea04d659ada3e49a2b808ade03dc 1748638 manpages_3.42.orig.tar.gz
 78f668751bc17c5ec2d6eb9f9f4e0c45581bcc1c 46466 manpages_3.42-1.diff.gz
 35199833a71faeb1d1d02210309ac61c8ec52adc 784438 manpages_3.42-1_all.deb
 29def2ec668e3b6d4f746e56793501e3171c3c99 1728792 manpages-dev_3.42-1_all.deb
Checksums-Sha256: 
 ba83353d9cabacd1978261d4763b7665f428b4f02f1bb16e27e6994126831b5f 1904 manpages_3.42-1.dsc
 e366548e907776780d8558d9ab2918d49c28b7f9f926a4bdbe8559cc27165a1d 1748638 manpages_3.42.orig.tar.gz
 d5d96fc20ef2192af599b57a174e510b9868a0ff718662034dfceb4907835e68 46466 manpages_3.42-1.diff.gz
 dbd074db50d0086168e0c1df6a0d2bbf0ff396bdf6ebc20d41ee814f4ab1c3e3 784438 manpages_3.42-1_all.deb
 b0b0bef7ac02ef1bb314856db094c85a33a53f40e3601c1080ec21738d865443 1728792 manpages-dev_3.42-1_all.deb
Files: 
 87240352356f2dc73d8834a9c16365e6 1904 doc important manpages_3.42-1.dsc
 cc8f73ecd8a123ceb7a8670daa91ee6c 1748638 doc important manpages_3.42.orig.tar.gz
 94b82badf5d39c826aa728c7e57f3d9f 46466 doc important manpages_3.42-1.diff.gz
 c96c0a4dfcfef21a1dbae4f982fe0816 784438 doc important manpages_3.42-1_all.deb
 b1ff58b81d31410b5593ee97d4617f67 1728792 doc optional manpages-dev_3.42-1_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iQIcBAEBCAAGBQJQOPbyAAoJEN/3OMLRbPuie3gP/RGCk7GsGOIW2jQagjv48WfY
nCb5winm4kaYS4SLf501J9BiIpghDMOntXwL4X7Er8NtV7adbcwr4VawW+BSTDnh
aEiQM9AFkpK2FIKBP2YWwVhqsl4VIEg/fezziRt4dK5b8MPNJLPk74mQ+1MJUG0L
Zb+oMtnwqBFKjb2xU1glNaQ01YUYsLnhZY8n1D+rDVfRRqfFzIiDvVJYdSKU1iwT
T61AYkNfjjIYG91jxjUi7Xi2cQudKqvOMUL0Cz/349A+9b8tMmLPvhjf8coRBOVS
3x7J3skD+npiT5DT9MUswKhwmy8Ml5JSr8JgdJu/zQRcnvWGP3FS6dDHkMRXGgtK
+kHp7yMfiMsmMqQqIjjYzhPRW/xQZslBjNlsCMSbI4VuMArn+hezqb4rfzfHe8yv
kOmeaH8svVEJ2eRbV+YbBglXXsQOeBKLAFWqrdLvVXXmCTuPFprPxsP/OGvQ+i2m
KWRsKzReMQ7nV31xCga9NxENou6v1EnF+sEVi1eBWYWH7lJWwcoYnAnHYHc6UsyA
2hcTw4nwxZCkMTXG/PewYd4OISJ3ChlkCC3yZ7U1dpFQisvgnhjNiROxBfKf2T4x
f1dfpNIfWf0i/ynn9I5QRSbN+ZNhyx0Txc4jiftJt/Dv7kqtU7hYuRje56pdoiC9
EV+YSyJky+x4+NLXJfhB
=ljey
-----END PGP SIGNATURE-----

Send a report that this bug log contains spam.