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