Re: Argument type for FS_IOC_GETFLAGS/FS_IOC_SETFLAGS ioctls

[Robert Edmonds <edmonds@debian.org>]

Theodore Ts'o wrote:
> On Wed, Nov 27, 2013 at 11:03:47AM +0100, Aurelien Jarno wrote:
> > People who do the things correctly lookup the argument type in
> > <linux/fs.h>, they see it's a long and then use a long in their code. And
> > they are right. The bare minimum would be to add a comment close to the
> > definition to explain to use an int and not a long.
> 
> The documentation is specifies the FS_IOC_GETFLAGS and FS_IOC_SETFLAGS
> takes an int * and int, respectively, in the ioctl_list man page.  As
> far as the "self documenting" ioctl numbering is concerned, I've
> always considered it "mostly harmless", but never as authoratative
> documentation.

the ioctl_list manpage, at least the version i'm looking at [0], which
appears to be the most up to date version available, appears to list the
correct argument types, but not under the names FS_IOC_GETFLAGS and
FS_IOC_SETFLAGS.

       // <include/linux/ext2_fs.h>

       0x80046601   EXT2_IOC_GETFLAGS     int *
       0x40046602   EXT2_IOC_SETFLAGS     const int *

the man page also describes itself as the list of ioctls for "Linux/i386
kernel 1.3.27".  i can easily see how a userspace developer could be
misled when looking at ioctl_list(2) and <linux/fs.h>.

[0] http://man7.org/linux/man-pages/man2/ioctl_list.2.html,
    http://git.kernel.org/cgit/docs/man-pages/man-pages.git/tree/man2/ioctl_list.2

> In any case, sure, we can add a documentation to the header file in
> the kernel sources, and the glibc folks will need to be asked to fix
> up /usr/include/linux/fs.h (which is not the same as the
> include/linux/fs.h in the kernel).  But it doesn't change the fact
> that it is bup and libexplain that will need to be changed, regardless
> of whether they were in the "right" or in the "wrong".  If the sense
> of moral superiority makes them more willing to fix their code, fine.

i am sure that the userspace developers in this case are only interested
in using the ioctl correctly on all architectures, and figuring out what
led to the incorrect usage in the first place.

-- 
Robert Edmonds
edmonds@debian.org