123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207 |
- .\" SPDX-License-Identifier: BSD-2-Clause
- .\"
- .\" Copyright (c) 2020 Val Packett <val@packett.cool>
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .Dd October 8, 2020
- .Dt EVENTFD 2
- .Os
- .Sh NAME
- .Nm eventfd
- .Nd create a file descriptor for event notification
- .Sh LIBRARY
- .Lb libc
- .Sh SYNOPSIS
- .In sys/eventfd.h
- .Ft int
- .Fn eventfd "unsigned int initval" "int flags"
- .Ft int
- .Fn eventfd_read "int fd" "eventfd_t *value"
- .Ft int
- .Fn eventfd_write "int fd" "eventfd_t value"
- .Sh DESCRIPTION
- .Fn eventfd
- creates a special file descriptor with event counter or semaphore semantics,
- designed for interprocess communication.
- The returned file descriptor refers to a kernel object containing an
- unsigned 64-bit integer counter, which is initialized with the value of the
- .Fa initval
- argument.
- .Pp
- The
- .Fa flags
- argument may contain the result of
- .Em or Ns 'ing
- the following values:
- .Pp
- .Bl -tag -width "EFD_SEMAPHORE" -compact
- .It Dv EFD_CLOEXEC
- set FD_CLOEXEC on the file descriptor
- .It Dv EFD_NONBLOCK
- do not block on read/write operations
- .It Dv EFD_SEMAPHORE
- use semaphore semantics
- .El
- .Pp
- File operations have the following semantics:
- .Bl -tag -width EFD_SEMAPHORE
- .It Xr read 2
- If the counter is zero, the call blocks until the counter becomes non-zero, unless
- .Dv EFD_NONBLOCK
- was set, in which case it would fail with
- .Dv EAGAIN
- instead.
- .Pp
- If the counter is non-zero:
- .Bl -bullet
- .It
- If
- .Dv EFD_SEMAPHORE
- is not set, the current value of the counter is returned,
- and the value is reset to zero.
- .It
- If
- .Dv EFD_SEMAPHORE
- is set, the constant 1 is returned, and the value is decremented by 1.
- .El
- .Pp
- The numeric value is encoded as 64-bit (8 bytes) in host byte order.
- The
- .Xr read 2
- call fails with
- .Dv EINVAL
- if there is less than 8 bytes available in the supplied buffer.
- .It Xr write 2
- Adds the given value to the counter.
- The maximum value that can be stored in the counter is the
- maximum unsigned 64-bit integer value minus one (0xfffffffffffffffe).
- .Pp
- If the resulting value exceeds the maximum, the call would block
- until the value is reduced by
- .Xr read 2 ,
- unless
- .Dv EFD_NONBLOCK
- was set, in which case it would fail with
- .Dv EAGAIN
- instead.
- .Pp
- The numeric value is encoded as 64-bit (8 bytes) in host byte order.
- The
- .Xr write 2
- call fails with
- .Dv EINVAL
- if there is less than 8 bytes available in the supplied buffer,
- or if the value 0xffffffffffffffff is given.
- .It Xr poll 2
- When receiving notifications via
- .Xr poll 2 /
- .Xr ppoll 2 /
- .Xr select 2 /
- .Xr pselect 2 /
- .Xr kqueue 2 ,
- the following semantics apply:
- .Bl -bullet
- .It
- The file descriptor is readable when the counter is greater than zero.
- .It
- The file descriptor is writable when the counter is less than the maximum value.
- .El
- .El
- .Pp
- File descriptors created by
- .Fn eventfd
- are passable to other processes via
- .Xr sendmsg 2
- and are preserved across
- .Xr fork 2 ;
- in both cases the descriptors refer to the same counter from both processes.
- Unless
- .Dv O_CLOEXEC
- flag was specified,
- the created file descriptor will remain open across
- .Xr execve 2
- system calls; see
- .Xr close 2 ,
- .Xr fcntl 2
- and
- .Dv O_CLOEXEC
- description.
- .Pp
- .Fn eventfd_read
- and
- .Fn eventfd_write
- are thin wrappers around
- .Xr read 2
- and
- .Xr write 2
- system calls,
- provided for compatibility with glibc.
- .Sh RETURN VALUES
- If successful,
- .Fn eventfd
- returns a non-negative integer, termed a file descriptor.
- It returns \-1 on failure, and sets
- .Va errno
- to indicate the error.
- .Pp
- The
- .Fn eventfd_read
- and
- .Fn eventfd_write
- functions return 0 if the operation succeeded, -1 otherwise.
- .Sh ERRORS
- .Fn eventfd
- may fail with:
- .Bl -tag -width Er
- .It Bq Er EINVAL
- The
- .Fa flags
- argument given to
- .Fn eventfd
- has unknown bits set.
- .It Bq Er EMFILE
- The process has already reached its limit for open
- file descriptors.
- .It Bq Er ENFILE
- The system file table is full.
- .It Bq Er ENOMEM
- No memory was available to create the kernel object.
- .El
- .Sh SEE ALSO
- .Xr close 2 ,
- .Xr kqueue 2 ,
- .Xr poll 2 ,
- .Xr read 2 ,
- .Xr select 2 ,
- .Xr write 2
- .Sh STANDARDS
- The
- .Fn eventfd
- system call is non-standard.
- It is present in Linux.
- .Sh HISTORY
- The
- .Fn eventfd
- system call first appeared in
- .Fx 13.0 .
|