eventfd man

概要

      #include <sys/eventfd.h>

      int eventfd(unsigned int initval, int flags);

描述

eventfd()创建一个“eventfd对象”，这个对象能被用户空间应用用作一个事件等待/响应机制，靠内核去响应用户空间应用事件。这个对象包含一个由内核保持的无符号64位整型计数器。这个计数器由参数initval说明的值来初始化。

从linux2.6.27开始，下面的值可以在flags中被 OR 来改变eventfd()的行为：

EFD_NONBLOCK  在新打开的文件描述符中设置O_NONBLOCK文件状态标示。使用这个标示节省了对fcntl的额外调               用。

EFD_CLOEXEC   在新打开的文件描述符中设置close-on-exec(FD_CLOEXEC)标示。

在linux2.6.26版本以下，flags参数都是不能够使用的，必须为0.

eventfd()返回一个新的与eventfd对象关联的文件描述符。下面的操作能在这个文件描述符上执行：

read

如果eventfd计数器为一个非0值，read返回包含这个值的8个字节，并且这个计数器的值被重置为0.（返回的值为主机字节序）。

如果read的时候计数器为0，调用要么阻塞直到计数器变为非0，要么失败返回EAGAIN，如果文件描述符是非阻塞的话。

read会失败返回EINVAL，如果提供的buffer大小小于8字节的话。

write

write调用向计数器增加一个由它的buffer提供的8字节整型值。计数器能存储的最大值是最大的无符号64位整型值少1（0xfffffffffffffffe)。如果增加导致计时器的值超过了最大值，write要么阻塞直到一个read在这个文件描述符上执行，要么返回EAGAIN，如果文件描述法是非阻塞的。

write会失败返回EINVAL，如果提供的buffer大小小于8字节的话，或者如果试图写入值0xffffffffffffff。

poll，select（等）

返回的文件描述符支持poll和select，如下：

文件描述符是可读的（seceltreadfds参数；）如果计数器值大于0.

文件描述符是可写的，如果它可以被写入一个至少为1的值而不会被阻塞。

如果计数器值被检测到溢出了，select会指示这个文件描述符为可读可写。如上所提醒的，write决不能溢出计数器。

eventfd文件描述符也支持其他文件多路转接API：pselcet，ppoll，epoll。

close

当文件描述符不再被需要的时候它要被关闭。当所有和同一个eventfd对象相联系的文件描述符被关系时，对象的资源就被内核清空。

由eventfd()创建的文件描述符拷贝被子进程通过fork所继承。文件描述符的副本是同同一个eventfd对象相联系的。由eventfd()创建的文件描述符在execve时被保留。

返回值

成功时，eventfd()返回一个新的eventfd文件描述符。失败时，返回-1，errno指出错误情况。

错误

EINVAL   标示不合法；在linux2.6.26或更早版本中，flags非0。

EMFILE   到达进程最大打开文件描述符限制。

ENFILE   到达系统总共能打开的文件数。

ENODEV   不能挂载匿名节点设备。

ENOMEM   没有创建一个新eventfd文件描述符的足够内存。

版本

eventfd()自从2.6.22开始可用。glibc版本2.8开始提供支持。eventfd2()系统调用从linux2.6.27开始可用。自从2.9开始，glibc eventfd()用evnetfd2()系统调用封装，如果内核支持的话。

注意

应用可以使用一个eventfd文件描述符来取代一个管道，在所有管道用来作为事件通知的情况下。内核消耗在一个eventfd文件描述符上的远比在一个管道上的少，并且仅需要一个文件描述符（管道需要2个）。

当使用在内核中时，一个eventfd文件描述符能提供一个内核-用户空间的桥梁。

一个关于eventfd要指出的地方是它能像其他文件描述符一样用select，poll。epoll来监控。这意味着一个应用能同时监控：传统“文件的读端，和其他支持eventfd接口的内核机制的读端。

后面的不想翻译了

EXAMPLE

The following program creates an eventfd file descriptor and then forks to create a child process. While the parent briefly sleeps, the child writes each of the integers supplied in the program's command-line arguments to the eventfd file descriptor. When the parent has finished sleeping, it reads from the eventfd file descriptor.

The following shell session shows a sample run of the program:

 $ ./a.out 1 2 4 7 14 

 Child writing 1 to efd 

 Child writing 2 to efd 

 Child writing 4 to efd 

 Child writing 7 to efd 

 Child writing 14 to efd 

 Child completed write loop 

 Parent about to read Parent read 28 (0x1c) from efd

Program source

#include <sys/eventfd.h> 

#include <unistd.h> 

#include <stdlib.h>

#include <stdio.h> 

#include <stdint.h> 

 #define handle_error(msg) \ 

 do { perror(msg); exit(EXIT_FAILURE); } while (0) 

 int main(int argc, char *argv[]) 

 { int efd, j; 

 uint64_t u; 

 ssize_t s; 

 if (argc < 2) 

{ 

 fprintf(stderr, "Usage: %s <num>...\n", argv[0]); 

 exit(EXIT_FAILURE); 

 } 

 efd = eventfd(0, 0);

 if (efd == -1) handle_error("eventfd"); 

 switch (fork()) 

{ 

 case 0: 

 for (j = 1; j < argc; j++) 

{ 

 printf("Child writing %s to efd\n", argv[j]);

 u = strtoull(argv[j], NULL, 0); 

 s = write(efd, &u, sizeof(uint64_t)); 

 if (s != sizeof(uint64_t)) 

 handle_error("write"); 

 } 

 printf("Child completed write loop\n"); 

 exit(EXIT_SUCCESS); 

 default:

 sleep(2); 

 printf("Parent about to read\n"); 

 s = read(efd, &u, sizeof(uint64_t));

 if (s != sizeof(uint64_t)) 

 handle_error("read"); 

 printf("Parent read %llu (0x%llx) from efd\n", (unsigned long long) u, (unsigned long long) u); 

 exit(EXIT_SUCCESS); 

 case -1: 

 handle_error("fork"); 

 }

 }