xnu-6153.121.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 6f1ce36ef4958953db0714bbc7491a48eba2516b..be1a477c7a8835891ec590b064e39cc0a911da17 100644 (file)
--- a/bsd/man/man2/kqueue.2
+++ b/bsd/man/man2/kqueue.2
@@ -145,6 +145,7 @@ The
 argument
 gives the size of
 .Fa changelist .
+.Pp
 The
 .Fa eventlist
 argument
@@ -158,11 +159,9 @@ The
 .Fa nevents
 argument determines the size of
 .Fa eventlist .
-If the KEVENT_FLAG_STACK_EVENTS flag is provided on the system call,
-the eventlist array is filled in in stack order (starting in the
-highest available index) instead of typical array order.
+.Pp
 The
-.Fa out_data
+.Fa data_out
 argument provides space for extra out data provided by specific filters.
 The
 .Fa data_available
@@ -170,6 +169,7 @@ argument's contents specified the space available in the data pool on input,
 and contains the amount still remaining on output.
 If the KEVENT_FLAG_STACK_DATA flag is specified on the system call,
 the data is allocated from the pool in stack order instead of typical heap order. 
+.Pp
 If
 .Fa timeout
 is a non-NULL pointer, it specifies a maximum interval to wait
@@ -595,41 +595,65 @@ area provided to
 .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
-specifies the timeout period and
+specifies the timeout period (in milliseconds).
+.Pp
 .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
-data is in seconds
+.Va data
+is in seconds
 .It NOTE_USECONDS
-data is in microseconds
+.Va data
+is in microseconds
 .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
-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
-system has extra leeway to coalesce this timer.
+apply more power-saving techniques to coalesce this timer with other timers
 .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
-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
-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
 ----