Bug 42705 - ioctl prototype is incorrect
ioctl prototype is incorrect
Product: Documentation
Classification: Unclassified
Component: man-pages
All Linux
: P1 normal
Assigned To: documentation_man-pages@kernel-bugs.osdl.org
Depends on:
  Show dependency treegraph
Reported: 2012-01-31 18:17 UTC by KOSAKI Motohiro
Modified: 2013-11-07 17:39 UTC (History)
3 users (show)

See Also:
Kernel Version:
Tree: Mainline
Regression: No


Description KOSAKI Motohiro 2012-01-31 18:17:18 UTC
Now, the ioctl man page (*) says ioctl declaration is

    int ioctl(int d, int request, ...);

(*) http://www.kernel.org/doc/man-pages/online/pages/man2/ioctl.2.html

But, actual glibc implementtion has a different type.

  extern int ioctl (int __fd, unsigned long int __request, ...) __THROW;

Look, __request parameter actually has unsigned long type. it's not int.
It would be better if the man respect an implemtation.
Comment 1 David Gibson 2012-02-09 05:46:42 UTC
I just discovered this one too.  Some more information:

As the submitter pointed out glibc uses unsigned long, the kernel's sys_ioctl() prototype uses unsigned int.  In addition the kernel _IOC_ macros which are used to construct ioctl numbers result in unsigned expressions, and these macros are exposed to userland via the headers.  There _are_ a number of already used ioctls numbers which have bit 31 set, and so are negative as an 'int'.  Specifically IOC_READ ioctls will have bit 31 set on x86, and IOC_WRITE ones will have bit 31 set on powerpc, I haven't checked other archs.

This discepancy can cause real userspace bugs or compile failures: because the ioctl number macros are unsigned, if IOCTL is one of the standard ioctl number #defines based on these macros then the following code fragment:
        int x = IOCTL;
        if (x == IOCTL)
                /* ... */
Will generate a "comparison always false due to limited range of data type" warning from gcc, and presumably will indeed compare false, which is clearly not the expected result.

POSIX states that the ioctl number should be 'int', but clearly the kernel and libc treat it as unsigned.  Apparently most existing user code must treat it that way too, since we haven't noticed this problem before.  *BSD also appear to have it as unsigned long.  Changing the kernel prototype could result in similar bugs but the other way around for existing code, which would be bad.

Therefore, we should update the man pages to reflect reality, rather than POSIX.
Comment 2 Michael Kerrisk 2013-11-07 17:39:05 UTC
Thanks for the report, Motohiro, and the confirmation, David. I changed it to

int ioctl(int d, unsigned long request, ...);

Note You need to log in before you can comment on or make changes to this bug.