Document various changes to kq:
- new EV_SET macro, - NOTE_LOWAT option for low water marks on read/write filters, - NOTE_REVOKE for filesystem unmounting (and revoke() calls) - improved API for EVFILT_AIO
This commit is contained in:
parent
19391949fb
commit
5d1c9c5606
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=73060
@ -41,6 +41,7 @@
|
||||
.Fn kqueue "void"
|
||||
.Ft int
|
||||
.Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout"
|
||||
.Fn EV_SET "&kev" ident filter flags fflags data udata
|
||||
.Sh DESCRIPTION
|
||||
.Fn kqueue
|
||||
provides a generic method of notifying the user when an event
|
||||
@ -114,6 +115,10 @@ structure. The same array may be used for the
|
||||
and
|
||||
.Fa eventlist .
|
||||
.Pp
|
||||
.Fn EV_SET
|
||||
is a macro which is provided for ease of initializing a
|
||||
kevent structure.
|
||||
.Pp
|
||||
The
|
||||
.Va kevent
|
||||
structure is defined as:
|
||||
@ -199,6 +204,7 @@ Takes a descriptor as the identifier, and returns whenever
|
||||
there is data available to read.
|
||||
The behavior of the filter is slightly different depending
|
||||
on the descriptor type.
|
||||
.Pp
|
||||
.Bl -tag -width 2n
|
||||
.It Sockets
|
||||
Sockets which have previously been passed to
|
||||
@ -208,13 +214,25 @@ return when there is an incoming connection pending.
|
||||
contains the size of the listen backlog.
|
||||
.Pp
|
||||
Other socket descriptors return when there is data to be read,
|
||||
subject to the SO_RCVLOWAT value of the socket buffer.
|
||||
subject to the
|
||||
.Dv SO_RCVLOWAT
|
||||
value of the socket buffer.
|
||||
This may be overridden with a per-filter low water mark at the
|
||||
time the filter is added by setting the
|
||||
NOTE_LOWAT
|
||||
flag in
|
||||
.Va fflags ,
|
||||
and specifying the new low water mark in
|
||||
.Va data .
|
||||
On return,
|
||||
.Va data
|
||||
contains the number of bytes in the socket buffer.
|
||||
.Pp
|
||||
If the read direction of the socket has shutdown, then the filter
|
||||
also sets EV_EOF in
|
||||
.Va flags .
|
||||
.Va flags ,
|
||||
and returns the socket error (if any) in
|
||||
.Va fflags .
|
||||
It is possible for EOF to be returned (indicating the connection is gone)
|
||||
while there is still data pending in the socket buffer.
|
||||
.It Vnodes
|
||||
@ -242,21 +260,33 @@ will contain the amount of space remaining in the write buffer.
|
||||
The filter will set EV_EOF when the reader disconnects, and for
|
||||
the fifo case, this may be cleared by use of EV_CLEAR.
|
||||
Note that this filter is not supported for vnodes.
|
||||
.Pp
|
||||
For sockets, the low water mark and socket error handling is
|
||||
identical to the EVFILT_READ case.
|
||||
.It EVFILT_AIO
|
||||
A kevent structure is initialized, with
|
||||
.Va ident
|
||||
containing the descriptor of the kqueue that the event should be
|
||||
attached to. The address of the kevent structure is then placed in the
|
||||
.Va aio_lio_opcode
|
||||
field of the AIO request, and the aio_* function is then called.
|
||||
The event will be registered with the specified kqueue, and the
|
||||
The sigevent portion of the AIO request is filled in, with
|
||||
.Va sigev_notify_kqueue
|
||||
containing the descriptor of the kqueue that the event should
|
||||
be attached to,
|
||||
.Va sigev_value
|
||||
containing the udata value, and
|
||||
.Va sigev_notify
|
||||
set to SIGEV_EVENT.
|
||||
When the aio_* function is called, the event will be registered
|
||||
with the specified kqueue, and the
|
||||
.Va ident
|
||||
argument set to the
|
||||
.Fa struct aiocb
|
||||
returned by the aio_* function.
|
||||
The filter returns under the same conditions as aio_error.
|
||||
.Pp
|
||||
NOTE: this interface is unstable and subject to change.
|
||||
Alternatively, a kevent structure may be initialized, with
|
||||
.Va ident
|
||||
containing the descriptor of the the kqueue, and the
|
||||
address of the kevent structure placed in the
|
||||
.Va aio_lio_opcode
|
||||
field of the AIO request. However, this approach will not work on
|
||||
architectures with 64-bit pointers, and should be considered depreciated.
|
||||
.It EVFILT_VNODE
|
||||
Takes a file descriptor as the identifier and the events to watch for in
|
||||
.Va fflags ,
|
||||
@ -276,6 +306,10 @@ The file referenced by the descriptor had its attributes changed.
|
||||
The link count on the file changed.
|
||||
.It NOTE_RENAME
|
||||
The file referenced by the descriptor was renamed.
|
||||
.It NOTE_REVOKE
|
||||
Access to the file was revoked via
|
||||
.Xr revoke 2
|
||||
or the underlying fileystem was unmounted.
|
||||
.El
|
||||
.Pp
|
||||
On return,
|
||||
|
Loading…
Reference in New Issue
Block a user