sys/linux/epoll: add EPOLLWAKEUP constant, epoll_pwait() call and add documentation

Signed-off-by: Luís Ferreira <contact@lsferreira.net>

Author: ljmf00

src/core/sys/linux/epoll.d

@@ -10,6 +10,8 @@ module core.sys.linux.epoll;
 
 version (linux):
 
+import core.sys.posix.signal : sigset_t;
+
 extern (C):
 @system:
 @nogc:
@@ -52,16 +54,19 @@ enum
     EPOLLHUP    = 0x010,
     EPOLLRDHUP  = 0x2000, // since Linux 2.6.17
     EPOLLEXCLUSIVE = 1u << 28, // since Linux 4.5
+    EPOLLWAKEUP = 1u << 29,
     EPOLLONESHOT = 1u << 30,
     EPOLLET     = 1u << 31
 }
 
-/* Valid opcodes ( "op" parameter ) to issue to epoll_ctl().  */
+/**
+ * Valid opcodes ( "op" parameter ) to issue to epoll_ctl().
+ */
 enum
 {
-    EPOLL_CTL_ADD = 1, // Add a file descriptor to the interface.
-    EPOLL_CTL_DEL = 2, // Remove a file descriptor from the interface.
-    EPOLL_CTL_MOD = 3, // Change file descriptor epoll_event structure.
+    EPOLL_CTL_ADD = 1, /// Add a file descriptor to the interface.
+    EPOLL_CTL_DEL = 2, /// Remove a file descriptor from the interface.
+    EPOLL_CTL_MOD = 3, /// Change file descriptor epoll_event structure.
 }
 
 version (X86_Any)
@@ -142,7 +147,82 @@ union epoll_data_t
     ulong u64;
 }
 
+/**
+ * Creates an epoll instance.
+ *
+ * Params:
+ *   size = a hint specifying the number of file descriptors to be associated
+ *          with the new instance.  T
+ * Returns: an fd for the new instance. The fd returned by epoll_create() should
+ *          be closed with close().
+ * See_also: epoll_create1 (int flags)
+ */
 int epoll_create (int size);
+
+/* Same as epoll_create but with an FLAGS parameter.  The unused SIZE
+   parameter has been dropped.  */
+
+/**
+ * Creates an epoll instance.
+ *
+ * Params:
+ *   flags = a specified flag. If flags is 0, then, other than the fact that the
+ *           obsolete size argument is dropped, epoll_create1() is the same as
+ *           epoll_create().
+ * Returns: an fd for the new instance. The fd returned by epoll_create() should
+ *          be closed with close().
+ * See_also: epoll_create (int size)
+ */
 int epoll_create1 (int flags);
+
+/**
+ * Manipulate an epoll instance
+ *
+ * Params:
+ *   epfd = an epoll file descriptor instance
+ *   op = one of the EPOLL_CTL_* constants
+ *   fd = target file descriptor of the operation
+ *   event = describes which events the caller is interested in and any
+ *           associated user dat
+ * Returns: 0 in case of success, -1 in case of error ( the "errno" variable
+ *          will contain the specific error code )
+ */
 int epoll_ctl (int epfd, int op, int fd, epoll_event *event);
+
+
+/**
+ * Wait for events on an epoll instance.
+ *
+ *
+ * Params:
+ *   epfd = an epoll file descriptor instance
+ *   events = a buffer that will contain triggered events
+ *   maxevents = the maximum number of events to be returned ( usually size of
+ *               "events" )
+ *   timeout = specifies the maximum wait time in milliseconds (-1 == infinite)
+ *
+ * Returns: the number of triggered events returned in "events" buffer. Or -1 in
+ *          case of error with the "errno" variable set to the specific error
+ *          code.
+ */
 int epoll_wait (int epfd, epoll_event *events, int maxevents, int timeout);
+
+/**
+ * Wait for events on an epoll instance
+ *
+ *
+ * Params:
+ *   epfd = an epoll file descriptor instance
+ *   events = a buffer that will contain triggered events
+ *   maxevents = the maximum number of events to be returned ( usually size of
+ *               "events" )
+ *   timeout = specifies the maximum wait time in milliseconds (-1 == infinite)
+ *   ss = a signal set. May be specified as `null`, in which case epoll_pwait() is
+ *        equivalent to epoll_wait().
+ *
+ * Returns: the number of triggered events returned in "events" buffer. Or -1 in
+ *          case of error with the "errno" variable set to the specific error
+ *          code.
+ */
+int epoll_pwait (int epfd, epoll_event *events, int maxevents, int timeout,
+    const sigset_t *ss);