(split) LDP man-pages の original/ を v3.29 に更新。

[linuxjm/LDP_man-pages.git] / original / man2 / eventfd.2

diff --git a/original/man2/eventfd.2 b/original/man2/eventfd.2
index 88ca50d..0bda275 100644 (file)
--- a/original/man2/eventfd.2
+++ b/original/man2/eventfd.2
@@ -18,7 +18,7 @@
 .\"
 .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC
 .\"
-.TH EVENTFD 2 2009-01-26 Linux "Linux Programmer's Manual"
+.TH EVENTFD 2 2010-08-30 Linux "Linux Programmer's Manual"
 .SH NAME
 eventfd \- create a file descriptor for event notification
 .SH SYNOPSIS
@@ -36,20 +36,12 @@ counter that is maintained by the kernel.
 This counter is initialized with the value specified in the argument
 .IR initval .
 
-Starting with Linux 2.6.27, the following values may be bitwise ORed in
+The following values may be bitwise ORed in
 .IR flags
 to change the behaviour of
 .BR eventfd ():
-.TP 14
-.B EFD_NONBLOCK
-Set the
-.BR O_NONBLOCK
-file status flag on the new open file description.
-Using this flag saves extra calls to
-.BR fcntl (2)
-to achieve the same result.
 .TP
-.B EFD_CLOEXEC
+.BR EFD_CLOEXEC " (since Linux 2.6.27)"
 Set the close-on-exec
 .RB ( FD_CLOEXEC )
 flag on the new file descriptor.
@@ -58,6 +50,18 @@ See the description of the
 flag in
 .BR open (2)
 for reasons why this may be useful.
+.TP
+.BR EFD_NONBLOCK " (since Linux 2.6.27)"
+Set the
+.BR O_NONBLOCK
+file status flag on the new open file description.
+Using this flag saves extra calls to
+.BR fcntl (2)
+to achieve the same result.
+.TP
+.BR EFD_SEMAPHORE " (since Linux 2.6.30)"
+Provide semaphore-like semantics for reads from the new file descriptor.
+See below.
 .PP
 In Linux up to version 2.6.26, the
 .I flags
@@ -70,25 +74,52 @@ eventfd object.
 The following operations can be performed on the file descriptor:
 .TP
 .BR read (2)
-If the eventfd counter has a nonzero value, then a
+Each successful
+.BR read (2)
+returns an 8-byte integer.
+A
+.BR read (2)
+will fail with the error
+.B EINVAL
+if the size of the supplied buffer is less than 8 bytes.
+.IP
+The value returned by
+.BR read (2)
+is in host byte order,
+i.e., the native byte order for integers on the host machine.
+.IP
+The semantics of
+.BR read (2)
+depend on whether the eventfd counter currently has a nonzero value
+and whether the
+.BR EFD_SEMAPHORE
+flag was specified when creating the eventfd file descriptor:
+.RS
+.IP * 3
+If
+.BR EFD_SEMAPHORE
+was not specified and the eventfd counter has a nonzero value, then a
 .BR read (2)
 returns 8 bytes containing that value,
 and the counter's value is reset to zero.
-(The returned value is in host byte order,
-i.e., the native byte order for integers on the host machine.)
-.IP
-If the counter is zero at the time of the
+.IP *
+If
+.BR EFD_SEMAPHORE
+was specified and the eventfd counter has a nonzero value, then a
+.BR read (2)
+returns 8 bytes containing the value 1,
+and the counter's value is decremented by 1.
+.IP *
+If the eventfd counter is zero at the time of the call to
 .BR read (2),
-then the call either blocks until the counter becomes nonzero,
+then the call either blocks until the counter becomes nonzero
+(at which time, the
+.BR read (2)
+proceeds as described above)
 or fails with the error
 .B EAGAIN
 if the file descriptor has been made nonblocking.
-.IP
-A
-.BR read (2)
-will fail with the error
-.B EINVAL
-if the size of the supplied buffer is less than 8 bytes.
+.RE
 .TP
 .BR write (2)
 A
@@ -186,7 +217,8 @@ eventfd object.
 File descriptors created by
 .BR eventfd ()
 are preserved across
-.BR execve (2).
+.BR execve (2),
+unless the close-on-exec flag has been set.
 .SH "RETURN VALUE"
 On success,
 .BR eventfd ()
@@ -197,11 +229,8 @@ is set to indicate the error.
 .SH ERRORS
 .TP
 .B EINVAL
-.I flags
-is invalid;
-or, in Linux 2.6.26 or earlier,
-.I flags
-is nonzero.
+An unsupported value was specified in
+.IR flags .
 .TP
 .B EMFILE
 The per-process limit on open file descriptors has been reached.