xnu-4903.241.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 201ad5de36ab3c0506a04b20322e423a0d3dfe7b..d1a5355422d8206b9ef2c23bc81d92587b34c645 100644 (file)
--- a/bsd/man/man2/kqueue.2
+++ b/bsd/man/man2/kqueue.2
@@ -1,5 +1,5 @@
 .\"
 .\"

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

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


@@ -53,8 +53,9 @@
 .Sh NAME
 .Nm kqueue ,
 .Nm kevent ,
 .Sh NAME
 .Nm kqueue ,
 .Nm kevent ,

-and

 .Nm kevent64
 .Nm kevent64

+and
+.Nm kevent_qos

 .Nd kernel event notification mechanism
 .Sh LIBRARY
 .Lb libc
 .Nd kernel event notification mechanism
 .Sh LIBRARY
 .Lb libc


@@ -68,21 +69,28 @@ and
 .Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout"
 .Ft int
 .Fn kevent64 "int kq" "const struct kevent64_s *changelist" "int nchanges" "struct kevent64_s *eventlist" "int nevents" "unsigned int flags" "const struct timespec *timeout"
 .Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout"
 .Ft int
 .Fn kevent64 "int kq" "const struct kevent64_s *changelist" "int nchanges" "struct kevent64_s *eventlist" "int nevents" "unsigned int flags" "const struct timespec *timeout"

+.Ft int
+.Fn kevent_qos "int kq" "const struct kevent_qos_s *changelist" "int nchanges" "struct kevent_qos_s *eventlist" "int nevents" "void *data_out" "size_t *data_available" "unsigned int flags"

 .Fn EV_SET "&kev" ident filter flags fflags data udata
 .Fn EV_SET64 "&kev" ident filter flags fflags data udata "ext[0]" "ext[1]"
 .Fn EV_SET "&kev" ident filter flags fflags data udata
 .Fn EV_SET64 "&kev" ident filter flags fflags data udata "ext[0]" "ext[1]"

+.Fn EV_SET_QOS "&kev" ident filter flags qos udata fflags xflags data "ext[0]" "ext[1]" "ext[2]" "ext[3]"

 .Sh DESCRIPTION
 The
 .Fn kqueue
 .Sh DESCRIPTION
 The
 .Fn kqueue

-system call
+system call allocates a kqueue file descriptor.  This file descriptor

 provides a generic method of notifying the user when a kernel
 event (kevent) happens or a condition holds, based on the results
 of small pieces of kernel code termed filters.
 provides a generic method of notifying the user when a kernel
 event (kevent) happens or a condition holds, based on the results
 of small pieces of kernel code termed filters.

-A kevent is identified by an (ident, filter) pair and specifies
-the interesting conditions to be notified about for that pair. 
-An (ident, filter) pair can only appear once in a given kqueue.
-Subsequent attempts to register the same pair for a given kqueue
+.Pp
+A kevent is identified by an (ident, filter, and optional udata value) 
+tuple.  It specifies the interesting conditions to be notified about
+for that tuple. An (ident, filter, and optional udata value) tuple can
+only appear once in a given kqueue.
+Subsequent attempts to register the same tuple for a given kqueue

 will result in the replacement of the conditions being watched,
 not an addition.
 will result in the replacement of the conditions being watched,
 not an addition.

+Whether the udata value is considered as part of the tuple is controlled
+by the EV_UDATA_SPECIFIC flag on the kevent.

 .Pp
 The filter identified in a kevent is executed upon the initial
 registration of that event in order to detect whether a preexisting
 .Pp
 The filter identified in a kevent is executed upon the initial
 registration of that event in order to detect whether a preexisting


@@ -112,9 +120,10 @@ The queue is not inherited by a child created with
 .Xr fork 2 .
 .Pp
 The
 .Xr fork 2 .
 .Pp
 The

-.Fn kevent
-and
+.Fn kevent,

 .Fn kevent64
 .Fn kevent64

+and
+.Fn kevent_qos

 system calls
 are used to register events with the queue, and return any pending
 events to the user.
 system calls
 are used to register events with the queue, and return any pending
 events to the user.


