Differential D26668 Diff 78167 lib/libc/sys/eventfd.2

Changeset View

Standalone View

lib/libc/sys/eventfd.2

This file was added.

				.\" SPDX-License-Identifier: BSD-2-Clause
				.\"
				.\" Copyright (c) 2020 Greg V
				.\"
				.\" 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.
				.\"
				.\" $FreeBSD$
				.\"
				.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,
				xtouqh_icloud.comUnsubmitted Not Done Inline Actions How about: The .Fn eventfd system call creates ... xtouqh_icloud.com: How about: The .Fn eventfd system call creates ...
				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
				.Bd -literal -offset indent -compact
				EFD_CLOEXEC set FD_CLOEXEC on the file descriptor
				xtouqh_icloud.comUnsubmitted Done Inline Actions I would use the proper list instead of literal one: .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 xtouqh_icloud.com: I would use the proper list instead of literal one: .Bl -tag -width "EFD_SEMAPHORE" -compact .
				EFD_NONBLOCK do not block on read/write operations
				EFD_SEMAPHORE use semaphore semantics
				.Ed
				.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 -tag -width *
				.It *
				xtouqh_icloud.comUnsubmitted Done Inline Actions Use .Bl -bullet or .Bl -dash and .It without arguments instead of re-inventing one :) xtouqh_icloud.com: Use .Bl -bullet or .Bl -dash and .It without arguments instead of re-inventing one :)
				If
				.Dv EFD_SEMAPHORE
				is not set, the current value of the counter is returned,
				and the value is reset to zero.
				.It *
				markjUnsubmitted Done Inline Actions This paragraph is mixing tenses. I think "is not set" is better, ditto below. markj: This paragraph is mixing tenses. I think "is not set" is better, ditto below.
				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 -tag -width *
				.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
				markjUnsubmitted Done Inline Actions returns markj: returns
				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 flags argument given to
				.Fn eventfd
				xtouqh_icloud.comUnsubmitted Done Inline Actions The .Fa flags argument ... xtouqh_icloud.com: The .Fa flags argument ...
				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 .