xnu-4570.51.1.tar.gz

[apple/xnu.git] / bsd / man / man2 / kqueue.2

diff --git a/bsd/man/man2/kqueue.2 b/bsd/man/man2/kqueue.2
index 5e8702457ef6385aa179de6e777ce56dcb2cbcbb..d1a5355422d8206b9ef2c23bc81d92587b34c645 100644 (file)
--- a/bsd/man/man2/kqueue.2
+++ b/bsd/man/man2/kqueue.2
@@ -1,5 +1,5 @@
 .\"
 .\"

-.\" Copyright (c) 2008-2015 Apple Inc.  All rights reserved.
+.\" Copyright (c) 2008-2016 Apple Inc.  All rights reserved.

 .\"
 .\" @APPLE_LICENSE_HEADER_START@
 .\" 
 .\"
 .\" @APPLE_LICENSE_HEADER_START@
 .\" 


@@ -435,6 +435,20 @@ field contains 1 on input, those devices will attach - but
 cannot be relied upon to provide an accurate count of bytes
 to be read on output.
 .El
 cannot be relied upon to provide an accurate count of bytes
 to be read on output.
 .El

+.It Dv EVFILT_EXCEPT
+Takes a descriptor as the identifier, and returns whenever one of the
+specified exceptional conditions has occurred on the descriptor. Conditions
+are specified in
+.Va fflags .
+Currently, this filter can be used to monitor the arrival of
+out-of-band data on a socket descriptor using the filter flag
+.Dv NOTE_OOB .
+.Pp
+If the read direction of the socket has shutdown, then the filter
+also sets EV_EOF in
+.Va flags ,
+and returns the socket error (if any) in
+.Va fflags .

 .It EVFILT_WRITE
 Takes a file descriptor as the identifier, and returns whenever
 it is possible to write to the descriptor.  For sockets, pipes
 .It EVFILT_WRITE
 Takes a file descriptor as the identifier, and returns whenever
 it is possible to write to the descriptor.  For sockets, pipes


@@ -501,6 +515,11 @@ The file referenced by the descriptor was renamed.
 Access to the file was revoked via
 .Xr revoke 2
 or the underlying fileystem was unmounted.
 Access to the file was revoked via
 .Xr revoke 2
 or the underlying fileystem was unmounted.

+.It NOTE_FUNLOCK
+The file was unlocked by calling
+.Xr flock 2
+or
+.Xr close 2

 .El
 .Pp
 On return,
 .El
 .Pp
 On return,


@@ -576,41 +595,65 @@ area provided to
 .Fn kevent_qos
 if there is enough space remaining there.
 .It EVFILT_TIMER
 .Fn kevent_qos
 if there is enough space remaining there.
 .It EVFILT_TIMER

-Establishes an interval timer with the data
-timer identified by
-.Va ident .
-When adding a timer,
+Establishes an interval timer identified by
+.Va ident
+where

 .Va data
 .Va data

-specifies the timeout period and
+specifies the timeout period (in milliseconds).
+.Pp

 .Va fflags
 .Va fflags

-can be set to one of the following:
-.Bl -tag -width NOTE_ABSOLUTE
+can include one of the following flags to specify a different unit:
+.Bl -tag -width NOTE_NSECONDS

 .It NOTE_SECONDS
 .It NOTE_SECONDS

-data is in seconds
+.Va data
+is in seconds

 .It NOTE_USECONDS
 .It NOTE_USECONDS

-data is in microseconds
+.Va data
+is in microseconds

 .It NOTE_NSECONDS
 .It NOTE_NSECONDS

-data is in nanoseconds
-.It NOTE_ABSOLUTE
-data is an absolute timeout
+.Va data
+is in nanoseconds
+.It NOTE_MACHTIME
+.Va data
+is in Mach absolute time units
+.El
+.Pp
+.Va fflags
+can also include
+.Dv NOTE_ABSOLUTE,
+which establishes an
+.Dv EV_ONESHOT
+timer with an absolute deadline instead of an interval.
+The absolute deadline is expressed in terms of
+.Xr gettimeofday 2 .
+With
+.Dv NOTE_MACHTIME,
+the deadline is expressed in terms of
+.Fn mach_absolute_time .
+.Pp
+The timer can be coalesced with other timers to save power. The following flags can be set in
+.Va fflags
+to modify this behavior:
+.Bl -tag -width NOTE_BACKGROUND

 .It NOTE_CRITICAL
 .It NOTE_CRITICAL

-system makes a best effort to fire this timer as scheduled.
+override default power-saving techniques to more strictly respect the leeway value

 .It NOTE_BACKGROUND
 .It NOTE_BACKGROUND

-system has extra leeway to coalesce this timer.
+apply more power-saving techniques to coalesce this timer with other timers

 .It NOTE_LEEWAY
 .It NOTE_LEEWAY

-ext[1] holds user-supplied slop in deadline for timer coalescing.
+.Va ext[1]
+holds user-supplied slop in deadline for timer coalescing.

 .El
 .Pp
 .El
 .Pp

-If fflags is not set, the default is milliseconds. The timer will be periodic unless EV_ONESHOT is specified.
+The timer will be periodic unless
+.Dv EV_ONESHOT
+is specified.

 On return,
 .Va data
 On return,
 .Va data

-contains the number of times the timeout has expired since the last call to
-.Fn kevent , 
-.Fn kevent64
-or
-.Fn kevent_qos .
-
-This filter automatically sets the EV_CLEAR flag internally.
+contains the number of times the timeout has expired since the last arming or last delivery of the timer event.
+.Pp
+This filter automatically sets the
+.Dv EV_CLEAR
+flag.

 .El
 .Pp
 ----
 .El
 .Pp
 ----