Drop trailing whitespace, and some mdoc fixes and improvements.
This commit is contained in:
wiz
parent
5dbdce59f0
commit
968f39c890
@ -1,4 +1,4 @@
|
||||
.\" $NetBSD: kqueue.2,v 1.5 2002/09/24 11:38:16 jdolecek Exp $
|
||||
.\" $NetBSD: kqueue.2,v 1.6 2002/09/25 00:55:16 wiz Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2000 Jonathan Lemon
|
||||
.\" All rights reserved.
|
||||
@ -42,9 +42,9 @@
|
||||
.Sh LIBRARY
|
||||
.Lb libc
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/types.h>
|
||||
.Fd #include <sys/event.h>
|
||||
.Fd #include <sys/time.h>
|
||||
.Fd #include \*[Lt]sys/types.h\*[Gt]
|
||||
.Fd #include \*[Lt]sys/event.h\*[Gt]
|
||||
.Fd #include \*[Lt]sys/time.h\*[Gt]
|
||||
.Ft int
|
||||
.Fn kqueue "void"
|
||||
.Ft int
|
||||
@ -68,7 +68,7 @@ The filter is also run when the user attempts to retrieve the kevent
|
||||
from the kqueue.
|
||||
If the filter indicates that the condition that triggered
|
||||
the event no longer holds, the kevent is removed from the kqueue and
|
||||
is not returned.
|
||||
is not returned.
|
||||
.Pp
|
||||
Multiple events which trigger the filter do not result in multiple
|
||||
kevents being placed on the kqueue; instead, the filter will aggregate
|
||||
@ -95,34 +95,40 @@ is used to register events with the queue, and return any pending
|
||||
events to the user.
|
||||
.Fa changelist
|
||||
is a pointer to an array of
|
||||
.Va kevent
|
||||
.Va kevent
|
||||
structures, as defined in
|
||||
.Aq Pa sys/event.h .
|
||||
All changes contained in the
|
||||
All changes contained in the
|
||||
.Fa changelist
|
||||
are applied before any pending events are read from the queue.
|
||||
.Fa nchanges
|
||||
gives the size of
|
||||
.Fa changelist .
|
||||
.Fa eventlist
|
||||
is a pointer to an array of kevent structures.
|
||||
is a pointer to an array of kevent structures.
|
||||
.Fa nevents
|
||||
determines the size of
|
||||
.Fa eventlist .
|
||||
If
|
||||
.Fa timeout
|
||||
is a non-NULL pointer, it specifies a maximum interval to wait
|
||||
is a
|
||||
.No non- Ns Dv NULL
|
||||
pointer, it specifies a maximum interval to wait
|
||||
for an event, which will be interpreted as a struct timespec. If
|
||||
.Fa timeout
|
||||
is a NULL pointer,
|
||||
is a
|
||||
.Dv NULL
|
||||
pointer,
|
||||
.Fn kevent
|
||||
waits indefinitely. To effect a poll, the
|
||||
.Fa timeout
|
||||
argument should be non-NULL, pointing to a zero-valued
|
||||
argument should be
|
||||
.No non- Ns Dv NULL ,
|
||||
pointing to a zero-valued
|
||||
.Va timespec
|
||||
structure. The same array may be used for the
|
||||
.Fa changelist
|
||||
and
|
||||
and
|
||||
.Fa eventlist .
|
||||
.Pp
|
||||
.Fn EV_SET
|
||||
@ -160,7 +166,7 @@ Actions to perform on the event.
|
||||
.It fflags
|
||||
Filter-specific flags.
|
||||
.It data
|
||||
Filter-specific data value.
|
||||
Filter-specific data value.
|
||||
.It udata
|
||||
Opaque user-defined value passed through the kernel unchanged.
|
||||
.El
|
||||
@ -183,8 +189,8 @@ Disable the event so
|
||||
.Fn kevent
|
||||
will not return it. The filter itself is not disabled.
|
||||
.It EV_DELETE
|
||||
Removes the event from the kqueue. Events which are attached to
|
||||
file descriptors are automatically deleted on the last close of
|
||||
Removes the event from the kqueue. Events which are attached to
|
||||
file descriptors are automatically deleted on the last close of
|
||||
the descriptor.
|
||||
.It EV_ONESHOT
|
||||
Causes the event to return only the first occurrence of the filter
|
||||
@ -202,19 +208,17 @@ See
|
||||
.Sx RETURN VALUES
|
||||
below.
|
||||
.El
|
||||
.Pp
|
||||
.Ss Filters
|
||||
.Pp
|
||||
Filters are identified by a number.
|
||||
There are two types of filters; pre-defined filters which
|
||||
are described below, and third-party filters that may be added with
|
||||
.Xr kfilter_register 2
|
||||
.Xr kfilter_register 2
|
||||
by kernel sub-systems, third-party device drivers, or loadable
|
||||
kernel modules.
|
||||
.Pp
|
||||
As a third-party filter is referenced by a well-known name instead
|
||||
of a statically assigned number, two
|
||||
.Xr ioctl 2 s
|
||||
.Xr ioctl 2 Ns s
|
||||
are supported on the file descriptor returned by
|
||||
.Fn kqueue
|
||||
to map a filter name to a filter number, and vice-versa (passing
|
||||
@ -246,7 +250,7 @@ struct kfilter_mapping {
|
||||
};
|
||||
.Ed
|
||||
.Pp
|
||||
Arguments may be passed to and from the filter via the
|
||||
Arguments may be passed to and from the filter via the
|
||||
.Va fflags
|
||||
and
|
||||
.Va data
|
||||
@ -275,9 +279,9 @@ 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
|
||||
time the filter is added by setting the
|
||||
NOTE_LOWAT
|
||||
flag in
|
||||
.Va fflags ,
|
||||
and specifying the new low water mark in
|
||||
.Va data .
|
||||
@ -288,7 +292,7 @@ contains the number of bytes in the socket buffer.
|
||||
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
|
||||
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.
|
||||
@ -311,25 +315,25 @@ returning.
|
||||
.It EVFILT_WRITE
|
||||
Takes a descriptor as the identifier, and returns whenever
|
||||
it is possible to write to the descriptor. For sockets, pipes,
|
||||
fifos and ttys,
|
||||
fifos, and ttys,
|
||||
.Va data
|
||||
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
|
||||
For sockets, the low water mark and socket error handling is
|
||||
identical to the EVFILT_READ case.
|
||||
.It EVFILT_AIO
|
||||
This is not implemented in
|
||||
.Nx .
|
||||
.ig
|
||||
The sigevent portion of the AIO request is filled in, with
|
||||
.Va sigev_notify_kqueue
|
||||
.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
|
||||
containing the udata value, and
|
||||
.Va sigev_notify
|
||||
set to SIGEV_EVENT.
|
||||
When the aio_* function is called, the event will be registered
|
||||
@ -340,7 +344,7 @@ argument set to the
|
||||
returned by the aio_* function.
|
||||
The filter returns under the same conditions as aio_error.
|
||||
.Pp
|
||||
Alternatively, a kevent structure may be initialized, with
|
||||
Alternatively, a kevent structure may be initialized, with
|
||||
.Va ident
|
||||
containing the descriptor of the kqueue, and the
|
||||
address of the kevent structure placed in the
|
||||
@ -349,7 +353,7 @@ 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
|
||||
Takes a file descriptor as the identifier and the events to watch for in
|
||||
.Va fflags ,
|
||||
and returns when one or more of the requested events occurs on the descriptor.
|
||||
The events to monitor are:
|
||||
@ -368,7 +372,7 @@ 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
|
||||
Access to the file was revoked via
|
||||
.Xr revoke 2
|
||||
or the underlying fileystem was unmounted.
|
||||
.El
|
||||
@ -377,7 +381,7 @@ On return,
|
||||
.Va fflags
|
||||
contains the events which triggered the filter.
|
||||
.It EVFILT_PROC
|
||||
Takes the process ID to monitor as the identifier and the events to watch for
|
||||
Takes the process ID to monitor as the identifier and the events to watch for
|
||||
in
|
||||
.Va fflags ,
|
||||
and returns when the process performs one or more of the requested events.
|
||||
@ -390,7 +394,7 @@ The process has exited.
|
||||
The process has called
|
||||
.Fn fork .
|
||||
.It NOTE_EXEC
|
||||
The process has executed a new process via
|
||||
The process has executed a new process via
|
||||
.Xr execve 2
|
||||
or similar call.
|
||||
.It NOTE_TRACK
|
||||
@ -400,7 +404,7 @@ calls. The parent process will return with NOTE_TRACK set in the
|
||||
.Va fflags
|
||||
field, while the child process will return with NOTE_CHILD set in
|
||||
.Va fflags
|
||||
and the parent PID in
|
||||
and the parent PID in
|
||||
.Va data .
|
||||
.It NOTE_TRACKERR
|
||||
This flag is returned if the system was unable to attach an event to
|
||||
@ -415,7 +419,7 @@ Takes the signal number to monitor as the identifier and returns
|
||||
when the given signal is delivered to the current process.
|
||||
This coexists with the
|
||||
.Fn signal
|
||||
and
|
||||
and
|
||||
.Fn sigaction
|
||||
facilities, and has a lower precedence. The filter will record
|
||||
all attempts to deliver a signal to a process, even if the signal has
|
||||
@ -429,7 +433,7 @@ This filter automatically sets the EV_CLEAR flag internally.
|
||||
.Sh RETURN VALUES
|
||||
.Fn kqueue
|
||||
creates a new kernel event queue and returns a file descriptor.
|
||||
If there was an error creating the kernel event queue, a value of -1 is
|
||||
If there was an error creating the kernel event queue, a value of \-1 is
|
||||
returned and errno set.
|
||||
.Pp
|
||||
.Fn kevent
|
||||
@ -450,7 +454,7 @@ set in
|
||||
and the system error in
|
||||
.Va data .
|
||||
Otherwise,
|
||||
.Dv -1
|
||||
.Dv \-1
|
||||
will be returned, and
|
||||
.Dv errno
|
||||
will be set to indicate the error condition.
|
||||
@ -477,9 +481,9 @@ function fails if:
|
||||
.It Bq Er EACCES
|
||||
The process does not have permission to register a filter.
|
||||
.It Bq Er EFAULT
|
||||
There was an error reading or writing the
|
||||
There was an error reading or writing the
|
||||
.Va kevent
|
||||
structure.
|
||||
structure.
|
||||
.It Bq Er EBADF
|
||||
The specified descriptor is invalid.
|
||||
.It Bq Er EINTR
|
||||
@ -505,8 +509,8 @@ The specified process to attach to does not exist.
|
||||
.Xr sigaction 2 ,
|
||||
.Xr write 2 ,
|
||||
.Xr signal 3 ,
|
||||
.Xr kfilter_register 9 .
|
||||
.Xr knote 9 .
|
||||
.Xr kfilter_register 9 ,
|
||||
.Xr knote 9
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn kqueue
|
||||
@ -529,7 +533,7 @@ system and this manual page were written by
|
||||
port and manpage additions were done by
|
||||
.An Luke Mewburn Aq lukem@NetBSD.org ,
|
||||
.An Jason Thorpe Aq thorpej@NetBSD.org ,
|
||||
and
|
||||
and
|
||||
.An Jaromir Dolecek Aq jdolecek@NetBSD.org .
|
||||
.Sh BUGS
|
||||
It is currently not possible to watch a
|
||||
|
||||
Loading…
Reference in New Issue
Block a user