epoll_create.2: Rework discussion of 'size' argument

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/epoll_create.2

@@ -36,17 +36,10 @@ epoll_create, epoll_create1 \- open an epoll file descriptor
 .BR epoll_create ()
 creates an
 .BR epoll (7)
-"instance",
-requesting the kernel to allocate an event backing store dimensioned for
+instance.
+Since Linux 2.6.8, the
 .I size
-descriptors.
-The
-.I size
-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 unused; see NOTES below.)
+argument is ignored, but must be greater than zero; see NOTES below.
 
 .BR epoll_create ()
 returns a file descriptor referring to the new epoll instance.
@@ -128,11 +121,28 @@ Library support is provided in glibc starting with version 2.9.
 .BR epoll_create ()
 is Linux-specific.
 .SH NOTES
-Since Linux 2.6.8, the
+In the initial
+.BR epoll_create ()
+implementation, the
 .I size
-argument is unused, but must be greater than zero.
-(The kernel dynamically sizes the required data structures
-without needing this initial hint.)
+argument informed the kernel of the number of file descriptors
+that the caller expected to add to the
+.B epoll
+instance.
+The kernel used this information as a hint for the amount of
+space to initially allocate in internal data structures describing events.
+(If necessary, the kernel would allocate more space
+if the caller's usage exceeded the hint given in
+.IR size .)
+Nowadays,
+this hint is no longer required
+(the kernel dynamically sizes the required data structures
+without needing the hint), but
+.I size
+must still be greater than zero,
+in order to ensure backward compatibility when new
+.B epoll
+applications are run on older kernels.
 .SH "SEE ALSO"
 .BR close (2),
 .BR epoll_ctl (2),