Page MenuHomeFreeBSD
Differential D48203

kqueue.2: Editorial pass
ClosedPublic
Actions

Authored by jhb on Dec 26 2024, 8:12 PM.
Tags
None
Referenced Files
Unknown Object (File)
Mon, Mar 3, 7:03 PM
Unknown Object (File)
Feb 14 2025, 8:11 PM
Unknown Object (File)
Feb 4 2025, 3:02 AM
Unknown Object (File)
Feb 3 2025, 2:37 AM
Unknown Object (File)
Feb 2 2025, 11:39 PM
Unknown Object (File)
Jan 26 2025, 8:08 AM
Unknown Object (File)
Jan 26 2025, 7:25 AM
Unknown Object (File)
Jan 14 2025, 3:51 AM
View All 19 Files
Subscribers
imp
ziaee

Details

Reviewers
emaste
Commits
rG8e8058b7373b: kqueue.2: Editorial pass
rG9b1585384d53: kqueue.2: Editorial pass
Summary
  • Use consistent language to describe user values unchanged by the kernel.
  • Replace passive language with active in a few places.
  • Add a history note for kqueuex().
  • Various wording and markup tweaks.

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Skipped
Unit
Tests Skipped
Build Status
Buildable 61406
Build 58290: arc lint + arc unit

Event Timeline

jhb created this revision.Dec 26 2024, 8:12 PM
Herald added a subscriber: imp. · View Herald TranscriptDec 26 2024, 8:12 PM
jhb requested review of this revision.Dec 26 2024, 8:12 PM
Harbormaster completed remote builds in B61336: Diff 148406.Dec 26 2024, 8:12 PM
emaste accepted this revision.Dec 28 2024, 5:19 PM

OK, one little note.

lib/libsys/kqueue.2
115–116

The "also" here seems somewhat out of place to me for some reason but I'm not quite sure why. Maybe "Also, for compatibility with NetBSD the..." or "The kqueue1 function is also provided, for compatibility with NetBSD. It accepts..."

This revision is now accepted and ready to land.Dec 28 2024, 5:19 PM
jhb updated this revision to Diff 148553.Dec 30 2024, 3:51 PM

Tweak kqueue1 language

This revision now requires review to proceed.Dec 30 2024, 3:51 PM
Harbormaster completed remote builds in B61406: Diff 148553.Dec 30 2024, 3:51 PM
emaste accepted this revision.Dec 30 2024, 4:22 PM
This revision is now accepted and ready to land.Dec 30 2024, 4:22 PM
Closed by commit rG9b1585384d53: kqueue.2: Editorial pass (authored by jhb). · Explain WhyDec 30 2024, 7:10 PM
This revision was automatically updated to reflect the committed changes.
jhb added a commit: rG9b1585384d53: kqueue.2: Editorial pass.
jhb added a commit: rG8e8058b7373b: kqueue.2: Editorial pass.Mon, Mar 3, 4:57 PM
Herald added a subscriber: ziaee. · View Herald TranscriptMon, Mar 3, 4:57 PM

Revision Contents
Changeset List

PathSize
lib/
libsys/
1 line
65 lines

Diff 148553

View Options

lib/libsys/Makefile.sys

Show First 20 Lines • Show All 447 Lines • ▼ Show 20 Lines
MLINKS+=getuid.2 geteuid.2 MLINKS+=getuid.2 geteuid.2
MLINKS+=intro.2 errno.2 MLINKS+=intro.2 errno.2
MLINKS+=jail.2 jail_attach.2 \ MLINKS+=jail.2 jail_attach.2 \
jail.2 jail_get.2 \ jail.2 jail_get.2 \
jail.2 jail_remove.2 \ jail.2 jail_remove.2 \
jail.2 jail_set.2 jail.2 jail_set.2
MLINKS+=kldunload.2 kldunloadf.2 MLINKS+=kldunload.2 kldunloadf.2
MLINKS+=kqueue.2 kevent.2 \ MLINKS+=kqueue.2 kevent.2 \
kqueue.2 kqueue1.2 \
kqueue.2 kqueuex.2 \ kqueue.2 kqueuex.2 \
kqueue.2 EV_SET.3 kqueue.2 EV_SET.3
MLINKS+=link.2 linkat.2 MLINKS+=link.2 linkat.2
MLINKS+=madvise.2 posix_madvise.2 MLINKS+=madvise.2 posix_madvise.2
MLINKS+=mkdir.2 mkdirat.2 MLINKS+=mkdir.2 mkdirat.2
MLINKS+=mkfifo.2 mkfifoat.2 MLINKS+=mkfifo.2 mkfifoat.2
MLINKS+=mknod.2 mknodat.2 MLINKS+=mknod.2 mknodat.2
MLINKS+=mlock.2 munlock.2 MLINKS+=mlock.2 munlock.2
▲ Show 20 Lines • Show All 81 Lines • Show Last 20 Lines
View Options