@@ -122,9 +131,10 @@ The
 .Fa changelist
 argument
 is a pointer to an array of
 .Fa changelist
 argument
 is a pointer to an array of

-.Va kevent
-or
+.Va kevent,

 .Va kevent64_s
 .Va kevent64_s

+or
+.Va kevent_qos_s

 structures, as defined in
 .Aq Pa sys/event.h .
 All changes contained in the
 structures, as defined in
 .Aq Pa sys/event.h .
 All changes contained in the


@@ -138,16 +148,28 @@ gives the size of
 The
 .Fa eventlist
 argument
 The
 .Fa eventlist
 argument

-is a pointer to an array of 
-.Va kevent
-or
+is a pointer to an array of out
+.Va kevent,

 .Va kevent64_s 
 .Va kevent64_s 

+or
+.Va kevent_qos_s 

 structures.
 The
 .Fa nevents
 structures.
 The
 .Fa nevents

-argument
-determines the size of
+argument determines the size of

 .Fa eventlist .
 .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.
+The
+.Fa out_data
+argument provides space for extra out data provided by specific filters.
+The
+.Fa data_available
+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. 

 If
 .Fa timeout
 is a non-NULL pointer, it specifies a maximum interval to wait
 If
 .Fa timeout
 is a non-NULL pointer, it specifies a maximum interval to wait


@@ -158,6 +180,13 @@ is a NULL pointer, both
 and
 .Fn kevent64
 wait indefinitely.  To effect a poll, the
 and
 .Fn kevent64
 wait indefinitely.  To effect a poll, the

+.Fa flags
+argument to
+.Fn kevent64
+or
+.Fn kevent_qos
+can include the KEVENT_FLAG_IMMEDIATE value to indicate an
+immediate timeout.  Alternatively, the

 .Fa timeout
 argument should be non-NULL, pointing to a zero-valued
 .Va timespec
 .Fa timeout
 argument should be non-NULL, pointing to a zero-valued
 .Va timespec


@@ -174,12 +203,17 @@ structure. Similarly,
 .Fn EV_SET64 
 initializes a
 .Va kevent64_s
 .Fn EV_SET64 
 initializes a
 .Va kevent64_s

+structure and
+.Fn EV_SET_QOS
+initializes a
+.Va kevent_qos_s

 structure.
 .Pp
 The
 structure.
 .Pp
 The

-.Va kevent
-and
+.Va kevent,

 .Va kevent64_s
 .Va kevent64_s

