265 lines
5.9 KiB
Groff
265 lines
5.9 KiB
Groff
.\" $NetBSD: eventfd.2,v 1.2 2021/09/23 13:16:13 uwe Exp $
|
|
.\"
|
|
.\" Copyright (c) 2021 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Jason R. Thorpe.
|
|
.\"
|
|
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 September 17, 2021
|
|
.Dt EVENTFD 2
|
|
.Os
|
|
.\"
|
|
.\"
|
|
.Sh NAME
|
|
.Nm eventfd ,
|
|
.Nm eventfd_read ,
|
|
.Nm eventfd_write
|
|
.Nd create and interact with a counting event descriptor
|
|
.\"
|
|
.\"
|
|
.Sh SYNOPSIS
|
|
.In sys/eventfd.h
|
|
.Ft int
|
|
.Fn eventfd "unsigned int val" "int flags"
|
|
.Ft int
|
|
.Fn eventfd_read "int efd" "eventfd_t *valp"
|
|
.Ft int
|
|
.Fn eventfd_write "int efd" "eventfd_t val"
|
|
.\"
|
|
.\"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
interface presents a simple counting object associated with a file descriptor.
|
|
Writes and reads to this file descriptor increment and decrement the count,
|
|
respectively.
|
|
When the object's value is non-zero, the file descriptor is considered
|
|
.Dq readable ,
|
|
and when the count is less than the maximum value
|
|
.Li UINT64_MAX\^-\^1
|
|
it is considered
|
|
.Dq writable .
|
|
When an
|
|
.Nm
|
|
object is no longer needed, it may be disposed of using
|
|
.Xr close 2 .
|
|
.Pp
|
|
All I/O to an
|
|
.Nm
|
|
object is 8\~bytes in length, which is the space required to store an
|
|
unsigned 64-bit integer.
|
|
Any read or write with a buffer smaller than 8\~bytes will fail with
|
|
.Er EINVAL .
|
|
Only the first 8\~bytes of the buffer will be used.
|
|
.Pp
|
|
The
|
|
.Fn eventfd
|
|
function creates a new counting event object and returns a file descriptor
|
|
representing that object.
|
|
The initial value of the object is specified by the
|
|
.Fa val
|
|
argument.
|
|
The following flags define the behavior of the resulting object:
|
|
.Bl -tag -width Dv
|
|
.It Dv EFD_CLOEXEC
|
|
This is an alias for the
|
|
.Dv O_CLOEXEC
|
|
flag; see
|
|
.Xr open 2
|
|
for more information.
|
|
.It Dv EFD_NONBLOCK
|
|
This is an alias for the
|
|
.Dv O_NONBLOCK
|
|
flag; see
|
|
.Xr open 2
|
|
for more information.
|
|
.It Dv EFD_SEMAPHORE
|
|
Creates a
|
|
.Dq semaphore mode
|
|
object; see below for details.
|
|
.El
|
|
.Pp
|
|
Reads from an
|
|
.Nm
|
|
object return an unsigned 64-bit integer in the caller's buffer.
|
|
The semantics of this value are dependent on whether the
|
|
.Nm
|
|
object was created in
|
|
.Dq semaphore mode :
|
|
.Bl -bullet
|
|
.It
|
|
If the
|
|
.Nm
|
|
object was created in
|
|
.Dq semaphore mode ,
|
|
reads return the value\~1
|
|
and object's counter is decremented by\~1.
|
|
.It
|
|
If the
|
|
.Nm
|
|
object was not created in
|
|
.Dq semaphore mode ,
|
|
reads return the current value of the object's counter
|
|
and reset the counter to\~0.
|
|
.El
|
|
.Pp
|
|
If the value of the
|
|
.Nm
|
|
object's counter is\~0,
|
|
then reads will block, unless the
|
|
.Nm
|
|
object is set for non-blocking I/O.
|
|
.Pp
|
|
Writing to an
|
|
.Nm
|
|
object adds the unsigned 64-bit value provided in the caller's buffer
|
|
to the
|
|
.Nm
|
|
object's counter.
|
|
If adding the specified value would exceed the maximum value, then the
|
|
write will block, unless the
|
|
.Nm
|
|
object is set for non-blocking I/O.
|
|
.Pp
|
|
The convenience functions
|
|
.Fn eventfd_read
|
|
and
|
|
.Fn eventfd_write
|
|
are provided to simplify interacting with
|
|
.Nm
|
|
objects, and are simply wrappers around the
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
system calls:
|
|
.Bl -tag -width Fn
|
|
.It Fn eventfd_read efd valp
|
|
Reads the unsigned 64-bit integer value of the
|
|
.Nm
|
|
object and returns it in
|
|
.Fa valp .
|
|
.It Fn eventfd_write efd val
|
|
Writes the unsigned 64-bit integer value
|
|
.Fa val
|
|
to the
|
|
.Nm
|
|
object.
|
|
.El
|
|
.\"
|
|
.\"
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn eventfd
|
|
system call returns\~\-1 if an error occurs,
|
|
otherwise the return value is a descriptor representing the
|
|
.Nm
|
|
object.
|
|
.Pp
|
|
.Rv -std eventfd_read eventfd_write
|
|
.\"
|
|
.\"
|
|
.Sh ERRORS
|
|
The
|
|
.Fn eventfd
|
|
system call fails if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
Flags other than
|
|
.Dv EFD_CLOEXEC ,
|
|
.Dv EFD_NONBLOCK ,
|
|
and
|
|
.Dv EFD_SEMAPHORE
|
|
are set in the
|
|
.Fa flags
|
|
argument.
|
|
.It Bq Er EMFILE
|
|
The per-process descriptor table is full.
|
|
.It Bq Er ENFILE
|
|
The system file table is full.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn eventfd_read
|
|
function fails if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EAGAIN
|
|
The value of the
|
|
.Nm
|
|
object is\~0 and the
|
|
.Nm
|
|
object is set for non-blocking I/O.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn eventfd_write
|
|
function fails if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EAGAIN
|
|
The resulting value of the
|
|
.Nm
|
|
object after adding the value
|
|
.Fa val
|
|
would exceed the maximum value
|
|
.Li UINT64_MAX\^-\^1
|
|
and the
|
|
.Nm
|
|
object is set for non-blocking I/O.
|
|
.It Bq Er EINVAL
|
|
An attempt was made to write a value greater than the maximum value.
|
|
.El
|
|
.Pp
|
|
In addition to the errors returned by
|
|
.Fn eventfd_read
|
|
and
|
|
.Fn eventfd_write ,
|
|
a read from or write to an
|
|
.Nm
|
|
object fails if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The size of the buffer is less than 8\~bytes
|
|
.Pq the size required to hold an unsigned 64-bit integer .
|
|
.El
|
|
.\"
|
|
.\"
|
|
.Sh SEE ALSO
|
|
.Xr close 2 ,
|
|
.Xr kevent 2 ,
|
|
.Xr open 2 ,
|
|
.Xr poll 2 ,
|
|
.Xr read 2 ,
|
|
.Xr select 2 ,
|
|
.Xr write 2
|
|
.\"
|
|
.\"
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
interface first appeared in
|
|
.Nx 10 .
|
|
It is compatible with the
|
|
.Nm
|
|
interface that appeared in Linux 2.6.30.
|