Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
EVENTFD(2)		  FreeBSD System Calls Manual		    EVENTFD(2)

NAME
     eventfd --	create a file descriptor for event notification

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <sys/eventfd.h>

     int
     eventfd(unsigned int initval, int flags);

     int
     eventfd_read(int fd, eventfd_t *value);

     int
     eventfd_write(int fd, eventfd_t value);

DESCRIPTION
     eventfd() creates a special file descriptor with event counter or sema-
     phore 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 initval argu-
     ment.

     The flags argument	may contain the	result of or'ing the following values:

     EFD_CLOEXEC    set	FD_CLOEXEC on the file descriptor
     EFD_NONBLOCK   do not block on read/write operations
     EFD_SEMAPHORE  use	semaphore semantics

     File operations have the following	semantics:

     read(2)	    If the counter is zero, the	call blocks until the counter
		    becomes non-zero, unless EFD_NONBLOCK was set, in which
		    case it would fail with EAGAIN instead.

		    If the counter is non-zero:

		    +o	If EFD_SEMAPHORE is not	set, the current value of the
			counter	is returned, and the value is reset to zero.

		    +o	If EFD_SEMAPHORE is set, the constant 1	is returned,
			and the	value is decremented by	1.

		    The	numeric	value is encoded as 64-bit (8 bytes) in	host
		    byte order.	 The read(2) call fails	with EINVAL if there
		    is less than 8 bytes available in the supplied buffer.

     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).

		    If the resulting value exceeds the maximum,	the call would
		    block until	the value is reduced by	read(2), unless
		    EFD_NONBLOCK was set, in which case	it would fail with
		    EAGAIN instead.

		    The	numeric	value is encoded as 64-bit (8 bytes) in	host
		    byte order.	 The write(2) call fails with EINVAL if	there
		    is less than 8 bytes available in the supplied buffer, or
		    if the value 0xffffffffffffffff is given.

     poll(2)	    When receiving notifications via poll(2) / ppoll(2)	/
		    select(2) /	pselect(2) / kqueue(2),	the following seman-
		    tics apply:

		    +o	The file descriptor is readable	when the counter is
			greater	than zero.

		    +o	The file descriptor is writable	when the counter is
			less than the maximum value.

     File descriptors created by eventfd() are passable	to other processes via
     sendmsg(2)	and are	preserved across fork(2); in both cases	the descrip-
     tors refer	to the same counter from both processes.  Unless O_CLOEXEC
     flag was specified, the created file descriptor will remain open across
     execve(2) system calls; see close(2), fcntl(2) and	O_CLOEXEC description.

     eventfd_read() and	eventfd_write()	are thin wrappers around read(2) and
     write(2) system calls, provided for compatibility with glibc.

RETURN VALUES
     If	successful, eventfd() returns a	non-negative integer, termed a file
     descriptor.  It returns -1	on failure, and	sets errno to indicate the er-
     ror.

     The eventfd_read()	and eventfd_write() functions return 0 if the opera-
     tion succeeded, -1	otherwise.

ERRORS
     eventfd() may fail	with:

     [EINVAL]		The flags argument given to eventfd() has unknown bits
			set.

     [EMFILE]		The process has	already	reached	its limit for open
			file descriptors.

     [ENFILE]		The system file	table is full.

     [ENOMEM]		No memory was available	to create the kernel object.

SEE ALSO
     close(2), kqueue(2), poll(2), read(2), select(2), write(2)

STANDARDS
     The eventfd() system call is non-standard.	 It is present in Linux.

HISTORY
     The eventfd() system call first appeared in FreeBSD 13.0.

FreeBSD	13.0			October	8, 2020			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=eventfd&sektion=2&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help