lib/libsys/kqueue.2

Show All 32 Lines
.Lb libc .Lb libc
.Sh SYNOPSIS .Sh SYNOPSIS
.In sys/event.h .In sys/event.h
.Ft int .Ft int
.Fn kqueue "void" .Fn kqueue "void"
.Ft int .Ft int
.Fn kqueuex "u_int flags" .Fn kqueuex "u_int flags"
.Ft int .Ft int
.Fn kqueue1 "int flags"
.Ft int
.Fo kevent .Fo kevent
.Fa "int kq" .Fa "int kq"
.Fa "const struct kevent *changelist" .Fa "const struct kevent *changelist"
.Fa "int nchanges" .Fa "int nchanges"
.Fa "struct kevent *eventlist" .Fa "struct kevent *eventlist"
.Fa "int nevents" .Fa "int nevents"
.Fa "const struct timespec *timeout" .Fa "const struct timespec *timeout"
.Fc .Fc
Show All 38 Lines
is called without the is called without the
.Dv RFFDG .Dv RFFDG
flag, then the descriptor table is shared, flag, then the descriptor table is shared,
which will allow sharing of the kqueue between two processes. which will allow sharing of the kqueue between two processes.
.Pp .Pp
The The
.Fn kqueuex .Fn kqueuex
system call also creates a new kernel event queue, and additionally takes system call also creates a new kernel event queue, and additionally takes
the a
.Fa flags .Fa flags
argument, which is a bitwise-inclusive OR of the following flags: argument, which is a bitwise-inclusive OR of the following flags:
.Bl -tag -width "KQUEUE_CLOEXEC" .Bl -tag -width "KQUEUE_CLOEXEC"
.It Fa KQUEUE_CLOEXEC .It Dv KQUEUE_CLOEXEC
The returned file descriptor is automatically closed on The returned file descriptor is automatically closed on
.Xr execve 2 .Xr execve 2
.El .El
.Pp
The The
.Ql fd = kqueue() .Fn kqueue
call is equivalent to system call is equivalent to calling
.Ql fd = kqueuex(0) . .Fn kqueuex
with
.Fa flags
set to 0.
.Pp .Pp
For compatibility with The
.Nx ,
the
.Fn kqueue1 .Fn kqueue1
function is provided, which accepts the function exists for compatibility with
emasteUnsubmitted
Not Done
Inline Actions

The "also" here seems somewhat out of place to me for some reason but I'm not quite sure why. Maybe "Also, for compatibility with NetBSD the..." or "The kqueue1 function is also provided, for compatibility with NetBSD. It accepts..."

emaste: The "also" here seems somewhat out of place to me for some reason but I'm not quite sure why.
.Dv O_CLOEXEC .Nx .
flag with the expected semantic. The
.Fa flags
argument accepts zero or more of the following values:
.Bl -tag -width O_CLOEXEC
.It Dv O_CLOEXEC
The returned file descriptor is automatically closed on
.Xr execve 2
.El
.Pp .Pp
The The
.Fn kevent .Fn kevent
system call system call
is used to register events with the queue, and return any pending is used to register events with the queue, and return any pending
events to the user. events to the user.
The The
.Fa changelist .Fa changelist
▲ Show 20 Lines • Show All 83 Lines • ▼ Show 20 Lines
.It Fa fflags .It Fa fflags
Filter-specific flags. Filter-specific flags.
.It Fa data .It Fa data
Filter-specific data value. Filter-specific data value.
.It Fa udata .It Fa udata
Opaque user-defined value passed through the kernel unchanged. Opaque user-defined value passed through the kernel unchanged.
.It Fa ext .It Fa ext
Extended data passed to and from kernel. Extended data passed to and from kernel.
The The meaning of the
.Fa ext[0] .Fa ext[0]
and and
.Fa ext[1] .Fa ext[1]
members use is defined by the filter. members is defined by the filter.
If the filter does not use them, the members are copied unchanged. If a filter does not use them,
these members are passed through the kernel unchanged.
The The
.Fa ext[2] .Fa ext[2]
and and
.Fa ext[3] .Fa ext[3]
members are always passed through the kernel as-is, members are always passed through the kernel unchanged,
making additional context available to application. providing additional user-defined values.
.El .El
.Pp .Pp
The The
.Va flags .Va flags
field can contain the following values: field can contain the following values:
.Bl -tag -width EV_DISPATCH .Bl -tag -width EV_KEEPUDATA
.It Dv EV_ADD .It Dv EV_ADD
Adds the event to the kqueue. Adds the event to the kqueue.
Re-adding an existing event Re-adding an existing event
will modify the parameters of the original event, and not result will modify the parameters of the original event, and not result
in a duplicate entry. in a duplicate entry.
Adding an event automatically enables it, Adding an event automatically enables it,
unless overridden by the EV_DISABLE flag. unless overridden by the EV_DISABLE flag.
.It Dv EV_ENABLE .It Dv EV_ENABLE
Show All 25 Lines
.Va data .Va data
field will be zero. field will be zero.
Note that if this flag is encountered and there is no remaining space in Note that if this flag is encountered and there is no remaining space in
.Fa eventlist .Fa eventlist
to hold the to hold the
.Dv EV_ERROR .Dv EV_ERROR
event, then subsequent changes will not get processed. event, then subsequent changes will not get processed.
.It Dv EV_ONESHOT .It Dv EV_ONESHOT
Causes the event to return only the first occurrence of the filter Return only the first occurrence of the filter
being triggered. being triggered.
After the user retrieves the event from the kqueue, After the user retrieves the event from the kqueue,
it is deleted. it is deleted.
.It Dv EV_CLEAR .It Dv EV_CLEAR
After the event is retrieved by the user, its state is reset. Reset the state of the event after it is retrieved by the user.
This is useful for filters which report state transitions This is useful for filters which report state transitions
instead of the current state. instead of the current state.
Note that some filters may automatically Note that some filters may automatically
set this flag internally. set this flag internally.
.It Dv EV_EOF .It Dv EV_EOF
Filters may set this flag to indicate filter-specific EOF condition. Filters may set this flag to indicate filter-specific EOF condition.
.It Dv EV_ERROR .It Dv EV_ERROR
See See
.Sx RETURN VALUES .Sx RETURN VALUES
below. below.
.It Dv EV_KEEPUDATA .It Dv EV_KEEPUDATA
Causes Preserve the
.Fn kevent
to leave unchanged any
.Fa udata .Fa udata
associated with an existing event. associated with an existing event.
This allows other aspects of the event to be modified without requiring the This allows other aspects of the event to be modified without requiring the
caller to know the caller to know the
.Fa udata .Fa udata
value presently associated. value previously registered with the event.
This is especially useful with This is especially useful with
.Dv NOTE_TRIGGER .Dv NOTE_TRIGGER
or flags like or
.Dv EV_ENABLE . .Dv EV_ENABLE .
This flag may not be used with This flag may not be used with
.Dv EV_ADD . .Dv EV_ADD .
.El .El
.Pp .Pp
The predefined system filters are listed below. The predefined system filters are listed below.
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
▲ Show 20 Lines • Show All 557 Lines • ▼ Show 20 Lines
.Re .Re
.Sh HISTORY .Sh HISTORY
The The
.Fn kqueue .Fn kqueue
and and
.Fn kevent .Fn kevent
system calls first appeared in system calls first appeared in
.Fx 4.1 . .Fx 4.1 .
The
.Fn kqueuex
system call
and
.Fn kevent1
function first appeared in
.Fx 14.0 .
.Sh AUTHORS .Sh AUTHORS
The The
.Fn kqueue .Fn kqueue
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
.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.