Bug 23872

Summary: epoll_create(0) fails. Mismatch between implementation and manpage
Product: Documentation Reporter: Joern Heissler (kernelbugs)
Component: man-pagesAssignee: Michael Kerrisk (mtk.manpages)
Severity: normal CC: mtk.manpages, pebolle
Priority: P1    
Hardware: All   
OS: Linux   
Kernel Version: 2.6.36 Subsystem:
Regression: No Bisected commit-id:

Description Joern Heissler 2010-11-28 13:13:05 UTC
The epoll_create manpage (current version as of 2010-11-28) contains:

    int epoll_create(int size);
    (Nowadays, size is ignored; see NOTES below.)
    EINVAL size is not positive.
    Since Linux 2.6.8, the size argument is unused. ...

on the other hand, fs/eventpoll.c contains:
SYSCALL_DEFINE1(epoll_create, int, size)
        if (size <= 0)
                return -EINVAL;

        return sys_epoll_create1(0);

The size parameter is not ignored as stated in the manpage.
Please correct the manpage or remove the check inside the implementation.
Comment 1 Michael Kerrisk 2010-12-03 06:20:24 UTC
Thanks for this report Joern. Of course, the right change here is to fix the documentation. I applied this patch for man-pages-3.22:

--- a/man2/epoll_create.2
+++ b/man2/epoll_create.2
@@ -44,7 +44,7 @@ is not the maximum size of the backing store but
 just a hint to the kernel about how to dimension internal structures.
 .I size
-is ignored; see NOTES below.)
+is unused; see NOTES below.)
 .BR epoll_create ()
 returns a file descriptor referring to the new epoll instance.
@@ -118,7 +118,7 @@ is Linux-specific, and was introduced in kernel 2.5.44.
 Since Linux 2.6.8, the
 .I size
-argument is unused.
+argument is unused, but must be greater than zero.
 (The kernel dynamically sizes the required data structures
 without needing this initial hint.)
Comment 2 Paul Bolle 2011-07-24 18:34:32 UTC
(In reply to comment #1)
> I applied this patch for man-pages-3.22:

0) That actually was man-pages-3.32.

1) This bug can be CLOSED (and set to FIXED, I assume).