Debian Bug report logs - #705293
manpages-dev: access(2) does not document return-value behavior for F_OK

Toggle useless messages

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

From: The Wanderer <wanderer@fastmail.fm>

To: submit@bugs.debian.org

Subject: manpages-dev: access(2) does not document return-value behavior for F_OK

Date: Fri, 12 Apr 2013 11:26:52 -0400

Package: manpages-dev
Version: 3.44-1
Severity: normal

Dear Maintainer,

The man page for the 'access' function describes two ways to use the
function: to check whether the current real user ID has specific
permissions for a file (R_OK, W_OK, X_OK), or to check whether that file simply
exists (F_OK).

The "Return Value" section of the man page, however, appears to be
written exclusively in the context of the "check permissions" modes. It
documents a value of zero as meaning "success (all requested permissions
granted)", but does not describe the meanings of return values when checking
only for existence rather than attempting to check any permissions.

A usage example near the bottom of what appears to be the z/OS man page for the
same function

http://publib.boulder.ibm.com/infocenter/zos/v1r11/topic/com.ibm.zos.r11.bpxbd00/rtacc.htm
seems to indicate that in the "check existence" mode, a return value of
zero indicates that the file exists, and nonzero indicates that the
file does not exist; however, even in that version of the man page, the
"Returned Value" section appears to be written exclusively in the
context of the "check permissions" modes.


-- System Information:
Debian Release: 7.0
  APT prefers stable-updates
  APT policy: (500, 'stable-updates'), (500, 'testing'), (500, 'stable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 3.2.0-4-amd64 (SMP w/12 CPU cores)
Locale: LANG=en_US.UTF-8, 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.44-1

manpages-dev recommends no packages.

Versions of packages manpages-dev suggests:
ii  man-db [man-browser]  2.6.2-1

-- no debconf information

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

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

To: The Wanderer <wanderer@fastmail.fm>, 705293@bugs.debian.org

Cc: control@bugs.debian.org

Subject: Re: Bug#705293: manpages-dev: access(2) does not document return-value behavior for F_OK

Date: Tue, 16 Apr 2013 08:01:38 +0200

tags 705293 fixed-upstream
thanks

On Fri, Apr 12, 2013 at 5:26 PM, The Wanderer <wanderer@fastmail.fm> wrote:
> Package: manpages-dev
> Version: 3.44-1
> Severity: normal
>
> Dear Maintainer,
>
> The man page for the 'access' function describes two ways to use the
> function: to check whether the current real user ID has specific
> permissions for a file (R_OK, W_OK, X_OK), or to check whether that file
> simply
> exists (F_OK).
>
> The "Return Value" section of the man page, however, appears to be
> written exclusively in the context of the "check permissions" modes. It
> documents a value of zero as meaning "success (all requested permissions
> granted)", but does not describe the meanings of return values when checking
> only for existence rather than attempting to check any permissions.
>
> A usage example near the bottom of what appears to be the z/OS man page for
> the
> same function
>
> http://publib.boulder.ibm.com/infocenter/zos/v1r11/topic/com.ibm.zos.r11.bpxbd00/rtacc.htm
> seems to indicate that in the "check existence" mode, a return value of
> zero indicates that the file exists, and nonzero indicates that the
> file does not exist; however, even in that version of the man page, the
> "Returned Value" section appears to be written exclusively in the
> context of the "check permissions" modes.

Thanks for the report. I agree that the page should be clearer on this
point. I've amended the REURN VALUE section to read:

       On success (all requested permissions granted, or mode is  F_OK
       and the file exists), zero is returned.  On error (at least one
       bit in mode asked for a permission that is denied, or  mode  is
       F_OK  and  the  file  does  not  exist,  or  some  other  error
       occurred), -1 is returned, and errno is set appropriately.

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 #19 received at 705293-close@bugs.debian.org (full text, mbox, reply):

From: Simon Paillard <spaillard@debian.org>

To: 705293-close@bugs.debian.org

Subject: Bug#705293: fixed in manpages 3.51-1

Date: Thu, 23 May 2013 22:48:40 +0000

