[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#354315: marked as done (libx11-dev: XGetWindowAttributes man page is misleading)

Your message dated Sun, 26 Nov 2006 11:47:40 +0000
with message-id <E1GoIU0-000229-7J@ries.debian.org>
and subject line Bug#354315: fixed in libx11 2:1.1-2
has caused the attached Bug report to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what I am
talking about this indicates a serious mail system misconfiguration
somewhere.  Please contact me immediately.)

Debian bug tracking system administrator
(administrator, Debian Bugs database)
--- Begin Message --- 
Package: libx11-dev
Version: 4.3.0.dfsg.1-14sarge1
Severity: normal
Tags: patch

This man page does not discuss the actual return values of the
function, but says they are of type "Status".  One might assume
that this means you could compare it with the "Success" macro.
One would be wrong.

The X functions seem to have two three types representing status.
If it is an "int" there are a number of error codes or "Success"
which can be compared against.  If it is a bool, the result can be
compared with "True" or "False".  If the return type is "Status" it
appears that the return type is either 0 or 1.  Unfortunately the
value for Success is zero, so it is important to distinguish
between the first two types of return values and the third;
otherwise the conditional will be inverted.

XGetWindowAttributes() is one of the functions which returns zero
for failure.  The man page should make this clear.

A simple patch is provided below.


As a general note, the quality of the X11 API documentation is low.
Much of it seems to be boiler-plate and obvious questions and
caveats are not documented.  Of particular note, the meanings of
individual function parameters are often not explained (things like
"time   Specifies the time" -- time of what?).  And some pages
document functions which have little to do with each other.
Should I submit bug reports for those items as I notice them?

Also, two of the pages specifically state they are incomplete:

 "This manual pages[sic] needs a lot more work."

  XShapeQueryExtension.3x
  XmbufQueryExtension.3x

Thanks,
-Ross


--- XGetWindowAttributes.3x     2006-02-24 20:47:24.000000000 -0600
+++ XGetWindowAttributes.3x-updated     2006-02-24 20:48:17.000000000 -0600
@@ -192,7 +192,8 @@
 .ZN XGetWindowAttributes
 function returns the current attributes for the specified window to an
 .ZN XWindowAttributes
-structure.
+structure.  It returns a nonzero status on success; otherwise, it returns a
+zero status.
 .LP
 .ZN XGetWindowAttributes
 can generate
@@ -209,6 +210,8 @@
 These are described in the argument list.
 It is legal to pass to this function a window whose class is
 .ZN InputOnly .
+It returns a nonzero status on success; otherwise, it returns a
+zero status.
 .SH STRUCTURES
 The
 .ZN XWindowAttributes




-- System Information:
Debian Release: 3.1
Architecture: amd64 (x86_64)
Kernel: Linux 2.6.14.5
Locale: LANG=en_US, LC_CTYPE=en_US (charmap=ANSI_X3.4-1968) (ignored: LC_ALL set to C)

