.\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
.\" starting from a version by Davide Libenzi <davidel@xmailserver.org>
.\"
+.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-.\" MA 02111-1307 USA
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
.\" 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
.SH DESCRIPTION
.BR eventfd ()
creates an "eventfd object" that can be used as
-an event wait/notify mechanism by userspace applications,
-and by the kernel to notify userspace applications of events.
+an event wait/notify mechanism by user-space applications,
+and by the kernel to notify user-space applications of events.
The object contains an unsigned 64-bit integer
.RI ( uint64_t )
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.
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
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\(emthat is,
+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
.IP
The eventfd file descriptor also supports the other file-descriptor
multiplexing APIs:
-.BR pselect (2),
-.BR ppoll (2),
+.BR pselect (2)
and
-.BR epoll (7).
+.BR ppoll (2).
.TP
.BR close (2)
When the file descriptor is no longer required it should be closed.
File descriptors created by
.BR eventfd ()
are preserved across
-.BR execve (2).
-.SH "RETURN VALUE"
+.BR execve (2),
+unless the close-on-exec flag has been set.
+.SH RETURN VALUE
On success,
.BR eventfd ()
returns a new eventfd file descriptor.
.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.
required (versus the two required for a pipe).
When used in the kernel, an eventfd
-file descriptor can provide a kernel-userspace bridge allowing,
+file descriptor can provide a bridge from kernel to user space, allowing,
for example, functionalities like KAIO (kernel AIO)
.\" or eventually syslets/threadlets
to signal to a file descriptor that some operation is complete.
}
}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR futex (2),
.BR pipe (2),
.BR poll (2),
.BR write (2),
.BR epoll (7),
.BR sem_overview (7)
+.SH COLOPHON
+This page is part of release 3.68 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
