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 
  16 .LP
  17 .nf
  18 #include <sys/epoll.h>
  19 
  20 \fBint\fR \fBepoll_create\fR(\fBint\fR \fIsize\fR);
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBint\fR \fBepoll_create1\fR(\fBint\fR \fIflags\fR);
  26 .fi
  27 
  28 .SH DESCRIPTION
  29 .LP
  30 The \fBepoll_create()\fR and \fBepoll_create1()\fR functions both create an
  31 \fBepoll\fR(5) instance that can be operated upon via \fBepoll_ctl\fR(3C),
  32 \fBepoll_wait\fR(3C) and \fBepoll_pwait\fR(3C).  \fBepoll\fR instances are
  33 represented as file descriptors, and should be closed via \fBclose\fR(2).
  34 
  35 The only difference between the two functions is their signature;
  36 \fBepoll_create()\fR takes a size argument that
  37 is vestigal and is only meaningful in as much as it must be greater than
  38 zero, while \fBepoll_create1()\fR takes a flags argument that can have
  39 any of the following values:
  40 
  41 .sp
  42 .ne 2
  43 .na
  44 \fBEPOLL_CLOEXEC\fR
  45 .ad
  46 .RS 12n
  47 Instance should be closed upon an
  48 \fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR.
  49 .RE
  50 
  51 .SH RETURN VALUES
  52 .LP
  53 Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno
  54 is set to indicate the error.
  55 .SH ERRORS
  56 .LP
  57 The \fBepoll_create()\fR and \fBepoll_create1()\fR functions will fail if:
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBEINVAL\fR\fR
  62 .ad
  63 .RS 10n
  64 Either the \fIsize\fR is zero (\fBepoll_create()\fR) or the \fIflags\fR
  65 are invalid (\fBepoll_create1()\fR).
  66 .RE
  67 
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBEMFILE\fR\fR
  72 .ad
  73 .RS 10n
  74 There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling
  75 process.
  76 .RE
  77 
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBENFILE\fR\fR
  82 .ad
  83 .RS 10n
  84 The maximum allowable number of files is currently open in the system.
  85 .RE
  86 
  87 .sp
  88 .SH NOTES
  89 .LP
  90 
  91 The \fBepoll\fR(5) facility is implemented for purposes of offering
  92 compatibility for Linux-borne applications; native
  93 applications should continue to prefer using event ports via the
  94 \fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C)
  95 interfaces.  See \fBepoll\fR(5) for compatibility details and restrictions.
  96 
  97 .SH SEE ALSO
  98 .LP
  99 \fBepoll_ctl\fR(3C), \fBepoll_wait\fR(3C), \fBepoll\fR(5)