+and
+.Va kevent_qos_s

 structures are defined as:
 .Bd -literal
 struct kevent {
 structures are defined as:
 .Bd -literal
 struct kevent {


@@ -191,7 +225,6 @@ struct kevent {
        void            *udata;         /* opaque user data identifier */
 };
 
        void            *udata;         /* opaque user data identifier */
 };
 

-

 struct kevent64_s {
         uint64_t        ident;          /* identifier for this event */
        int16_t         filter;         /* filter for event */
 struct kevent64_s {
         uint64_t        ident;          /* identifier for this event */
        int16_t         filter;         /* filter for event */


@@ -201,18 +234,31 @@ struct kevent64_s {
        uint64_t        udata;          /* opaque user data identifier */
        uint64_t        ext[2];         /* filter-specific extensions */
 };
        uint64_t        udata;          /* opaque user data identifier */
        uint64_t        ext[2];         /* filter-specific extensions */
 };

+
+struct kevent_qos_s {
+        uint64_t        ident;          /* identifier for this event */
+       int16_t         filter;         /* filter for event */
+       uint16_t        flags;          /* general flags */
+       uint32_t        qos;            /* quality of service when servicing event */
+       uint64_t        udata;          /* opaque user data identifier */
+       uint32_t        fflags;         /* filter-specific flags */
+       uint32_t        xflags;         /* extra filter-specific flags */
+       int64_t         data;           /* filter-specific data */
+       uint64_t        ext[4];         /* filter-specific extensions */
+};

 .Ed
 .Pp
 ----
 .Pp
 The fields of
 .Ed
 .Pp
 ----
 .Pp
 The fields of

-.Fa struct kevent
-and
+.Fa struct kevent,

 .Fa struct kevent64_s
 .Fa struct kevent64_s

+and
+.Fa struct kevent_qos_s

 are:
 .Bl -tag -width XXXfilter
 .It ident
 are:
 .Bl -tag -width XXXfilter
 .It ident

-Value used to identify this event.
+Value used to identify the source of the event.

 The exact interpretation is determined by the attached filter,
 but often is a file descriptor.
 .It filter
 The exact interpretation is determined by the attached filter,
 but often is a file descriptor.
 .It filter


@@ -225,7 +271,8 @@ Filter-specific flags.
 .It data
 Filter-specific data value.
 .It udata
 .It data
 Filter-specific data value.
 .It udata

-Opaque user-defined value passed through the kernel unchanged.
+Opaque user-defined value passed through the kernel unchanged. It can
+optionally be part of the uniquing decision of the kevent system

 .El
 .Pp
 In addition,
 .El
 .Pp
 In addition,


@@ -237,6 +284,16 @@ This field stores extensions for the event's filter. What type of extension depe
 what type of filter is being used.
 .El
 .Pp
 what type of filter is being used.
 .El
 .Pp

+In addition,
+.Fa struct kevent_qos_s
+contains:
+.Bl -tag -width XXXfilter
+.It xflags
+Extra filter-specific flags.
+.It ext[4]
+The QoS variant provides twice as many extension values for filter-specific uses.
+.El
+.Pp

 ----
 .Pp
 The
 ----
 .Pp
 The


@@ -250,15 +307,17 @@ in a duplicate entry.  Adding an event automatically enables it,
 unless overridden by the EV_DISABLE flag.
 .It EV_ENABLE
 Permit
 unless overridden by the EV_DISABLE flag.
 .It EV_ENABLE
 Permit

-.Fn kevent
-and
+.Fn kevent,

 .Fn kevent64
 .Fn kevent64

+and
+.Fn kevent_qos

 to return the event if it is triggered.
 .It EV_DISABLE
 Disable the event so
 to return the event if it is triggered.
 .It EV_DISABLE
 Disable the event so

-.Fn kevent
-and
+.Fn kevent,

 .Fn kevent64
 .Fn kevent64

+and
+.Fn kevent_qos

 will not return it.  The filter itself is not disabled.
 .It EV_DELETE
 Removes the event from the kqueue.  Events which are attached to
 will not return it.  The filter itself is not disabled.
 .It EV_DELETE
 Removes the event from the kqueue.  Events which are attached to


@@ -281,6 +340,9 @@ instead of the current state.  Note that some filters may automatically
 set this flag internally.
 .It EV_EOF
 Filters may set this flag to indicate filter-specific EOF condition.
 set this flag internally.
 .It EV_EOF
 Filters may set this flag to indicate filter-specific EOF condition.

+.It EV_OOBAND
+Read filter on socket may set this flag to indicate the presence of out of
+band data on the descriptor.

 .It EV_ERROR
 See
 .Sx RETURN VALUES
 .It EV_ERROR
 See
 .Sx RETURN VALUES


@@ -291,13 +353,15 @@ below.
 .Pp
 The predefined system filters are listed below.
 Arguments may be passed to and from the filter via the
 .Pp
 The predefined system filters are listed below.
 Arguments may be passed to and from the filter via the

+.Va data,

 .Va fflags
 .Va fflags

-and
-.Va data
+and optionally
+.Va xflags

 fields in the
 fields in the

-.Va kevent
-or
+.Va kevent,

 .Va kevent64_s
 .Va kevent64_s

+or
+.Va kevent_qos_s

 structure.
 .Bl -tag -width EVFILT_MACHPORT
 .It EVFILT_READ
 structure.
 .Bl -tag -width EVFILT_MACHPORT
 .It EVFILT_READ


@@ -325,10 +389,18 @@ flag in
 .Va fflags ,
 and specifying the new low water mark in
 .Va data .
 .Va fflags ,
 and specifying the new low water mark in
 .Va data .

+The derived per filter low water mark value is, however, bounded
+by socket receive buffer's high and low water mark values.

 On return,
 .Va data
 contains the number of bytes of protocol data available to read.
 .Pp
 On return,
 .Va data
 contains the number of bytes of protocol data available to read.
 .Pp

+The presence of EV_OOBAND in
+.Va flags ,
+indicates the presence of out of band data on the socket
+.Va data
+equal to the potential number of OOB bytes availble to read.
+.Pp

 If the read direction of the socket has shutdown, then the filter
 also sets EV_EOF in
 .Va flags ,
 If the read direction of the socket has shutdown, then the filter
 also sets EV_EOF in
 .Va flags ,


@@ -342,7 +414,7 @@ Returns when the file pointer is not at the end of file.
 contains the offset from current position to end of file,
 and may be negative.
 .It "Fifos, Pipes"
 contains the offset from current position to end of file,
 and may be negative.
 .It "Fifos, Pipes"

-Returns when the there is data to read;
+Returns when there is data to read;

 .Va data
 contains the number of bytes available.
 .Pp
 .Va data
 contains the number of bytes available.
 .Pp


@@ -351,7 +423,32 @@ When the last writer disconnects, the filter will set EV_EOF in
 This may be cleared by passing in EV_CLEAR, at which point the
 filter will resume waiting for data to become available before
 returning.
 This may be cleared by passing in EV_CLEAR, at which point the
 filter will resume waiting for data to become available before
 returning.

+.It "Device nodes"
+Returns when there is data to read from the device;
+.Va data
+contains the number of bytes available.  If the device does
+not support returning number of bytes, it will not allow the
+filter to be attached.  However, if the NOTE_LOWAT flag is
+specified and the
+.Va data
+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
 .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


@@ -418,11 +515,17 @@ 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,
 .Va fflags
 .El
 .Pp
 On return,
 .Va fflags

-contains the events which triggered the filter.
+contains the filter-specific flags which are associated with
+the triggered events seen by this filter.

 .It EVFILT_PROC
 Takes the process ID to monitor as the identifier and the events to watch for
 in
 .It EVFILT_PROC
 Takes the process ID to monitor as the identifier and the events to watch for
 in


@@ -475,46 +578,82 @@ This filter automatically sets the EV_CLEAR flag internally.
 .It EVFILT_MACHPORT
 Takes the name of a mach port, or port set, in 
 .Va ident
 .It EVFILT_MACHPORT
 Takes the name of a mach port, or port set, in 
 .Va ident

-and waits until a message is received on the port or port set. When a message 
-is recieved, the size of the message is returned in 
-.Va data 
-and if
+and waits until a message is enqueued on the port or port set. When a message 
+is detected, but not directly received by the kevent call, the name of the
+specific port where the message is enqueued is returned in
+.Va data .
+If

 .Va fflags 
 .Va fflags 

-is set to MACH_RCV_MSG, a pointer to the message is returned in ext[0].
+contains MACH_RCV_MSG, the ext[0] and ext[1] flags are assumed to contain
+a pointer to the buffer where the message is to be received and the size
+of the receive buffer, respectively.  If MACH_RCV_MSG is specifed, yet the
+buffer size in ext[1] is zero, The space for the buffer may be carved out
+of the
+.Va
+data_out
+area provided to
+.Fn kevent_qos
+if there is enough space remaining there.

 .It EVFILT_TIMER
 .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 
-or
-.Fn kevent64 .
-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
 ----


@@ -545,9 +684,10 @@ If there was an error creating the kernel event queue, a value of -1 is
 returned and errno set.
 .Pp
 The
 returned and errno set.
 .Pp
 The

-.Fn kevent
-and
+.Fn kevent ,

 .Fn kevent64
 .Fn kevent64

+and
+.Fn kevent_qos

 system calls
 return the number of events placed in the
 .Fa eventlist ,
 system calls
 return the number of events placed in the
 .Fa eventlist ,


@@ -571,9 +711,10 @@ will be returned, and
 .Dv errno
 will be set to indicate the error condition.
 If the time limit expires, then
 .Dv errno
 will be set to indicate the error condition.
 If the time limit expires, then

-.Fn kevent
-and
+.Fn kevent ,

 .Fn kevent64
 .Fn kevent64

+and
+.Fn kevent_qos

 return 0.
 .Sh ERRORS
 The
 return 0.
 .Sh ERRORS
 The