Bug 23872 - epoll_create(0) fails. Mismatch between implementation and manpage
Summary: epoll_create(0) fails. Mismatch between implementation and manpage
Status: RESOLVED CODE_FIX
Alias: None
Product: Documentation
Classification: Unclassified
Component: man-pages (show other bugs)
Hardware: All Linux
: P1 normal
Assignee: Michael Kerrisk
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2010-11-28 13:13 UTC by Joern Heissler
Modified: 2012-04-14 20:40 UTC (History)
2 users (show)

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


Attachments

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

SYNOPSIS
...
    int epoll_create(int size);
...
DESCRIPTION
...
    (Nowadays, size is ignored; see NOTES below.)
...
ERRORS
    EINVAL size is not positive.
...
NOTES
    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.
 (Nowadays,
 .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.
 .SH NOTES
 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.)
 .SH "SEE ALSO"
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).

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