1 '\" te
   2 .\"  Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
   3 .\"  This file and its contents are supplied under the terms of the
   4 .\"  Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\"  You may only use this file in accordance with the terms of version
   6 .\"  1.0 of the CDDL.
   7 .\"
   8 .\"  A full copy of the text of the CDDL should have accompanied this
   9 .\"  source.  A copy of the CDDL is also available via the Internet at
  10 .\"  http://www.illumos.org/license/CDDL.
  11 .TH EPOLL_CREATE 3C "April 9, 2016"
  12 .SH NAME
  13 epoll_create, epoll_create1 \- create an epoll instance
  14 .SH SYNOPSIS
  15 .nf
  16 #include <sys/epoll.h>
  17 
  18 \fBint\fR \fBepoll_create\fR(\fBint\fR \fIsize\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBint\fR \fBepoll_create1\fR(\fBint\fR \fIflags\fR);
  24 .fi
  25 
  26 .SH DESCRIPTION
  27 The \fBepoll_create()\fR and \fBepoll_create1()\fR functions both create an
  28 \fBepoll\fR(5) instance that can be operated upon via \fBepoll_ctl\fR(3C),
  29 \fBepoll_wait\fR(3C) and \fBepoll_pwait\fR(3C).  \fBepoll\fR instances are
  30 represented as file descriptors, and should be closed via \fBclose\fR(2).
  31 
  32 The only difference between the two functions is their signature;
  33 \fBepoll_create()\fR takes a size argument that
  34 is vestigal and is only meaningful in as much as it must be greater than
  35 zero, while \fBepoll_create1()\fR takes a flags argument that can have
  36 any of the following values:
  37 
  38 .sp
  39 .ne 2
  40 .na
  41 \fBEPOLL_CLOEXEC\fR
  42 .ad
  43 .RS 12n
  44 Instance should be closed upon an
  45 \fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR.
  46 .RE
  47 
  48 .SH RETURN VALUES
  49 Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno
  50 is set to indicate the error.
  51 .SH ERRORS
  52 The \fBepoll_create()\fR and \fBepoll_create1()\fR functions will fail if:
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBEINVAL\fR\fR
  57 .ad
  58 .RS 10n
  59 Either the \fIsize\fR is zero (\fBepoll_create()\fR) or the \fIflags\fR
  60 are invalid (\fBepoll_create1()\fR).
  61 .RE
  62 
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBEMFILE\fR\fR
  67 .ad
  68 .RS 10n
  69 There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling
  70 process.
  71 .RE
  72 
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBENFILE\fR\fR
  77 .ad
  78 .RS 10n
  79 The maximum allowable number of files is currently open in the system.
  80 .RE
  81 
  82 .sp
  83 .SH NOTES
  84 The \fBepoll\fR(5) facility is implemented for purposes of offering
  85 compatibility for Linux-borne applications; native
  86 applications should continue to prefer using event ports via the
  87 \fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C)
  88 interfaces.  See \fBepoll\fR(5) for compatibility details and restrictions.
  89 
  90 .SH SEE ALSO
  91 \fBepoll_ctl\fR(3C), \fBepoll_wait\fR(3C), \fBepoll\fR(5)