Differential D15778 Diff 45907 head/lib/libc/sys/kqueue.2

Changeset View

Standalone View

head/lib/libc/sys/kqueue.2

	Show All 18 Lines
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd June 22, 2017			.Dd July 27, 2018
	.Dt KQUEUE 2			.Dt KQUEUE 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm kqueue ,			.Nm kqueue ,
	.Nm kevent			.Nm kevent
	.Nd kernel event notification mechanism			.Nd kernel event notification mechanism
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	▲ Show 20 Lines • Show All 113 Lines • ▼ Show 20 Lines
	.Bd -literal			.Bd -literal
	struct kevent {			struct kevent {
	uintptr_t ident; /* identifier for this event */			uintptr_t ident; /* identifier for this event */
	short filter; /* filter for event */			short filter; /* filter for event */
	u_short flags; /* action flags for kqueue */			u_short flags; /* action flags for kqueue */
	u_int fflags; /* filter flag value */			u_int fflags; /* filter flag value */
	int64_t data; /* filter data value */			int64_t data; /* filter data value */
	void udata; / opaque user data identifier */			void udata; / opaque user data identifier */
	uint64_t ext[4]; /* extentions */			uint64_t ext[4]; /* extensions */
	};			};
	.Ed			.Ed
	.Pp			.Pp
	The fields of			The fields of
	.Fa struct kevent			.Fa struct kevent
	are:			are:
	.Bl -tag -width "Fa filter"			.Bl -tag -width "Fa filter"
	.It Fa ident			.It Fa ident
	▲ Show 20 Lines • Show All 184 Lines • ▼ Show 20 Lines
	.It Dv EVFILT_EMPTY			.It Dv EVFILT_EMPTY
	Takes a descriptor as the identifier, and returns whenever			Takes a descriptor as the identifier, and returns whenever
	there is no remaining data in the write buffer.			there is no remaining data in the write buffer.
	.It Dv EVFILT_AIO			.It Dv EVFILT_AIO
	Events for this filter are not registered with			Events for this filter are not registered with
	.Fn kevent			.Fn kevent
	directly but are registered via the			directly but are registered via the
	.Va aio_sigevent			.Va aio_sigevent
	member of an asychronous I/O request when it is scheduled via an asychronous I/O			member of an asynchronous I/O request when it is scheduled via an
	system call such as			asynchronous I/O system call such as
	.Fn aio_read .			.Fn aio_read .
	The filter returns under the same conditions as			The filter returns under the same conditions as
	.Fn aio_error .			.Fn aio_error .
	For more details on this filter see			For more details on this filter see
	.Xr sigevent 3 and			.Xr sigevent 3 and
	.Xr aio 4 .			.Xr aio 4 .
	.It Dv EVFILT_VNODE			.It Dv 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
	▲ Show 20 Lines • Show All 128 Lines • ▼ Show 20 Lines
	.Fn sigaction			.Fn sigaction
	facilities, and has a lower precedence.			facilities, and has a lower precedence.
	The filter will record			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
	been marked as			been marked as
	.Dv SIG_IGN ,			.Dv SIG_IGN ,
	except for the			except for the
	.Dv SIGCHLD			.Dv SIGCHLD
	signal, which, if ignored, won't be recorded by the filter.			signal, which, if ignored, will not be recorded by the filter.
	Event notification happens after normal			Event notification happens after normal
	signal delivery processing.			signal delivery processing.
	.Va data			.Va data
	returns the number of times the signal has occurred since the last call to			returns the number of times the signal has occurred since the last call to
	.Fn kevent .			.Fn kevent .
	This filter automatically sets the			This filter automatically sets the
	.Dv EV_CLEAR			.Dv EV_CLEAR
	flag internally.			flag internally.
	Show All 40 Lines
	.Pp			.Pp
	If			If
	.Va fflags			.Va fflags
	is not set, the default is milliseconds.			is not set, the default is milliseconds.
	On return,			On return,
	.Va fflags			.Va fflags
	contains the events which triggered the filter.			contains the events which triggered the filter.
	.Pp			.Pp
				If an existing timer is re-added, the existing timer will be
				effectively canceled (throwing away any undelivered record of previous
				timer expiration) and re-started using the new parameters contained in
				.Va data
				and
				.Va fflags .
				.Pp
	There is a system wide limit on the number of timers			There is a system wide limit on the number of timers
	which is controlled by the			which is controlled by the
	.Va kern.kq_calloutmax			.Va kern.kq_calloutmax
	sysctl.			sysctl.
	.It Dv EVFILT_USER			.It Dv EVFILT_USER
	Establishes a user event identified by			Establishes a user event identified by
	.Va ident			.Va ident
	which is not associated with any kernel mechanism but is triggered by			which is not associated with any kernel mechanism but is triggered by
	Show All 30 Lines
	.Pp			.Pp
	On return,			On return,
	.Va fflags			.Va fflags
	contains the users defined flags in the lower 24 bits.			contains the users defined flags in the lower 24 bits.
	.El			.El
	.Sh CANCELLATION BEHAVIOUR			.Sh CANCELLATION BEHAVIOUR
	If			If
	.Fa nevents			.Fa nevents
	is non-zero, i.e. the function is potentially blocking, the call			is non-zero, i.e., the function is potentially blocking, the call
	is a cancellation point.			is a cancellation point.
	Otherwise, i.e. if			Otherwise, i.e., if
	.Fa nevents			.Fa nevents
	is zero, the call is not cancellable.			is zero, the call is not cancellable.
	Cancellation can only occur before any changes are made to the kqueue,			Cancellation can only occur before any changes are made to the kqueue,
	or when the call was blocked and no changes to the queue were requested.			or when the call was blocked and no changes to the queue were requested.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	The			The
	.Fn kqueue			.Fn kqueue
	system call			system call
	▲ Show 20 Lines • Show All 159 Lines • ▼ Show 20 Lines
	system and this manual page were written by			system and this manual page were written by
	.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org .			.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org .
	.Sh BUGS			.Sh BUGS
	The			The
	.Fa timeout			.Fa timeout
	value is limited to 24 hours; longer timeouts will be silently			value is limited to 24 hours; longer timeouts will be silently
	reinterpreted as 24 hours.			reinterpreted as 24 hours.
	.Pp			.Pp
	In versions older than			In versions older than
	.Fx 12.0 ,			.Fx 12.0 ,
	.In sys/event.h			.In sys/event.h
	failed to parse without including			failed to parse without including
	.In sys/types.h			.In sys/types.h
	manually.			manually.