Versions of packages libx11-dev depends on:
ii  libc6-dev [libc-de 2.3.2.ds1-22          GNU C Library: Development Librari
ii  libx11-6           4.3.0.dfsg.1-14sarge1 X Window System protocol client li
ii  libxext-dev        4.3.0.dfsg.1-14sarge1 X Window System miscellaneous exte
ii  libxi-dev          4.3.0.dfsg.1-14sarge1 X Window System Input extension li
ii  x-dev              4.3.0.dfsg.1-14sarge1 X protocol development files
ii  xfree86-common     4.3.0.dfsg.1-14sarge1 X Window System (XFree86) infrastr
ii  xlibs-static-dev   4.3.0.dfsg.1-14sarge1 X Window System client library dev

-- no debconf information

--- End Message ---
--- Begin Message --- 
Source: libx11
Source-Version: 2:1.1-2

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

libx11-6-dbg_1.1-2_i386.deb
  to pool/main/libx/libx11/libx11-6-dbg_1.1-2_i386.deb
libx11-6_1.1-2_i386.deb
  to pool/main/libx/libx11/libx11-6_1.1-2_i386.deb
libx11-data_1.1-2_all.deb
  to pool/main/libx/libx11/libx11-data_1.1-2_all.deb
libx11-dev_1.1-2_i386.deb
  to pool/main/libx/libx11/libx11-dev_1.1-2_i386.deb
libx11-xcb-dev_1.1-2_i386.deb
  to pool/main/libx/libx11/libx11-xcb-dev_1.1-2_i386.deb
libx11-xcb1-dbg_1.1-2_i386.deb
  to pool/main/libx/libx11/libx11-xcb1-dbg_1.1-2_i386.deb
libx11-xcb1_1.1-2_i386.deb
  to pool/main/libx/libx11/libx11-xcb1_1.1-2_i386.deb
libx11_1.1-2.diff.gz
  to pool/main/libx/libx11/libx11_1.1-2.diff.gz
libx11_1.1-2.dsc
  to pool/main/libx/libx11/libx11_1.1-2.dsc



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 354315@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Josh Triplett <josh@freedesktop.org> (supplier of updated libx11 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: SHA1

Format: 1.7
Date: Sat, 25 Nov 2006 14:37:58 -0800
Source: libx11
Binary: libx11-6-dbg libx11-data libx11-6 libx11-xcb1-dbg libx11-xcb1 libx11-dev libx11-xcb-dev
Architecture: source i386 all
Version: 2:1.1-2
Distribution: experimental
Urgency: low
Maintainer: Debian X Strike Force <debian-x@lists.debian.org>
Changed-By: Josh Triplett <josh@freedesktop.org>
Description: 
 libx11-6   - X11 client-side library
 libx11-6-dbg - X11 client-side library (debug package)
 libx11-data - X11 client-side library
 libx11-dev - X11 client-side library (development headers)
 libx11-xcb-dev - Xlib/XCB interface library (development headers)
 libx11-xcb1 - Xlib/XCB interface library
 libx11-xcb1-dbg - Xlib/XCB interface library (debug package)
Closes: 354315
Changes: 
 libx11 (2:1.1-2) experimental; urgency=low
 .
   [ Josh Triplett ]
   * Include some upstream post-1.1 fixes in debian/patches:
     * "Bug #9153: Fix access to freed memory."
     * "Bug #9154: Always process an event for _XReadEvents, even if an error
        occurs"; fixes an assertion failure, first observed with xcompmgr.
     * "Debian bug #354315: Clarify return value in XGetWindowAttributes man
        page" (closes: 354315)
   * Fix override discrepancies: library packages go in libs, -dbg and -dev
     packages go in libdevel.  Fix for both the libx11 packages and the new
     libx11-xcb packages.
Files: 
 4e09e75fe90bd37d0e76f4699f252ee2 1107 x11 optional libx11_1.1-2.dsc
 a92cd6de32ebed7a2a5c7249fa13bebe 136244 x11 optional libx11_1.1-2.diff.gz
 49c9271b4e0ad8766bde65110c9c8893 156910 x11 optional libx11-data_1.1-2_all.deb
 48cf68eb8e8aa5505b6ca189038c5055 558066 libs optional libx11-6_1.1-2_i386.deb
 c273907c2656e4e35977539a8ba05037 2456332 libdevel extra libx11-6-dbg_1.1-2_i386.deb
 5456a41bbaba6f7095c1e3caf4d36f7b 8679192 libdevel optional libx11-dev_1.1-2_i386.deb
 e05af8821b2eb998f1e0ddee2a6ad4ed 20094 libs optional libx11-xcb1_1.1-2_i386.deb
 29db92bbdf40ddb229f00f8dbddd27f8 34352 libdevel extra libx11-xcb1-dbg_1.1-2_i386.deb
 8146572be9ba820d3b230f72f0249264 39856 libdevel optional libx11-xcb-dev_1.1-2_i386.deb

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

iD8DBQFFaNV4p1aplQ4I9mURAraIAJ0bwzwCULe0oW5b3YLi2cXgZcRSyACfb4Jv
p5J+SqvVUziaDW8n8So/jMg=
=d2Xw
-----END PGP SIGNATURE-----

--- End Message ---
Reply to: