diff options
Diffstat (limited to 'share/man/man9')
| -rw-r--r-- | share/man/man9/Makefile | 7 | ||||
| -rw-r--r-- | share/man/man9/PCI_IOV_ADD_VF.9 | 2 | ||||
| -rw-r--r-- | share/man/man9/PCI_IOV_INIT.9 | 2 | ||||
| -rw-r--r-- | share/man/man9/VOP_INOTIFY.9 | 60 | ||||
| -rw-r--r-- | share/man/man9/cdefs.9 | 10 | ||||
| -rw-r--r-- | share/man/man9/coredumper_register.9 | 168 | ||||
| -rw-r--r-- | share/man/man9/counter.9 | 27 | ||||
| -rw-r--r-- | share/man/man9/cpuset.9 | 14 | ||||
| -rw-r--r-- | share/man/man9/domainset.9 | 16 | ||||
| -rw-r--r-- | share/man/man9/firmware.9 | 4 | ||||
| -rw-r--r-- | share/man/man9/mbuf.9 | 62 | ||||
| -rw-r--r-- | share/man/man9/pci.9 | 8 | ||||
| -rw-r--r-- | share/man/man9/pci_iov_schema.9 | 2 | ||||
| -rw-r--r-- | share/man/man9/style.9 | 157 | ||||
| -rw-r--r-- | share/man/man9/ucred.9 | 24 | ||||
| -rw-r--r-- | share/man/man9/vm_map.9 | 1 | ||||
| -rw-r--r-- | share/man/man9/vm_map_simplify_entry.9 | 59 | ||||
| -rw-r--r-- | share/man/man9/vnode.9 | 4 |
18 files changed, 522 insertions, 105 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index f7cd206126d6..5bcde3030ebc 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,5 +1,7 @@ .include <src.opts.mk> +PACKAGE= kernel + MAN= accept_filter.9 \ accf_data.9 \ accf_dns.9 \ @@ -67,6 +69,7 @@ MAN= accept_filter.9 \ config_intrhook.9 \ contigmalloc.9 \ copy.9 \ + coredumper_register.9 \ counter.9 \ cpu_machdep.9 \ cpuset.9 \ @@ -393,7 +396,6 @@ MAN= accept_filter.9 \ vm_map_max.9 \ vm_map_protect.9 \ vm_map_remove.9 \ - vm_map_simplify_entry.9 \ vm_map_stack.9 \ vm_map_submap.9 \ vm_map_sync.9 \ @@ -435,6 +437,7 @@ MAN= accept_filter.9 \ VOP_GETEXTATTR.9 \ VOP_GETPAGES.9 \ VOP_INACTIVE.9 \ + VOP_INOTIFY.9 \ VOP_IOCTL.9 \ VOP_LINK.9 \ VOP_LISTEXTATTR.9 \ @@ -903,6 +906,7 @@ MLINKS+=copy.9 copyin.9 \ copy.9 copyout.9 \ copy.9 copyout_nofault.9 \ copy.9 copystr.9 +MLINKS+=coredumper_register.9 coredumper_unregister.9 MLINKS+=counter.9 counter_u64_alloc.9 \ counter.9 counter_u64_free.9 \ counter.9 counter_u64_add.9 \ @@ -2461,6 +2465,7 @@ MLINKS+=VOP_CREATE.9 VOP_MKDIR.9 \ MLINKS+=VOP_FSYNC.9 VOP_FDATASYNC.9 MLINKS+=VOP_GETPAGES.9 VOP_PUTPAGES.9 MLINKS+=VOP_INACTIVE.9 VOP_RECLAIM.9 +MLINKS+=VOP_INOTIFY.9 VOP_INOTIFY_ADD_WATCH.9 MLINKS+=VOP_LOCK.9 vn_lock.9 \ VOP_LOCK.9 VOP_ISLOCKED.9 \ VOP_LOCK.9 VOP_UNLOCK.9 diff --git a/share/man/man9/PCI_IOV_ADD_VF.9 b/share/man/man9/PCI_IOV_ADD_VF.9 index d13cb6e1ddc9..512b0b8668cc 100644 --- a/share/man/man9/PCI_IOV_ADD_VF.9 +++ b/share/man/man9/PCI_IOV_ADD_VF.9 @@ -31,7 +31,7 @@ .Nd inform a PF driver that a VF is being created .Sh SYNOPSIS .In sys/bus.h -.In machine/stdarg.h +.In sys/stdarg.h .In sys/nv.h .In dev/pci/pci_iov.h .Ft int diff --git a/share/man/man9/PCI_IOV_INIT.9 b/share/man/man9/PCI_IOV_INIT.9 index 66b1e693cedb..8ce94800f6d1 100644 --- a/share/man/man9/PCI_IOV_INIT.9 +++ b/share/man/man9/PCI_IOV_INIT.9 @@ -31,7 +31,7 @@ .Nd enable SR-IOV on a PF device .Sh SYNOPSIS .In sys/bus.h -.In machine/stdarg.h +.In sys/stdarg.h .In sys/nv.h .In dev/pci/pci_iov.h .Ft int diff --git a/share/man/man9/VOP_INOTIFY.9 b/share/man/man9/VOP_INOTIFY.9 new file mode 100644 index 000000000000..43b644682153 --- /dev/null +++ b/share/man/man9/VOP_INOTIFY.9 @@ -0,0 +1,60 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Klara, Inc. +.\" +.Dd May 27, 2025 +.Dt VOP_INOTIFY 9 +.Os +.Sh NAME +.Nm VOP_INOTIFY +.Nd vnode inotify interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo VOP_INOTIFY +.Fa struct vnode *vp +.Fa struct vnode *dvp +.Fa struct componentname *cnp +.Fa int event +.Fa uint32_t cookie +.Fc +.Ft int +.Fo VOP_INOTIFY_ADD_WATCH +.Fa struct vnode *vp +.Fa struct inotify_softc *sc +.Fa uint32_t mask +.Fa uint32_t *wdp +.Fa struct thread *td +.Fc +.Sh DESCRIPTION +The +.Fn VOP_INOTIFY +operation notifies the +.Xr inotify 2 +subsystem of a file system event on a vnode. +The +.Fa dvp +and +.Fa cnp +arguments are optional and are only used to obtain a file name for the event. +If they are omitted, the inotify subsystem will use the file name cache to +find a name for the vnode, but this is more expensive. +.Pp +The +.Fn VOP_INOTIFY_ADD_WATCH +operation is for internal use by the inotify subsystem to add a watch to a +vnode. +.Sh LOCKS +The +.Fn VOP_INOTIFY +operation does not assume any particular vnode lock state. +The +.Fn VOP_INOTIFY_ADD_WATCH +operation should be called with the vnode locked. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh SEE ALSO +.Xr inotify 2 , +.Xr vnode 9 diff --git a/share/man/man9/cdefs.9 b/share/man/man9/cdefs.9 index 397ddb0891bb..cc56e34d070a 100644 --- a/share/man/man9/cdefs.9 +++ b/share/man/man9/cdefs.9 @@ -319,7 +319,7 @@ to distinguish it from newer standards. Support for this compilation environment is dependent on compilers supporting this configuration. Most of the old forms of C have been deprecated or removed in -.St -isoC-2024 . +.St -isoC-2023 . Compilers make compiling in this mode increasingly difficult and support for it may ultimately be removed from the tree. .It St -ansiC @@ -349,7 +349,7 @@ since there are no new C17 only symbols or macros. .Pp This version of the standard did not introduce any new features, only made minor, technical corrections. -.It St -isoC-2024 +.It St -isoC-2023 .Dv __STDC_VERSION__ = 202311L Strict environment selected with .Dv _C23_SOURCE @@ -385,7 +385,7 @@ implements this as a NOP because too much software breaks with the correct stric .It Dv _ANSI_SOURCE Ta St -ansiC .It Dv _C99_SOURCE Ta St -isoC-99 .It Dv _C11_SOURCE Ta St -isoC-2011 -.It Dv _C23_SOURCE Ta St -isoC-2024 +.It Dv _C23_SOURCE Ta St -isoC-2023 .It Dv _BSD_SOURCE Ta Everything, including Fx extensions .El .Pp @@ -406,7 +406,7 @@ Likewise, when C23 dialog is selected with or .St -p1003.1-2024 , definitions for -.St -isoC-2024 +.St -isoC-2023 are also included. .Ss Header Visibility Macros These macros are set by @@ -432,7 +432,7 @@ Possible values include 1990, 1999, 2011, 2017 and 2023 for .St -isoC-99 , .St -isoC-2011 , ISO/IEC 9899:2018 ("ISO C17"), and -.St -isoC-2024 , +.St -isoC-2023 , respectively. .It Dv __BSD_VISIBLE Ta 1 if the .Fx diff --git a/share/man/man9/coredumper_register.9 b/share/man/man9/coredumper_register.9 new file mode 100644 index 000000000000..f4c9eb4a1bf6 --- /dev/null +++ b/share/man/man9/coredumper_register.9 @@ -0,0 +1,168 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Kyle Evans <kevans@FreeBSD.org> +.\" +.Dd July 23, 2025 +.Dt COREDUMPER_REGISTER 9 +.Os +.Sh NAME +.Nm coredumper_register , +.Nm coredumper_unregister +.Nd loadable user coredumper support +.Sh SYNOPSIS +.In sys/ucoredump.h +.Ft void +.Fn coredumper_register "struct coredumper *cd" +.Ft void +.Fn coredumper_unregister "struct coredumper *cd" +.Pp +.Ft int +.Fn coredumper_probe_fn "struct thread *td" +.Ft int +.Fn coredumper_handle_fn "struct thread *td" "off_t limit" +.Bd -literal +/* Incomplete, but the useful members are depicted here. */ +struct coredumper { + const char *cd_name; + coredumper_probe_fn *cd_probe; + coredumper_handle_fn *cd_handle; +}; +.Ed +.Pp +.Ft int +.Fn coredump_init_fn "const struct coredump_writer *" \ +"const struct coredump_params *" +.Ft int +.Fn coredump_write_fn "const struct coredump_writer *" "const void *" "size_t" \ +"off_t" "enum uio_seg" "struct ucred *" "size_t *" "struct thread *" +.Ft int +.Fn coredump_extend_fn "const struct coredump_writer *" "off_t" "struct ucred *" +.Bd -literal +struct coredump_writer { + void *ctx; + coredump_init_fn *init_fn; + coredump_write_fn *write_fn; + coredump_extend_fn *extend_fn; +}; +.Ed +.Sh DESCRIPTION +The +.Nm +mechanism provides a path for kernel modules to register a new user process core +dumper. +The expected use of +.Nm +is for a module to define the fields of the struct coredumper listed above, then +call +.Fn coredumper_register +at +.Dv MOD_LOAD +time. +A corresponding +.Fn coredumper_unregister +should be called at +.Dv MOD_UNLOAD +time. +Note that +.Fn coredumper_unregister +will block until the specified coredumper is no longer processing coredumps. +.Pp +When a user process is preparing to start dumping core, the kernel will execute +the +.Fn cd_probe +function for each coredumper currently registered. +The +.Fn cd_probe +function is expected to return either -1 if it would decline to dump the +process, or a priority level greater than 0. +The coredumper with the highest priority will handle the coredump. +The following default priorities are defined: +.Bl -tag -width indent +.It Dv COREDUMPER_NOMATCH +This dumper declines dumping the process. +.It Dv COREDUMPER_GENERIC +This dumper will dump the process at the lowest priority. +This priority is not recommended, as the default vnode dumper will bid at +.Dv COREDUMPER_GENERIC +as well. +.It Dv COREDUMPER_SPECIAL +This dumper provides special behavior, and will dump the process at a higher +priority. +.It Dv COREDUMPER_HIGHPRIORITY +This dumper would prefer to handle this coredump. +This may be used by, for instance, a custom or vendor-specific coredump +mechanism that wishes to preempt others. +.El +.Pp +Note that this system has been designed such that the +.Fn cd_probe +function can examine the process in question and make an informed decision. +Different processes being dumped could probe at different priorities in the +same coredumper. +.Pp +Once the highest priority coredumper has been selected, the +.Fn cd_handle +function will be invoked. +The +.Fn cd_handle +will receive both the thread and the +.Dv RLIMIT_CORE +.Xr setrlimit 2 +.Fa limit . +The proc lock will be held on entry, and should be unlocked before the handler +returns. +The +.Fa limit +is typically passed to the +.Fn sv_coredump +that belongs to the process's +.Va p_sysent . +.Pp +The +.Fn cd_handle +function should return either 0 if the dump was successful, or an appropriate +.Xr errno 2 +otherwise. +.Ss Customized Coredump Writers +Custom coredumpers can define their own +.Dv coredump_writer +to pass to +.Fn sv_coredump . +.Pp +The +.Va ctx +member is opaque and only to be used by the coredumper itself. +.Pp +The +.Va init_fn +function, if it's provided, will be called by the +.Fn sv_coredump +implementation before any data is to be written. +This allows the writer implementation to record any coredump parameters that it +might need to capture, or setup the object to be written to. +.Pp +The +.Va write_fn +function will be called by the +.Fn sv_coredump +implementation to write out data. +The +.Va extend_fn +function will be called to enlarge the coredump, in the sense that a hole is +created in any difference between the current size and the new size. +For convenience, the +.Fn core_vn_write +and +.Fn core_vn_extend +functions used by the vnode coredumper are exposed in +.In sys/ucordumper.h , +and the +.Dv coredump_vnode_ctx +defined there should be populated with the vnode to write to. +.Sh SEE ALSO +.Xr setrlimit 2 , +.Xr core 5 +.Sh AUTHORS +This manual page was written by +.An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/share/man/man9/counter.9 b/share/man/man9/counter.9 index 1d3f3281ac0b..05af87e8263e 100644 --- a/share/man/man9/counter.9 +++ b/share/man/man9/counter.9 @@ -23,7 +23,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd March 11, 2021 +.Dd June 19, 2025 .Dt COUNTER 9 .Os .Sh NAME @@ -49,8 +49,14 @@ .Fn counter_u64_fetch "counter_u64_t c" .Ft void .Fn counter_u64_zero "counter_u64_t c" +.Ft struct counter_rate * +.Fn counter_rate_alloc "int flags" "int period" .Ft int64_t .Fn counter_ratecheck "struct counter_rate *cr" "int64_t limit" +.Ft uint64_t +.Fn counter_rate_get "struct counter_rate *cr" +.Ft void +.Fn counter_rate_free "struct counter_rate *cr" .Fn COUNTER_U64_SYSINIT "counter_u64_t c" .Fn COUNTER_U64_DEFINE_EARLY "counter_u64_t c" .In sys/sysctl.h @@ -133,6 +139,13 @@ value for any moment. Clear the counter .Fa c and set it to zero. +.It Fn counter_rate_alloc flags period +Allocate a new struct counter_rate. +.Fa flags +is passed to +.Xr malloc 9 . +.Fa period +is the time over which the rate is checked. .It Fn counter_ratecheck cr limit The function is a multiprocessor-friendly version of .Fn ppsratecheck @@ -140,11 +153,17 @@ which uses .Nm internally. Returns non-negative value if the rate is not yet reached during the current -second, and a negative value otherwise. -If the limit was reached on previous second, but was just reset back to zero, -then +period, and a negative value otherwise. +If the limit was reached during the previous period, but was just reset back +to zero, then .Fn counter_ratecheck returns number of events since previous reset. +.It Fn counter_rate_get cr +The number of hits to this check within the current period. +.It Fn counter_rate_free cr +Free the +.Fa cr +counter. .It Fn COUNTER_U64_SYSINIT c Define a .Xr SYSINIT 9 diff --git a/share/man/man9/cpuset.9 b/share/man/man9/cpuset.9 index 20485059a4c8..0ca04f921f82 100644 --- a/share/man/man9/cpuset.9 +++ b/share/man/man9/cpuset.9 @@ -22,7 +22,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd September 23, 2022 +.Dd August 7, 2025 .Dt CPUSET 9 .Os .Sh NAME @@ -50,8 +50,10 @@ .Nm CPU_ANDNOT , .Nm CPU_XOR , .Nm CPU_CLR_ATOMIC , +.Nm CPU_TEST_CLR_ATOMIC , .Nm CPU_SET_ATOMIC , .Nm CPU_SET_ATOMIC_ACQ , +.Nm CPU_TEST_SET_ATOMIC , .Nm CPU_AND_ATOMIC , .Nm CPU_OR_ATOMIC , .Nm CPU_COPY_STORE_REL @@ -93,8 +95,10 @@ .Fn CPU_XOR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" .\" .Fn CPU_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_TEST_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" .Fn CPU_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" .Fn CPU_SET_ATOMIC_ACQ "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_TEST_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" .\" .Fn CPU_AND_ATOMIC "cpuset_t *dst" "cpuset_t *src" .Fn CPU_OR_ATOMIC "cpuset_t *dst" "cpuset_t *src" @@ -143,6 +147,10 @@ The .Fn CPU_CLR_ATOMIC macro is identical, but the bit representing the CPU is cleared with atomic machine instructions. +The +.Fn CPU_TEST_CLR_ATOMIC +macro atomically clears the bit representing the CPU and returns whether it +was set. .Pp The .Fn CPU_COPY @@ -176,6 +184,10 @@ machine instructions. The .Fn CPU_SET_ATOMIC_ACQ macro sets the bit representing the CPU with atomic acquire semantics. +The +.Fn CPU_TEST_SET_ATOMIC +macro atomically sets the bit representing the CPU and returns whether it was +set. .Pp The .Fn CPU_ISSET diff --git a/share/man/man9/domainset.9 b/share/man/man9/domainset.9 index 816ce29f04f7..702c9f83a88b 100644 --- a/share/man/man9/domainset.9 +++ b/share/man/man9/domainset.9 @@ -22,7 +22,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd April 14, 2021 +.Dd June 24, 2025 .Dt DOMAINSET 9 .Os .Sh NAME @@ -54,6 +54,8 @@ struct domainset { .Ft struct domainset * .Fn domainset_create "const struct domainset *key" .Ft int +.Fn domainset_populate "struct domainset *domain" "domainset_t *mask" "int policy" "size_t mask_size" +.Ft int .Fn sysctl_handle_domainset "SYSCTL_HANDLER_ARGS" .Sh DESCRIPTION The @@ -137,6 +139,7 @@ These policies should be used in preference to to avoid blocking indefinitely on a .Dv M_WAITOK request. +.Pp The .Fn domainset_create function takes a partially filled in domainset as a key and returns a @@ -148,6 +151,17 @@ is an immutable type that is shared among all matching keys and must not be modified after return. .Pp The +.Fn domainset_populate +function fills a +.Vt domainset +struct using a domain mask and policy. +It is used for validating and +translating a domain mask and policy into a +.Vt domainset +struct when creating a custom domainset using +.Vt domainset_create . +.Pp +The .Fn sysctl_handle_domainset function is provided as a convenience for modifying or viewing domainsets that are not accessible via diff --git a/share/man/man9/firmware.9 b/share/man/man9/firmware.9 index f324861248d2..43f965a20fb7 100644 --- a/share/man/man9/firmware.9 +++ b/share/man/man9/firmware.9 @@ -201,7 +201,7 @@ whether compiled in, or preloaded by or manually loaded with .Xr kldload 8 . However, a system can implement additional mechanisms to bring -these images in memory before calling +these images into memory before calling .Fn firmware_register . .Pp When @@ -347,7 +347,7 @@ If .Fa imagename matches the trailing subpath of a registered image with a full path, that image is returned. .It -he kernel linker searches for a kernel module named +The kernel linker searches for a kernel module named .Fa imagename . If a kernel module is found, it is loaded, and the list of registered firmware images is searched again. diff --git a/share/man/man9/mbuf.9 b/share/man/man9/mbuf.9 index 0262c598ed18..e4f30962ccab 100644 --- a/share/man/man9/mbuf.9 +++ b/share/man/man9/mbuf.9 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 28, 2023 +.Dd August 1, 2025 .Dt MBUF 9 .Os .\" @@ -1091,7 +1091,7 @@ network code, when data must be encrypted or otherwise altered prior to transmission. .El .Sh HARDWARE-ASSISTED CHECKSUM CALCULATION -This section currently applies to TCP/IP only. +This section currently applies to SCTP, TCP, and UDP over IP only. In order to save the host CPU resources, computing checksums is offloaded to the network interface hardware if possible. The @@ -1102,8 +1102,7 @@ of a packet contains two fields used for that purpose, .Vt int Va csum_flags and .Vt int Va csum_data . -The meaning of those fields depends on the direction a packet flows in, -and on whether the packet is fragmented. +The meaning of those fields depends on whether the packet is fragmented. Henceforth, .Va csum_flags or @@ -1117,14 +1116,14 @@ in the .Vt mbuf chain containing the packet. .Pp -On output, checksum offloading is attempted after the outgoing -interface has been determined for a packet. +When a packet is sent by SCTP, TCP, or UDP, the computation of the checksum +is delayed until the outgoing interface has been determined for a packet. The interface-specific field .Va ifnet.if_data.ifi_hwassist (see .Xr ifnet 9 ) -is consulted for the capabilities of the interface to assist in -computing checksums. +is consulted by IP for the capabilities of the network interface selected for +output to assist in computing checksums. The .Va csum_flags field of the packet header is set to indicate which actions the interface @@ -1135,12 +1134,15 @@ such actions will never be requested through .Va csum_flags . .Pp The flags demanding a particular action from an interface are as follows: -.Bl -tag -width ".Dv CSUM_TCP" -offset indent +.Bl -tag -width ".Dv CSUM_SCTP" -offset indent .It Dv CSUM_IP The IP header checksum is to be computed and stored in the corresponding field of the packet. The hardware is expected to know the format of an IP header to determine the offset of the IP checksum field. +.It Dv CSUM_SCTP +The SCTP checksum is to be computed. +(See below.) .It Dv CSUM_TCP The TCP checksum is to be computed. (See below.) @@ -1149,17 +1151,19 @@ The UDP checksum is to be computed. (See below.) .El .Pp -Should a TCP or UDP checksum be offloaded to the hardware, +Should a SCTP, TCP, or UDP checksum be offloaded to the hardware, the field .Va csum_data will contain the byte offset of the checksum field relative to the end of the IP header. -In this case, the checksum field will be initially -set by the TCP/IP module to the checksum of the pseudo header +In the case of TCP or UDP, the checksum field will be initially +set by the TCP or UDP implementation to the checksum of the pseudo header defined by the TCP and UDP specifications. +In the case of SCTP, the checksum field will be initially +set by the SCTP implementation to 0. .Pp -On input, an interface indicates the actions it has performed -on a packet by setting one or more of the following flags in +When a packet is received by an interface, it indicates the actions it has +performed on a packet by setting one or more of the following flags in .Va csum_flags associated with the packet: .Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent @@ -1187,13 +1191,13 @@ to obtain the final checksum to be used for TCP or UDP validation purposes. .El .Pp If a particular network interface just indicates success or -failure of TCP or UDP checksum validation without returning +failure of SCTP, TCP, or UDP checksum validation without returning the exact value of the checksum to the host CPU, its driver can mark .Dv CSUM_DATA_VALID -and -.Dv CSUM_PSEUDO_HDR in -.Va csum_flags , +.Va csum_flags +as well as, for TCP and UDP, +.Dv CSUM_PSEUDO_HDR and set .Va csum_data to @@ -1203,6 +1207,28 @@ It is a peculiarity of the algorithm used that the Internet checksum calculated over any valid packet will be .Li 0xFFFF as long as the original checksum field is included. +Note that for SCTP the value of +.Va csum_data +is not relevant and +.Dv CSUM_PSEUDO_HDR +in +.Va csum_flags +is not set, since SCTP does not use a pseudo header checksum. +.Pp +If IP delivers a packet with the flags +.Dv CSUM_SCTP , +.Dv CSUM_TCP , +or +.Dv CSUM_UDP +set in +.Va csum_flags +to a local SCTP, TCP, or UDP stack, the packet will be processed without +computing or validating the checksum, since the packet has not been on the +wire. +This can happen if the packet was handled by a virtual interface such as +.Xr tap 4 +or +.Xr epair 4 . .Sh STRESS TESTING When running a kernel compiled with the option .Dv MBUF_STRESS_TEST , diff --git a/share/man/man9/pci.9 b/share/man/man9/pci.9 index 8f772e76ba99..eeb62a63a2bd 100644 --- a/share/man/man9/pci.9 +++ b/share/man/man9/pci.9 @@ -664,10 +664,14 @@ Buses in this state can cause devices to lose some context. Devices .Em must be prepared for the bus to be in this state or higher. -.It Dv PCI_POWERSTATE_D3 +.It Dv PCI_POWERSTATE_D3_HOT State in which the device is off and not running. Device context is lost, and power from the device can -be removed. +be (but is not necessarily) removed. +.It Dv PCI_POWERSTATE_D3_COLD +Same as +.Dv PCI_POWERSTATE_D3_HOT , +except power has been removed from the device. .It Dv PCI_POWERSTATE_UNKNOWN State of the device is unknown. .El diff --git a/share/man/man9/pci_iov_schema.9 b/share/man/man9/pci_iov_schema.9 index 764d357fbaee..99589b59fb91 100644 --- a/share/man/man9/pci_iov_schema.9 +++ b/share/man/man9/pci_iov_schema.9 @@ -38,7 +38,7 @@ .Nm pci_iov_schema_add_unicast_mac .Nd PCI SR-IOV config schema interface .Sh SYNOPSIS -.In machine/stdarg.h +.In sys/stdarg.h .In sys/nv.h .In sys/iov_schema.h .Ft nvlist_t * diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 index 5542a9685c46..26c7a3b2aa64 100644 --- a/share/man/man9/style.9 +++ b/share/man/man9/style.9 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd February 18, 2025 +.Dd July 28, 2025 .Dt STYLE 9 .Os .Sh NAME @@ -917,6 +917,161 @@ Only use the annotation for the entire if statement, rather than individual clauses. Do not add these annotations without empirical evidence of the likelihood of the branch. +.Ss C++ +KNF style was originally defined as a style for C. +C++ introduces several new idioms which do not have an existing corollary +in KNF C such as inline function definitions in classes. +C++ is also not always compatible with some KNF guidelines such as +enclosing return values in parentheses. +For C++ code, FreeBSD aims to follow broadly accepted C++ practices while +also following the general shape of KNF. +This section enumerates C++ specific guidelines that differ from KNF C. +.Pp +The preferred suffixes for C++ source files are +.Dq .cc +and +.Dq .hh . +Header files should always use a suffix, +unlike headers from the C++ standard library. +.Pp +Return values should not be enclosed in parentheses. +When converting existing C code to C++, +existing return values may remain in parentheses. +.Pp +The opening curly brace for namespace declarations should be on the first line +similar to structure and class definitions. +Nested namespaces should be declared using a single namespace declaration. +.Bd -literal +namespace foo::bar { +} +.Ed +.Pp +Member function declarations should follow the same style used for standalone +function protoypes except that a space should be used between a function's +return type and name. +.Pp +Function definitions at the top level should use a newline after the function +type similar to C function definitions. +.Pp +Nested member function definitions inside of a class, structure, or union +should not use a newline after the function type. +Instead, these should follow the style of member function declarations. +This is more common C++ style and is more compact for small methods such as +getters and setters. +.Pp +Inline functions whose body consists of a single statement may use a single +line for the function body. +Inline functions with an empty body should always use a single line. +.Bd -literal +struct widget { + int foo() { return 4; } + int bar(); +}; + +int +widget::bar() +{ + return 6; +} +.Ed +.Pp +Default and deleted methods should be declared as a single line. +.Bd -literal +class box { + ~box() = default; +}; +.Ed +.Pp +In template declarations, the +.Ic template +keyword and list of template parameters should be followed by a newline +before the templated declaration. +.Bd -literal +template <typename T> +class box { + T data; +}; +.Ed +.Pp +The +.Ic & +for reference variables should be placed on the variable name rather +than the type similar to the style used with +.Ic * +for pointers. +.Bd -literal + int x; + int &xp = x; +.Ed +.Pp +Variables may be declared at any point within a function, +not just at the start of blocks. +.Pp +Standard library containers should be used in preference to +.Xr queue 3 +or +.Xr tree 3 +macros. +.Pp +.Ic nullptr +should be used instead of +.Dv NULL +or 0. +.Pp +Use standard library types for managing strings such as +.Vt std::string +and +.Vt std::string_view +rather than +.Vt "char *" +and +.Vt "const char *" . +C types may be used when interfacing with C code. +.Pp +The +.Ic auto +keyword can be used in various contexts which improve readability. +Examples include iterators, non-trivial types of ranged-for values, +and return values of obvious types, +such as +.Ic static_cast +or +.Fn std::make_unique . +Place any qualifiers before +.Ic auto , +for example: +.Ic const auto . +.Pp +Use the +.Vt std::unique_ptr +and +.Vt std::shared_ptr +smart pointers to manage the lifetime of dynamically allocated objects +instead of +.Ic new +and +.Ic delete . +Construct smart pointers with +.Fn std::make_unique +or +.Fn std::make_shared . +Do not use +.Xr malloc 3 +except when necessary to interface with C code. +.Pp +Do not import any namespaces with +.Ic using +at global scope in header files. +Namespaces other than the +.Ic std +namespace (for example, +.Ic std::literals ) +may be imported in source files and in function scope in header files. +.Pp +Define type aliases using +.Ic using +instead of +.Ic typedef . .Sh FILES .Bl -tag -width indent .It Pa /usr/src/tools/build/checkstyle9.pl diff --git a/share/man/man9/ucred.9 b/share/man/man9/ucred.9 index e9fe2e1d02fc..38759bddb5b0 100644 --- a/share/man/man9/ucred.9 +++ b/share/man/man9/ucred.9 @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" -.Dd January 23, 2019 +.Dd July 29, 2025 .Dt UCRED 9 .Os .Sh NAME @@ -54,6 +54,9 @@ .Ft void .Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups" .Ft void +.Fn crsetgroups_and_egid "struct ucred *cr" "int ngrp" "gid_t *groups" \ + "gid_t default_egid" +.Ft void .Fn cru2x "struct ucred *cr" "struct xucred *xcr" .Sh DESCRIPTION The @@ -110,17 +113,28 @@ The actual copying is performed by .Pp The .Fn crsetgroups -function sets the +and +.Fn crsetgroups_and_egid +functions set the .Va cr_groups and .Va cr_ngroups variables and allocates space as needed. -It also truncates the group list to the current maximum number of +They also truncate the group list to the current maximum number of groups. No other mechanism should be used to modify the .Va cr_groups -array except for updating the primary group via assignment to -.Va cr_groups[0] . +array. +Note that +.Fn crsetgroups_and_egid +will interpret the first element of +.Va groups +as the new effective GID and the rest of the array as the supplementary groups, +and +.Va default_egid +will be used as the new effective GID only if +.Va groups +is empty. .Pp The .Fn cru2x diff --git a/share/man/man9/vm_map.9 b/share/man/man9/vm_map.9 index 9f41a24541b1..d08d54bd1004 100644 --- a/share/man/man9/vm_map.9 +++ b/share/man/man9/vm_map.9 @@ -323,7 +323,6 @@ is backed by a .Xr vm_map_pmap 9 , .Xr vm_map_protect 9 , .Xr vm_map_remove 9 , -.Xr vm_map_simplify_entry 9 , .Xr vm_map_stack 9 , .Xr vm_map_submap 9 , .Xr vm_map_sync 9 , diff --git a/share/man/man9/vm_map_simplify_entry.9 b/share/man/man9/vm_map_simplify_entry.9 deleted file mode 100644 index 0e99596d067e..000000000000 --- a/share/man/man9/vm_map_simplify_entry.9 +++ /dev/null @@ -1,59 +0,0 @@ -.\" -.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" 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 -.\" SUCH DAMAGE. -.\" -.Dd July 19, 2003 -.Dt VM_MAP_SIMPLIFY_ENTRY 9 -.Os -.Sh NAME -.Nm vm_map_simplify_entry -.Nd simplify a -.Vt vm_map_entry -.Sh SYNOPSIS -.In sys/param.h -.In vm/vm.h -.In vm/vm_map.h -.Ft void -.Fn vm_map_simplify_entry "vm_map_t map" "vm_map_entry_t entry" -.Sh DESCRIPTION -The -.Fn vm_map_simplify_entry -function simplifies the given -.Fa entry -by merging with either neighbour. -The -.Fa map -must be locked upon entry. -.Pp -This function also has the ability to merge with both neighbours. -.Pp -This function guarantees that the passed entry remains valid, although -possibly extended. -.Sh SEE ALSO -.Xr vm_map 9 , -.Xr vm_map_insert 9 , -.Xr vm_map_remove 9 -.Sh AUTHORS -This manual page was written by -.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/share/man/man9/vnode.9 b/share/man/man9/vnode.9 index 5dd087725e92..d17492668298 100644 --- a/share/man/man9/vnode.9 +++ b/share/man/man9/vnode.9 @@ -24,7 +24,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd October 9, 2024 +.Dd July 15, 2025 .Dt VNODE 9 .Os .Sh NAME @@ -113,7 +113,7 @@ The function declarations and definitions are generated from .Pa sys/kern/vnode_if.src by the -.Pa sys/tools/vndoe_if.awk +.Pa sys/tools/vnode_if.awk script. The interfaces are documented in their respective manual pages like .Xr VOP_READ 9 |