Source: manpages
Source-Version: 3.51-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 705293@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 May 2013 23:05:10 +0200
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 3.51-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: 182014 235967 533232 542601 553413 575077 578178 620746 674034 676264 692136 699387 700529 704787 705293
Changes: 
 manpages (3.51-1) unstable; urgency=low
 .
   * Imported Upstream version 3.51:
     . new manpages: kcmp.3 s390_runtime_instr.2 if_freenameindex.3
       if_indextoname.3 if_nameindex.3 if_nametoindex.3 (Closes: #235967)
       perf_event_open.2 getcontext.3 getdtablesize.3 pthread_getname_np.3
       pthread_setname_np.3 setcontext.3 sln.8
       fattach.2 fdetach.2 getmsg.2 getunwind.2 isastream.2
       perfmonctl.2 putmsg.2 nss.5
     . ttyname.3: Fix confused text in ERRORS (Closes: #676264)
     . proc.5: Add field numbers for (Closes: #553413)
     . read.2: Remove crufty text about O_NONBLOCK on files (Closes: #700529)
     . read.2: Clarify interaction of count==0 and error check (Closes: #533232)
     . getpeername.2: Clarify semantics of getpeername() for datagram
       sockets (Closes: #674034)
     . mmap.2: Some 'flags' values require a feature test macro to be
       defined (Closes: #542601)
     . resolver.3, resolv.conf.5: RES_DEBUG is only available if glibc is
       compiled with debug support (Closes: #692136)
     . stdarg.3: Describe va_copy() (Closes: #575077)
     . futimes.3: ERRORS: Add ENOSYS for lutimes() (Closes: #620746)
     . units.7: units should use an actual µ (Closes: #704787)
     . access.2: Clarify RETURN VALUE for F_OK (Closes: #705293)
     . resolv.conf.5: Document "single-request-reopen" option (Closes: #699387)
     . bootparam.7: Document 'rootfstype' option (Closes: #182014)
     . ioperm.2: Linux 2.6.8 lifted the port limit to 65,536 (Closes: #578178)
   * d/rules: build-{arch,indep} as required by policy 3.9.4
   * lintian overrides: FSSTND-dir-in-manual-page are alternate path
Checksums-Sha1: 
 f277d33dc4ae2e2824fd7f2d747ec18f272a0d59 1907 manpages_3.51-1.dsc
 96c93e69f4e5db0952361b25db3eb3c19504ac1f 1828168 manpages_3.51.orig.tar.gz
 beaf9204e88e4406e7afd7d6014e7ea7af620e2f 47215 manpages_3.51-1.diff.gz
 db917de30d91a0382c32b8a71a57331eb0da7d40 823120 manpages_3.51-1_all.deb
 3d8a2bba0b3c9cb0ef8e4ab545eb37b5b1bf1974 1803556 manpages-dev_3.51-1_all.deb
Checksums-Sha256: 
 bf5b05f49b85e86052694c2c80fc1a9119437c88b60f0606d786b301b1c6f07b 1907 manpages_3.51-1.dsc
 f6639351a6a9e7fd9a82bae7dbefa8cb73557794e04a5d6a05bf8f64b8457bad 1828168 manpages_3.51.orig.tar.gz
 0151dd7c6eeeae5f3e764b5a5ac03fa6a48e3c36eeaa19e550de2ccbf0cfb337 47215 manpages_3.51-1.diff.gz
 fd60606aecff76039e414d9930b528900c90916f226ab61e24a1ce782de85916 823120 manpages_3.51-1_all.deb
 ebf111927854d749bfe4b1b510fe4ac49b965ed3466795a0456c144de3e5311f 1803556 manpages-dev_3.51-1_all.deb
Files: 
 233eff29953c78f8c1257fda9f31a6d2 1907 doc important manpages_3.51-1.dsc
 bed1627674356ec85492c5e94619b23d 1828168 doc important manpages_3.51.orig.tar.gz
 3144b81732373b7f027c071c58f6c230 47215 doc important manpages_3.51-1.diff.gz
 4df5993a51d7985a0a271d0a4bf19d79 823120 doc important manpages_3.51-1_all.deb
 075aa05d2cae81593bf807ad5b56585f 1803556 doc optional manpages-dev_3.51-1_all.deb

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

iQIcBAEBCAAGBQJRnplOAAoJEN/3OMLRbPuiX0EP/0++s6v9aB7OtKEXos4RnFbQ
SAOyHWgLaBJ7ui/nb0OfUHWhZ3DxfgkGQmcDw0EU86pvr5FAJinMKV0rJ7s4YacY
VxL5Ryw0VlvnTBWt017c2GgRxFtMUZFY3wvuvB4hJRCnjFujR3e8ARvDjmYTGr/0
xIP/5dMqEXJIKKFBdg3PDI1p+MqG5xapINBX2kegRI6bAWmEXq356JkIvGy2QuLU
OKkrFeKijgaij8ZPuwDqrq2Wax3wsB8Qn4RKM64zRZpilEDvRZZHBBHwpdDFl8rr
iIlFuXeC0fePVMefJ1u7T8X640hoFMNBcYU5lJdT4rHKPlqDJFIU+C9SlRH1kxYX
+0x4EgzOxzLZfXmP0FoQpeCC4kOqpLOteFHylLHFr9RItKHmFdvBiPCGTjuAb71c
dtPJLx+LgXoHagvOI9wc1aS6AAsVove1PRJtAaj7jNK5SJX+o0chT2rWXkw2HHYy
sJMLb5ePdwP15IsuUwkN8XDyWsnEfPyM+hIgoPByyNZolEsrzXKlpAl62I5cCI/D
8LHgLmAhKEsRwbvvy9EhgzV5+qAS5ABL6T1BB55ZRKZ8omkMq5AXeHGhgYwISeYp
AdM4DTI0kWZ7yNgrJxsIMtewPgR2pI1Cgf+B7xzZHfP94+ogSKEq/jdvgJEml9St
INgTr6jypYWrNIjoJenf
=cbGv
-----END PGP SIGNATURE-----

Send a report that this bug log contains spam.