original/man2/epoll_create.2

   1 .\"
   2 .\"  epoll by Davide Libenzi ( efficient event notification retrieval )
   3 .\"  Copyright (C) 2003  Davide Libenzi
   4 .\"
   5 .\"  This program is free software; you can redistribute it and/or modify
   6 .\"  it under the terms of the GNU General Public License as published by
   7 .\"  the Free Software Foundation; either version 2 of the License, or
   8 .\"  (at your option) any later version.
   9 .\"
  10 .\"  This program is distributed in the hope that it will be useful,
  11 .\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 .\"  GNU General Public License for more details.
  14 .\"
  15 .\"  You should have received a copy of the GNU General Public License
  16 .\"  along with this program; if not, write to the Free Software
  17 .\"  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 .\"
  19 .\"  Davide Libenzi <davidel@xmailserver.org>
  20 .\"
  21 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  22 .\" Modified 2005-04-04 by Marko Kohtala <marko.kohtala@gmail.com>
  23 .\" 2008-10-10, mtk: add description of epoll_create1()
  24 .\"
  25 .TH EPOLL_CREATE 2 2009-01-17 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 epoll_create, epoll_create1 \- open an epoll file descriptor
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <sys/epoll.h>
  31 .sp
  32 .BI "int epoll_create(int " size );
  33 .BI "int epoll_create1(int " flags );
  34 .fi
  35 .SH DESCRIPTION
  36 .BR epoll_create ()
  37 creates an epoll "instance",
  38 requesting the kernel to allocate an event backing store dimensioned for
  39 .I size
  40 descriptors.
  41 The
  42 .I size
  43 is not the maximum size of the backing store but
  44 just a hint to the kernel about how to dimension internal structures.
  45 (Nowadays,
  46 .I size
  47 is ignored; see NOTES below.)
  48
  49 .BR epoll_create ()
  50 returns a file descriptor referring to the new epoll instance.
  51 This file descriptor is used for all the subsequent calls to the
  52 .B epoll
  53 interface.
  54 When no longer required, the file descriptor returned by
  55 .BR epoll_create ()
  56 should be closed by using
  57 .BR close (2).
  58 When all file descriptors referring to an epoll instance have been closed,
  59 the kernel destroys the instance
  60 and releases the associated resources for reuse.
  61
  62 If
  63 .I flags
  64 is 0, then, other than the fact that the obsolete
  65 .I size
  66 argument is dropped,
  67 .BR epoll_create1 ()
  68 is the same as
  69 .BR epoll_create ().
  70 The following value can be included in
  71 .IR flags
  72 to obtain different behavior:
  73 .TP
  74 .B EPOLL_CLOEXEC
  75 Set the close-on-exec
  76 .RB ( FD_CLOEXEC )
  77 flag on the new file descriptor.
  78 See the description of the
  79 .B O_CLOEXEC
  80 flag in
  81 .BR open (2)
  82 for reasons why this may be useful.
  83 .SH "RETURN VALUE"
  84 On success,
  85 these system calls
  86 return a nonnegative file descriptor.
  87 On error, \-1 is returned, and
  88 .I errno
  89 is set to indicate the error.
  90 .SH ERRORS
  91 .TP
  92 .B EINVAL
  93 .I size
  94 is not positive.
  95 .TP
  96 .B EINVAL
  97 .RB ( epoll_create1 ())
  98 Invalid value specified in
  99 .IR flags .
 100 .TP
 101 .B EMFILE
 102 The per-user limit on the number of epoll instances imposed by
 103 .I /proc/sys/fs/epoll/max_user_instances
 104 was encountered.
 105 See
 106 .BR epoll (7)
 107 for further details.
 108 .TP
 109 .B ENFILE
 110 The system limit on the total number of open files has been reached.
 111 .TP
 112 .B ENOMEM
 113 There was insufficient memory to create the kernel object.
 114 .SH CONFORMING TO
 115 .BR epoll_create ()
 116 is Linux-specific, and was introduced in kernel 2.5.44.
 117 .\" The interface should be finalized by Linux kernel 2.5.66.
 118 .SH NOTES
 119 Since Linux 2.6.8, the
 120 .I size
 121 argument is unused.
 122 (The kernel dynamically sizes the required data structures
 123 without needing this initial hint.)
 124 .SH "SEE ALSO"
 125 .BR close (2),
 126 .BR epoll_ctl (2),
 127 .BR epoll_wait (2),
 128 .BR epoll (7)