[PATCH] Epoll documentation

[PATCH] Epoll documentation

[Chris "ク" Heath]

A few months ago, Davide Libenzi wrote this message on lkml:
  http://marc.info/?l=linux-kernel&m=119368443105320&w=2
but apparently hasn't found time yet to review the man page.

So I figured it might work better if I propose a patch and get Davide to
ack it or suggest further changes.  My proposed patch to epoll(7) is
below.

Feedback would be appreciated.  In particular, I removed reference to
threads in A1 because I was unable to find a test case where I didn't
get EEXIST.  Maybe I'm missing something.

Chris


--- man-pages-2.78/man7/epoll.7.orig	2008-02-11 06:53:44.000000000 -0500
+++ man-pages-2.78/man7/epoll.7	2008-02-21 23:43:53.000000000 -0500
@@ -234,11 +234,11 @@
 What happens if you add the same file descriptor to an epoll set twice?
 .TP
 .B A1
-You will probably get
+You will get
 .BR EEXIST .
-However, it is possible that two
-threads may add the same file descriptor twice.
-This is a harmless condition.
+However, it is possible to add a
+.BR dup (2)
+of that file descriptor to the epoll set.
 .TP
 .B Q2
 Can two
@@ -285,7 +285,15 @@
 sets automatically?
 .TP
 .B A6
-Yes.
+Only if the underlying open file description (see
+.BR open (2))
+is closed.
+For example, if the file descriptor was duplicated with a
+.BR dup (2)
+or
+.BR fork (2)
+call, it will only be removed from epoll sets when all duplicate
+descriptors are closed.
 .TP
 .B Q7
 If more than one event occurs between

Re: [PATCH] Epoll documentation

[Davide Libenzi]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: TEXT/PLAIN; charset=X-UNKNOWN, Size: 703 bytes --]

On Fri, 22 Feb 2008, Chris "ã~B¯" Heath wrote:

> A few months ago, Davide Libenzi wrote this message on lkml:
>   http://marc.info/?l=linux-kernel&m=119368443105320&w=2
> but apparently hasn't found time yet to review the man page.
> 
> So I figured it might work better if I propose a patch and get Davide to
> ack it or suggest further changes.  My proposed patch to epoll(7) is
> below.
> 
> Feedback would be appreciated.  In particular, I removed reference to
> threads in A1 because I was unable to find a test case where I didn't
> get EEXIST.  Maybe I'm missing something.

I already sent a patch for that to Michael Kerrisk, short after I posted 
that message.


- Davide

Re: [PATCH] Epoll documentation

[Michael Kerrisk]

On Fri, Feb 22, 2008 at 6:05 PM, Davide Libenzi <davidel-AhlLAIvw+VFwn5V/fVEdqA@public.gmane.orgg> wrote:
> On Fri, 22 Feb 2008, Chris "ã~B¯" Heath wrote:
>
> > A few months ago, Davide Libenzi wrote this message on lkml:
> >   http://marc.info/?l=linux-kernel&m=119368443105320&w=2
> > but apparently hasn't found time yet to review the man page.
> >
> > So I figured it might work better if I propose a patch and get Davide to
> > ack it or suggest further changes.  My proposed patch to epoll(7) is
> > below.
> >
> > Feedback would be appreciated.  In particular, I removed reference to
> > threads in A1 because I was unable to find a test case where I didn't
> > get EEXIST.  Maybe I'm missing something.
>
> I already sent a patch for that to Michael Kerrisk, short after I posted
> that message.

That; true.  It's in my queue!

Cheers,

Michael

-- 
Michael Kerrisk
Maintainer of the Linux man-pages project
http://www.kernel.org/doc/man-pages/
Want to report a man-pages bug?  Look here:
http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: [PATCH] Epoll documentation

[Michael Kerrisk]

Michael Kerrisk wrote:
> On Fri, Feb 22, 2008 at 6:05 PM, Davide Libenzi <davidel@xmailserver.org> wrote:
>> On Fri, 22 Feb 2008, Chris "ã~B¯" Heath wrote:
>>
>>> A few months ago, Davide Libenzi wrote this message on lkml:
>>>   http://marc.info/?l=linux-kernel&m=119368443105320&w=2
>>> but apparently hasn't found time yet to review the man page.
>>>
>>> So I figured it might work better if I propose a patch and get Davide to
>>> ack it or suggest further changes.  My proposed patch to epoll(7) is
>>> below.
>>>
>>> Feedback would be appreciated.  In particular, I removed reference to
>>> threads in A1 because I was unable to find a test case where I didn't
>>> get EEXIST.  Maybe I'm missing something.
>> I already sent a patch for that to Michael Kerrisk, short after I posted
>> that message.
> 
> That; true.  It's in my queue!

Davide,

Actually, that was not completely true, as far as I can tell.  You sent me
a patch for Q6/A6 (which I finally responded to just now), but I can't find
any patch for Q1/A1...  I'll follow up in the other thread, and CC
linux-man and Chris.

Cheers,

Michael

-- 
Michael Kerrisk
Maintainer of the Linux man-pages project
http://www.kernel.org/doc/man-pages/
Want to report a man-pages bug?  Look here:
http://www.kernel.org/doc/man-pages/reporting_bugs.html