diff options
Diffstat (limited to 'share/man/man7')
38 files changed, 3736 insertions, 1348 deletions
diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index 228c4ea393d5..6a426cc29b15 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -1,39 +1,45 @@ -# @(#)Makefile 8.1 (Berkeley) 6/5/93 -# $FreeBSD$ - .include <src.opts.mk> +MANGROUPS= MAN + #MISSING: eqnchar.7 ms.7 term.7 MAN= arch.7 \ ascii.7 \ bsd.snmpmod.mk.7 \ build.7 \ c.7 \ + d.7 \ clocks.7 \ crypto.7 \ development.7 \ environ.7 \ - ffs.7 \ firewall.7 \ growfs.7 \ hier.7 \ hostname.7 \ intro.7 \ maclabel.7 \ + mitigations.7 \ + named_attribute.7 \ operator.7 \ orders.7 \ + freebsd-base.7 \ ports.7 \ release.7 \ sdoc.7 \ security.7 \ + simd.7 \ + sizeof.7 \ sprog.7 \ stats.7 \ stdint.7 \ sticky.7 \ - tests.7 \ + tracing.7 \ tuning.7 MLINKS= intro.7 miscellaneous.7 +MLINKS+= growfs.7 growfs_fstab.7 +MLINKS+= freebsd-base.7 pkgbase.7 MLINKS+= security.7 securelevel.7 MLINKS+= c.7 c78.7 MLINKS+= c.7 c89.7 @@ -42,17 +48,30 @@ MLINKS+= c.7 c95.7 MLINKS+= c.7 c99.7 MLINKS+= c.7 c11.7 MLINKS+= c.7 c17.7 -MLINKS+= c.7 c2x.7 +MLINKS+= c.7 c23.7 +MLINKS+= c.7 c2y.7 + +.if ${MK_INET} != "no" +MAN+= networking.7 +MLINKS+= networking.7 wifi.7 +.endif .if ${MK_TESTS} != "no" -ATF= ${SRCTOP}/contrib/atf -.PATH: ${ATF}/doc -MAN+= atf.7 +MANGROUPS+= ATF TESTS + +TESTS= tests.7 +TESTSPACKAGE= tests + +ATF= atf.7 +ATFPACKAGE= atf + +ATFPATH= ${SRCTOP}/contrib/atf +.PATH: ${ATFPATH}/doc CLEANFILES+= atf.7 atf.7: atf.7.in sed -e 's,__DOCDIR__,/usr/share/doc/atf,g' \ - <"${ATF}/doc/atf.7.in" >atf.7 + <"${ATFPATH}/doc/atf.7.in" >atf.7 .endif .include <bsd.prog.mk> diff --git a/share/man/man7/Makefile.depend b/share/man/man7/Makefile.depend index f80275d86ab1..11aba52f82cf 100644 --- a/share/man/man7/Makefile.depend +++ b/share/man/man7/Makefile.depend @@ -1,4 +1,3 @@ -# $FreeBSD$ # Autogenerated - do NOT edit! DIRDEPS = \ diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7 index c7c2e224b33d..5170a27768b8 100644 --- a/share/man/man7/arch.7 +++ b/share/man/man7/arch.7 @@ -24,9 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd November 25, 2021 +.Dd October 1, 2025 .Dt ARCH 7 .Os .Sh NAME @@ -44,33 +42,44 @@ documentation. .Pp If not explicitly mentioned, sizes are in bytes. The architecture details in this document apply to -.Fx 12.0 +.Fx 13.0 and later, unless otherwise noted. .Pp .Fx uses a flat address space. Variables of types -.Vt unsigned long , -.Vt uintptr_t , +.Vt unsigned long and .Vt size_t -and pointers all have the same representation. +have the same representation. .Pp In order to maximize compatibility with future pointer integrity mechanisms, manipulations of pointers as integers should be performed via .Vt uintptr_t or .Vt intptr_t -and no other types. -In particular, -.Vt long +and no other types as these types are the only integer types where the +C standard guarantees that a pointer may be cast to it and then cast back +to the original type. +On CHERI systems, +.Vt uintptr_t and -.Vt ptrdiff_t -should be avoided. +.Vt intptr_t +are defined as +.Vt __uintcap_t +and +.Vt __intcap_t +which represent capabilities that can be manipulated by integer operations. +Pointers should not be cast to +.Vt long , +.Vt ptrdiff_t , +or +.Vt size_t +if they will later be cast back to a pointer that is expected to be +dereferenceable as they remain bare integer types on all architectures. .Pp On some architectures, e.g., -.Dv powerpc -and AIM variants of +AIM variants of .Dv powerpc64 , the kernel uses a separate address space. On other architectures, kernel and a user mode process share a @@ -88,36 +97,38 @@ release to support each architecture. .Bl -column -offset indent "Architecture" "Initial Release" .It Sy Architecture Ta Sy Initial Release .It aarch64 Ta 11.0 +.It aarch64c Ta 16.0 (planned) .It amd64 Ta 5.1 -.It armv6 Ta 10.0 .It armv7 Ta 12.0 -.It i386 Ta 1.0 -.It powerpc Ta 6.0 -.It powerpcspe Ta 12.0 .It powerpc64 Ta 9.0 .It powerpc64le Ta 13.0 .It riscv64 Ta 12.0 -.It riscv64sf Ta 12.0 +.It riscv64c Ta 16.0 (planned) .El .Pp Discontinued architectures are shown in the following table. .Bl -column -offset indent "Architecture" "Initial Release" "Final Release" .It Sy Architecture Ta Sy Initial Release Ta Sy Final Release .It alpha Ta 3.2 Ta 6.4 -.It arm Ta 6.0 Ta 12.x +.It arm Ta 6.0 Ta 12.4 .It armeb Ta 8.0 Ta 11.4 +.It armv6 Ta 10.0 Ta 14.x .It ia64 Ta 5.0 Ta 10.4 -.It mips Ta 8.0 Ta 13.x -.It mipsel Ta 9.0 Ta 13.x -.It mipselhf Ta 12.0 Ta 13.x -.It mipshf Ta 12.0 Ta 13.x -.It mipsn32 Ta 9.0 Ta 13.x -.It mips64 Ta 9.0 Ta 13.x -.It mips64el Ta 9.0 Ta 13.x -.It mips64elhf Ta 12.0 Ta 13.x -.It mips64hf Ta 12.0 Ta 13.x +.It i386 Ta 1.0 Ta 14.x +.It mips Ta 8.0 Ta 13.5 +.It mipsel Ta 9.0 Ta 13.5 +.It mipselhf Ta 12.0 Ta 13.5 +.It mipshf Ta 12.0 Ta 13.5 +.It mipsn32 Ta 9.0 Ta 13.5 +.It mips64 Ta 9.0 Ta 13.5 +.It mips64el Ta 9.0 Ta 13.5 +.It mips64elhf Ta 12.0 Ta 13.5 +.It mips64hf Ta 12.0 Ta 13.5 .It pc98 Ta 2.2 Ta 11.4 -.It sparc64 Ta 5.0 Ta 12.x +.It powerpc Ta 6.0 Ta 14.x +.It powerpcspe Ta 12.0 Ta 14.x +.It riscv64sf Ta 12.0 Ta 13.5 +.It sparc64 Ta 5.0 Ta 12.4 .El .Ss Type sizes All @@ -126,21 +137,33 @@ architectures use some variant of the ELF (see .Xr elf 5 ) .Sy Application Binary Interface (ABI) for the machine processor. -All supported ABIs can be divided into two groups: -.Bl -tag -width "Dv ILP32" +Supported ABIs can be divided into three main groups: +.Bl -tag -width "Dv L64PC128" .It Dv ILP32 .Vt int , +.Vt intptr_t , .Vt long , +and .Vt void * types machine representations all have 4-byte size. .It Dv LP64 .Vt int type machine representation uses 4 bytes, while -.Vt long +.Vt intptr_t , +.Vt long , and .Vt void * are 8 bytes. +.It Dv L64PC128 +.Vt int +type machine representation uses 4 bytes. +.Vt long +type machine representation uses 8 bytes. +.Vt intptr_t +and +.Vt void * +are 16 byte capabilities. .El .Pp Some machines support more than one @@ -158,27 +181,37 @@ Examples are: .It Sy LP64 Ta Sy ILP32 counterpart .It Dv amd64 Ta Dv i386 .It Dv powerpc64 Ta Dv powerpc -.It Dv mips64* Ta Dv mips* -.It Dv aarch64 Ta Dv armv6/armv7 +.It Dv aarch64 Ta Dv armv7 .El .Pp .Dv aarch64 will support execution of -.Dv armv6 -or .Dv armv7 binaries if the CPU implements .Dv AArch32 -execution state, however -.Dv armv5 -binaries aren't supported. +execution state. +Binaries targeting +.Dv armv6 +and earlier are no longer supported by +.Fx . +.Pp +Architectures with 128-bit capabilities support both a +.Dq native +.Dv L64PC128 +execution environment and a +.Dv LP64 +environment: +.Bl -column -offset indent "aarch64c" "LP64 counterpart" +.It Sy L64PC128 Ta Sy LP64 counterpart +.It Dv aarch64c Ta Dv aarch64 +.It Dv riscv64c Ta Dv riscv64 +.El .Pp On all supported architectures: -.Bl -column -offset -indent "long long" "Size" +.Bl -column -offset indent "long long" "Size" .It Sy Type Ta Sy Size .It short Ta 2 .It int Ta 4 -.It long Ta sizeof(void*) .It long long Ta 8 .It float Ta 4 .It double Ta 8 @@ -187,33 +220,24 @@ On all supported architectures: Integers are represented in two's complement. Alignment of integer and pointer types is natural, that is, the address of the variable must be congruent to zero modulo the type size. -Most ILP32 ABIs, except -.Dv arm , -require only 4-byte alignment for 64-bit integers. +The sole exception is that +.Dv i386 +requires only 4-byte alignment for 64-bit integers. .Pp Machine-dependent type sizes: -.Bl -column -offset indent "Architecture" "void *" "long double" "time_t" -.It Sy Architecture Ta Sy void * Ta Sy long double Ta Sy time_t -.It aarch64 Ta 8 Ta 16 Ta 8 -.It amd64 Ta 8 Ta 16 Ta 8 -.It armv6 Ta 4 Ta 8 Ta 8 -.It armv7 Ta 4 Ta 8 Ta 8 -.It i386 Ta 4 Ta 12 Ta 4 -.It mips Ta 4 Ta 8 Ta 8 -.It mipsel Ta 4 Ta 8 Ta 8 -.It mipselhf Ta 4 Ta 8 Ta 8 -.It mipshf Ta 4 Ta 8 Ta 8 -.It mipsn32 Ta 4 Ta 8 Ta 8 -.It mips64 Ta 8 Ta 8 Ta 8 -.It mips64el Ta 8 Ta 8 Ta 8 -.It mips64elhf Ta 8 Ta 8 Ta 8 -.It mips64hf Ta 8 Ta 8 Ta 8 -.It powerpc Ta 4 Ta 8 Ta 8 -.It powerpcspe Ta 4 Ta 8 Ta 8 -.It powerpc64 Ta 8 Ta 8 Ta 8 -.It powerpc64le Ta 8 Ta 8 Ta 8 -.It riscv64 Ta 8 Ta 16 Ta 8 -.It riscv64sf Ta 8 Ta 16 Ta 8 +.Bl -column -offset indent "Architecture" "long" "void *" "long double" "time_t" +.It Sy Architecture Ta Sy long Ta Sy void * Ta Sy long double Ta Sy time_t +.It aarch64 Ta 8 Ta 8 Ta 16 Ta 8 +.It aarch64c Ta 8 Ta 16 Ta 16 Ta 8 +.It amd64 Ta 8 Ta 8 Ta 16 Ta 8 +.It armv7 Ta 4 Ta 4 Ta 8 Ta 8 +.It i386 Ta 4 Ta 4 Ta 12 Ta 4 +.It powerpc Ta 4 Ta 4 Ta 8 Ta 8 +.It powerpcspe Ta 4 Ta 4 Ta 8 Ta 8 +.It powerpc64 Ta 8 Ta 8 Ta 8 Ta 8 +.It powerpc64le Ta 8 Ta 8 Ta 8 Ta 8 +.It riscv64 Ta 8 Ta 8 Ta 16 Ta 8 +.It riscv64c Ta 8 Ta 16 Ta 16 Ta 8 .El .Pp .Sy time_t @@ -222,73 +246,103 @@ is 8 bytes on all supported architectures except i386. .Bl -column -offset indent "Architecture" "Endianness" "char Signedness" .It Sy Architecture Ta Sy Endianness Ta Sy char Signedness .It aarch64 Ta little Ta unsigned +.It aarch64c Ta little Ta unsigned .It amd64 Ta little Ta signed -.It armv6 Ta little Ta unsigned .It armv7 Ta little Ta unsigned .It i386 Ta little Ta signed -.It mips Ta big Ta signed -.It mipsel Ta little Ta signed -.It mipselhf Ta little Ta signed -.It mipshf Ta big Ta signed -.It mipsn32 Ta big Ta signed -.It mips64 Ta big Ta signed -.It mips64el Ta little Ta signed -.It mips64elhf Ta little Ta signed -.It mips64hf Ta big Ta signed .It powerpc Ta big Ta unsigned .It powerpcspe Ta big Ta unsigned .It powerpc64 Ta big Ta unsigned .It powerpc64le Ta little Ta unsigned .It riscv64 Ta little Ta signed -.It riscv64sf Ta little Ta signed +.It riscv64c Ta little Ta signed .El .Ss Page Size .Bl -column -offset indent "Architecture" "Page Sizes" .It Sy Architecture Ta Sy Page Sizes -.It aarch64 Ta 4K, 2M, 1G +.It aarch64 Ta 4K, 64K, 2M, 1G +.It aarch64c Ta 4K, 64K, 2M, 1G .It amd64 Ta 4K, 2M, 1G -.It armv6 Ta 4K, 1M .It armv7 Ta 4K, 1M .It i386 Ta 4K, 2M (PAE), 4M -.It mips Ta 4K -.It mipsel Ta 4K -.It mipselhf Ta 4K -.It mipshf Ta 4K -.It mipsn32 Ta 4K -.It mips64 Ta 4K -.It mips64el Ta 4K -.It mips64elhf Ta 4K -.It mips64hf Ta 4K .It powerpc Ta 4K .It powerpcspe Ta 4K .It powerpc64 Ta 4K .It powerpc64le Ta 4K .It riscv64 Ta 4K, 2M, 1G -.It riscv64sf Ta 4K, 2M, 1G +.It riscv64c Ta 4K, 2M, 1G .El +.Ss User Address Space Layout +.Bl -column -offset indent "riscv64 (Sv48)" "0x0001000000000000" "NNNU" +.It Sy Architecture Ta Sy Maximum Address Ta Sy Address Space Size +.It aarch64 Ta 0x0001000000000000 Ta 256TiB +.It aarch64c Ta 0x0001000000000000 Ta 256TiB +.It amd64 (LA48) Ta 0x0000800000000000 Ta 128TiB +.It amd64 (LA57) Ta 0x0100000000000000 Ta 64PiB +.It armv7 Ta 0xbfc00000 Ta 3GiB +.It i386 Ta 0xffc00000 Ta 4GiB +.It powerpc Ta 0xfffff000 Ta 4GiB +.It powerpcspe Ta 0x7ffff000 Ta 2GiB +.It powerpc64 Ta 0x000fffffc0000000 Ta 4PiB +.It powerpc64le Ta 0x000fffffc0000000 Ta 4PiB +.It riscv64 (Sv39) Ta 0x0000004000000000 Ta 256GiB +.It riscv64c (Sv39) Ta 0x0000004000000000 Ta 256GiB +.It riscv64 (Sv48) Ta 0x0000800000000000 Ta 128TiB +.It riscv64c (Sv48) Ta 0x0000800000000000 Ta 128TiB +.El +.Pp +The layout of a process' address space can be queried via the +.Dv KERN_PROC_VM_LAYOUT +.Xr sysctl 3 +MIB. +.Pp +Historically, amd64 CPUs were limited to a 48-bit virtual address space. +Newer CPUs support 5-level page tables, which extend the significant bits of +addresses to 57 bits (LA57 mode). +The address space layout is determined by the CPU's support for LA57. +Setting the +.Sy vm.pmap.la57 +tunable to 0 forces the system into 4-level paging mode, even on hardware that +supports 5-level paging. +In this mode, all processes get a 48-bit address space. +The +.Sy vm.pmap.prefer_la48_uva +tunable determines whether processes running on a LA57 system are limited to +a 48-bit address space by default. +Some applications make use of unused upper bits in pointer values to store +information, and thus implicitly assume they are running in LA48 mode. +To avoid breaking compatibility, all processes run in LA48 mode by default. +The +.Xr elfctl 1 +utility can be used to request LA48 or LA57 mode for specific executables. +Similarly, +.Xr proccontrol 1 +can be used to configure the address space layout when executing a process. +.Pp +The RISC-V specification permits 3-level (Sv39), 4-level (Sv48), and +5-level (Sv57) page tables. +Hardware is only required to implement Sv39; implementations which support +Sv48 must also support Sv39, and implementations which support Sv57 must also +support Sv48. +The +.Sy vm.pmap.mode +tunable can be used to select the layout. +.Fx +currently supports Sv39 and Sv48 and defaults to using Sv39. .Ss Floating Point .Bl -column -offset indent "Architecture" "float, double" "long double" .It Sy Architecture Ta Sy float, double Ta Sy long double .It aarch64 Ta hard Ta soft, quad precision +.It aarch64c Ta hard Ta soft, quad precision .It amd64 Ta hard Ta hard, 80 bit -.It armv6 Ta hard Ta hard, double precision .It armv7 Ta hard Ta hard, double precision .It i386 Ta hard Ta hard, 80 bit -.It mips Ta soft Ta identical to double -.It mipsel Ta soft Ta identical to double -.It mipselhf Ta hard Ta identical to double -.It mipshf Ta hard Ta identical to double -.It mipsn32 Ta soft Ta identical to double -.It mips64 Ta soft Ta identical to double -.It mips64el Ta soft Ta identical to double -.It mips64elhf Ta hard Ta identical to double -.It mips64hf Ta hard Ta identical to double .It powerpc Ta hard Ta hard, double precision .It powerpcspe Ta hard Ta hard, double precision .It powerpc64 Ta hard Ta hard, double precision .It powerpc64le Ta hard Ta hard, double precision .It riscv64 Ta hard Ta hard, quad precision -.It riscv64sf Ta soft Ta soft, quad precision +.It riscv64c Ta hard Ta hard, quad precision .El .Ss Default Tool Chain .Fx @@ -298,7 +352,7 @@ as the default compiler on all supported CPU architectures, LLVM's .Xr ld.lld 1 as the default linker, and -ELF Tool Chain binary utilities such as +LLVM binary utilities such as .Xr objcopy 1 and .Xr readelf 1 . @@ -315,13 +369,12 @@ when referring to the kernel, interfaces dependent on a specific type of kernel or similar things like boot sequences. .Bl -column -offset indent "Dv MACHINE" "Dv MACHINE_CPUARCH" "Dv MACHINE_ARCH" .It Dv MACHINE Ta Dv MACHINE_CPUARCH Ta Dv MACHINE_ARCH -.It arm64 Ta aarch64 Ta aarch64 +.It arm64 Ta aarch64 Ta aarch64, aarch64c .It amd64 Ta amd64 Ta amd64 -.It arm Ta arm Ta armv6, armv7 +.It arm Ta arm Ta armv7 .It i386 Ta i386 Ta i386 -.It mips Ta mips Ta mips, mipsel, mips64, mips64el, mipshf, mipselhf, mips64elhf, mipsn32 .It powerpc Ta powerpc Ta powerpc, powerpcspe, powerpc64, powerpc64le -.It riscv Ta riscv Ta riscv64, riscv64sf +.It riscv Ta riscv Ta riscv64, riscv64c .El .Ss Predefined Macros The compiler provides a number of predefined macros. @@ -335,39 +388,49 @@ cc -x c -dM -E /dev/null .Ed .Pp Common type size and endianness macros: -.Bl -column -offset indent "BYTE_ORDER" "Meaning" +.Bl -column -offset indent "__SIZEOF_POINTER__" "Meaning" .It Sy Macro Ta Sy Meaning +.It Dv __SIZEOF_LONG__ Ta size in bytes of long +.It Dv __SIZEOF_POINTER__ Ta size in bytes of intptr_t and pointers +.It Dv __SIZEOF_SIZE_T__ Ta size in bytes of size_t .It Dv __LP64__ Ta 64-bit (8-byte) long and pointer, 32-bit (4-byte) int .It Dv __ILP32__ Ta 32-bit (4-byte) int, long and pointer +.It Dv __CHERI__ Ta 128-bit (16-byte) capability pointer, 64-bit (8-byte) long .It Dv BYTE_ORDER Ta Either Dv BIG_ENDIAN or Dv LITTLE_ENDIAN . -.Dv PDP11_ENDIAN -is not used on -.Fx . .El .Pp +Because systems were historically either +.Dv __ILP32__ +or +.Dv __LP64__ +it has been common for programmers to test only one and assume the other +one in an else branch. +With the arrival of CHERI architectures, this is no longer the case. +.Dv __SIZEOF_*__ +macros should be used instead. +New uses of +.Dv __ILP32__ +and +.Dv __LP64__ +should be avoided. +Compilers for CHERI targets do not define +.Dv __LP64__ +as their pointers are 128-bit capabilities. +.Pp Architecture-specific macros: .Bl -column -offset indent "Architecture" "Predefined macros" .It Sy Architecture Ta Sy Predefined macros .It aarch64 Ta Dv __aarch64__ +.It aarch64c Ta Dv __aarch64__ , Dv __CHERI__ .It amd64 Ta Dv __amd64__ , Dv __x86_64__ -.It armv6 Ta Dv __arm__ , Dv __ARM_ARCH >= 6 .It armv7 Ta Dv __arm__ , Dv __ARM_ARCH >= 7 .It i386 Ta Dv __i386__ -.It mips Ta Dv __mips__ , Dv __MIPSEB__ , Dv __mips_o32 -.It mipsel Ta Dv __mips__ , Dv __mips_o32 -.It mipselhf Ta Dv __mips__ , Dv __mips_o32 -.It mipshf Ta Dv __mips__ , Dv __MIPSEB__ , Dv __mips_o32 -.It mipsn32 Ta Dv __mips__ , Dv __MIPSEB__ , Dv __mips_n32 -.It mips64 Ta Dv __mips__ , Dv __MIPSEB__ , Dv __mips_n64 -.It mips64el Ta Dv __mips__ , Dv __mips_n64 -.It mips64elhf Ta Dv __mips__ , Dv __mips_n64 -.It mips64hf Ta Dv __mips__ , Dv __MIPSEB__ , Dv __mips_n64 .It powerpc Ta Dv __powerpc__ .It powerpcspe Ta Dv __powerpc__ , Dv __SPE__ .It powerpc64 Ta Dv __powerpc__ , Dv __powerpc64__ .It powerpc64le Ta Dv __powerpc__ , Dv __powerpc64__ .It riscv64 Ta Dv __riscv , Dv __riscv_xlen == 64 -.It riscv64sf Ta Dv __riscv , Dv __riscv_xlen == 64 , Dv __riscv_float_abi_soft +.It riscv64c Ta Dv __riscv , Dv __riscv_xlen == 64 , Dv __CHERI__ .El .Pp Compilers may define additional variants of architecture-specific macros. @@ -429,34 +492,30 @@ It may also encode a variation in the size of the integer or pointer. It may also encode a ISA revision. It may also encode hard versus soft floating point ABI and usage. It may also encode a variant ABI when the other factors do not -uniquely define the ABI (e.g., MIPS' n32 ABI). +uniquely define the ABI. It, along with .Dv MACHINE , defines the ABI used by the system. -For example, the MIPS CPU processor family supports 9 different -combinations encoding pointer size, endian and hard versus soft float (for -8 combinations) as well as N32 (which only ever had one variation of -all these). Generally, the plain CPU name specifies the most common (or at least first) variant of the CPU. -This is why mips and mips64 imply 'big endian' while 'armv6' and 'armv7' +This is why powerpc and powerpc64 imply 'big endian' while armv7 and aarch64 imply little endian. If we ever were to support the so-called x32 ABI (using 32-bit pointers on the amd64 architecture), it would most likely be encoded as amd64-x32. -It is unfortunate that amd64 specifies the 64-bit evolution of the x86 -platform (it matches the 'first rule') as everybody else uses x86_64. -There is no standard name for the processor: each OS selects its own -conventions. +It is unfortunate that amd64 specifies the 64-bit evolution of the x86 platform +(it matches the 'first rule') as almost everybody else uses x86_64. +The +.Fx +port was so early, it predated processor name standardization after Intel joined +the market. +At the time, each OS selected its own conventions. +Backwards compatibility means it is not easy to change to the consensus name. .It Dv MACHINE_CPUARCH Represents the source location for a given .Dv MACHINE_ARCH . It is generally the common prefix for all the MACHINE_ARCH that share the same implementation, though 'riscv' breaks this rule. -For example, -.Dv MACHINE_CPUARCH -is defined to be mips for all the flavors of mips that we support -since we support them all with a shared set of sources. While amd64 and i386 are closely related, MACHINE_CPUARCH is not x86 for them. The @@ -480,7 +539,7 @@ in the top level Makefile for cross building. Unused outside of that scope. It is not passed down to the rest of the build. Makefiles outside of the top level should not use it at all (though -some have their own private copy for hysterical raisons). +some have their own private copy for historical reasons). .It Dv TARGET_ARCH Used to set .Dv MACHINE_ARCH @@ -490,8 +549,12 @@ Like it is unused outside of that scope. .El .Sh SEE ALSO +.Xr elfctl 1 , +.Xr proccontrol 1 , +.Xr sysctl 3 , .Xr src.conf 5 , -.Xr build 7 +.Xr build 7 , +.Xr simd 7 .Sh HISTORY An .Nm diff --git a/share/man/man7/ascii.7 b/share/man/man7/ascii.7 index 713a4922e759..11f4f63ccb47 100644 --- a/share/man/man7/ascii.7 +++ b/share/man/man7/ascii.7 @@ -25,10 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)ascii.7 8.1 (Berkeley) 6/5/93 -.\" $FreeBSD$ -.\" -.Dd September 21, 2019 +.Dd January 4, 2025 .Dt ASCII 7 .Os .Sh NAME @@ -142,6 +139,44 @@ ESC ; [ { 11011 RS > ^ - 11110 US ? _ DEL 11111 .Ed +.Pp +The full +.Nm names +of the control character set: +.Bd -literal -offset left +NUL NULl +SOH Start Of Heading +STX Start Of Text +ETX End Of Text +EOT End Of Transmission +ENQ ENQuiry +ACK ACKnowledge +BEL BELl + BS BackSpace + HT Horizontal Tab + LF Line Feed (new line) + VT Vertical Tab + FF new page Form Feed + CR Carriage Return + SO Shift Out + SI Shift In +DLE Data Link Escape +DC1 Device Control 1 +DC2 Device Control 2 +DC3 Device Control 3 +DC4 Device Control 4 +NAK Negative AcKnowledge +SYN SYNchronous idle +ETB End of Transmission Block +CAN CANcel + EM End of Medium +SUB SUBstitute +ESC ESCape + FS File Separator + GS Group Separator + RS Record Separator + US Unit Separator +.Ed .Sh FILES .Bl -tag -width /usr/share/misc/ascii -compact .It Pa /usr/share/misc/ascii @@ -157,4 +192,4 @@ ESC ; [ { 11011 An .Nm manual page appeared in -.At v2 . +.At v1 . diff --git a/share/man/man7/bsd.snmpmod.mk.7 b/share/man/man7/bsd.snmpmod.mk.7 index 299daf227e18..fc6ca0ae20e1 100644 --- a/share/man/man7/bsd.snmpmod.mk.7 +++ b/share/man/man7/bsd.snmpmod.mk.7 @@ -26,8 +26,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd January 8, 2008 .Dt BSD.SNMPMOD.MK 7 .Os diff --git a/share/man/man7/build.7 b/share/man/man7/build.7 index 4e499c81b45c..9adfd4bc8a63 100644 --- a/share/man/man7/build.7 +++ b/share/man/man7/build.7 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 2000 .\" Mike W. Meyer .\" @@ -22,45 +25,39 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd August 10, 2021 +.Dd September 25, 2025 .Dt BUILD 7 .Os .Sh NAME .Nm build -.Nd General instructions on how to build the system +.Nd general instructions on how to build the +.Fx +system .Sh DESCRIPTION The sources for the .Fx -system and its applications are contained in three different directories, -normally -.Pa /usr/src , -.Pa /usr/doc , -and -.Pa /usr/ports . -These directories may be initially empty or non-existent until updated with -Git -.Po installed from packages with -.Xr pkg 7 -or from -.Xr ports 7 Pc . -Directory -.Pa /usr/src -contains the -.Dq "base system" -sources, which is loosely defined as the things required to rebuild -the system to a useful state. -Directory -.Pa /usr/doc -contains the source for the system documentation, excluding the manual -pages. -Directory -.Pa /usr/ports -contains a tree that provides a consistent interface for building and -installing third party applications. -For more information about the ports build process, see -.Xr ports 7 . +system and its applications are contained in three directories, +normally: +.Bl -tag -width "/usr/ports" +.It Pa /usr/src +.Dq base system , +loosely defined as everything required to build the system +to a useful state +.It Pa /usr/doc +system documentation, excluding manual pages +.It Pa /usr/ports +third-party software, with a consistent interface for building and +installing them; see +.Xr ports 7 +.El +.Pp +These directories may be initially empty or non-existent until updated +with Git +.Po Pa devel/git +from the +.Fx +Ports Collection +.Pc . .Pp The .Xr make 1 @@ -89,7 +86,9 @@ The canonical object directory is described in the documentation for the .Cm buildworld target below. .Pp -The build may be controlled by defining +The +.Nm +may be controlled by defining .Xr make 1 variables described in the .Sx ENVIRONMENT @@ -190,6 +189,20 @@ the compiler, linker, assembler, headers and libraries) has been built; see the .Cm toolchain target below. +.Pp +.Va BUILDENV_SHELL , +which defaults to +.Pa /bin/sh , +is executed. +This can be set to a command that does something in this build environment, +like cross build an application. +If that application has dependencies, though, the +.Pa devel/poudriere +package or port provides a more generic solution. +.It Cm buildenvvars +Print the shell variables that are set for a +.Cm buildenv +environment and exit. .It Cm buildworld Build everything but the kernel, configure files in .Pa etc , @@ -265,13 +278,31 @@ defaults to and .Sy TARGET_ARCH must be defined. +.It Cm packages +Create a +.Xr freebsd-base 7 +package repository containing packages that can be +used to install or upgrade the base system. +The repository is created in the object directory, under +.Pa ${REPODIR}/${PKG_ABI} +where +.Ev REPODIR +is the base directory where the repository will be created, and +.Va PKG_ABI +is the +.Xr pkg 7 +ABI for the build target, for example, +.Pa /usr/obj/${SRCDIR}/repo/FreeBSD:15:amd64 . .It Cm packageworld Archive the results of .Cm distributeworld , placing the results in .Va DISTDIR . -This target is used while building a release; see -.Xr release 7 . +This target is used while building a +.Xr release 7 +and is unrelated to building +.Xr freebsd-base 7 +packages. .It Cm installworld Install everything built by a preceding .Cm buildworld @@ -352,6 +383,14 @@ and .Va XDDIR defaults to .Pa ${TARGET_ARCH}-freebsd . +.It Cm update-packages +Create or update the +.Xr freebsd-base 7 +package repository for the base system. +If an old repository is being updated, +then packages whose contents have not changed since the previous version +will be copied into the new repository to avoid needless updating of the +version number. .It Cm xdev-build Builds for the .Cm xdev @@ -389,7 +428,7 @@ The target directory under .Pa ${DESTDIR} may be modified using the .Va INSTKERNNAME -and +or .Va KODIR .Xr make 1 variables. @@ -403,8 +442,11 @@ Archive the results of .Cm distributekernel , placing the results in .Va DISTDIR . -This target is used while building a release; see -.Xr release 7 . +This target is used while building a +.Xr release 7 +and is unrelated to building +.Xr freebsd-base 7 +packages. .It Cm kernel Equivalent to .Cm buildkernel @@ -433,6 +475,8 @@ include: .Bl -tag -width ".Cm delete-old-libs" .It Cm check-old Print a list of old files and directories in the system. +.It Cm check-old-libs +Print a list of obsolete base system libraries. .It Cm delete-old Delete obsolete base system files and directories interactively. When @@ -484,6 +528,9 @@ The directory hierarchy prefix where built objects will be installed. If not set, .Va DESTDIR defaults to the empty string. +If set, +.Va DESTDIR +must specify an absolute path. .It Va MAKEOBJDIRPREFIX Defines the prefix for directory names in the tree of built objects. Defaults to @@ -496,6 +543,8 @@ and not via or .Pa /etc/src.conf or the command line. +.Va MAKEOBJDIRPREFIX +must specify an absolute path. .It Va WITHOUT_WERROR If defined, compiler warnings will not cause the build to halt, even if the makefile says otherwise. @@ -509,12 +558,38 @@ Additionally, builds in are influenced by the following .Xr make 1 variables: -.Bl -tag -width ".Va SUBDIR_OVERRIDE" +.Bl -tag -width ".Va LOCAL_MODULES_DIR" +.It Va CROSS_TOOLCHAIN +Requests use of an external toolchain to build either the world or kernel. +This value of this variable can either be the full path to a file, +or the base name of a file in +.Pa ${LOCALBASE}/share/toolchains . +The file should be a make file which sets variables to request an external +toolchain such as +.Va XCC . +.Pp +External toolchains are available in ports for both LLVM and GCC/binutils. +For external toolchains available in ports, +.Va CROSS_TOOLCHAIN +should be set to the name of the package. +LLVM toolchain packages use the name llvm<major version>. +GCC toolchains provide separate packages for each architecture and use the +name ${MACHINE_ARCH}-gcc<major version>. +.It Va INSTKERNNAME +If set, specify an alternative name to build and install for the various +kernel make targets. .It Va KERNCONF Overrides which kernel to build and install for the various kernel make targets. It defaults to .Cm GENERIC . +.It Va KERNBUILDDIR +Overrides the default directory to get all the opt_*.h files for +building a kernel module. +Useful for stand-alone modules that depend on +.Xr config 8 +options. +Automatically set for modules built with a kernel. .It Va KERNCONFDIR Overrides the directory in which .Va KERNCONF @@ -537,6 +612,9 @@ then .Va KERNCONF is set to the value of .Va KERNFAST . +.It Va KODIR +If set, +this variable specifies an alternative directory to install the kernel. .It Va LOCAL_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the @@ -596,6 +674,24 @@ If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm cross-tools target. +.It Va OBJROOT +The object directory root is defined as +.Pa ${OBJDIR}/${SRCDIR}/ . +See +.Pa share/mk/src.sys.obj.mk . +.It Va PKG_FORMAT +Specify a package compression format when building +.Xr freebsd-base 7 +packages. +Default: +.Ql tzst . +Consider using +.Ql tar +to disable compression. +Accepted options are documented in the +.Fl f +description of +.Xr pkg-create 8 . .It Va PORTS_MODULES A list of ports with kernel modules that should be built and installed as part of the @@ -603,8 +699,15 @@ as part of the and .Cm installkernel process. -.Bd -literal -offset indent -make PORTS_MODULES=emulators/virtualbox-ose-kmod kernel +This is currently incompatible with building +.Xr freebsd-base 7 +packages. +Each port must be specified as +.Ar category Ns Li / Ns Ar port Ns Op Li @ Ns Ar flavor , +e.g. +.Bd -literal +PORTS_MODULES=graphics/gpu-firmware-intel-kmod@kabylake +PORTS_MODULES+=graphics/drm-66-kmod .Ed .It Va LOCAL_MODULES A list of external kernel modules that should be built and installed @@ -627,6 +730,13 @@ Specify a file to override the default The src.conf file controls the components to build. See .Xr src.conf 5 +.It Va REPODIR +The root directory used to create the package repository for building +.Xr packages 7 . +Defaults to +.Pa ${OBJROOT}/repo/ . +This can also be set in +.Xr src-env.conf 5 . .It Va STRIPBIN Command to use at install time when stripping binaries. Be sure to add any additional tools required to run @@ -656,7 +766,7 @@ and will only build the specified directory as was done historically. When combined with .Cm buildworld -it is necesarry to override +it is necessary to override .Va LOCAL_LIB_DIRS with any custom directories containing libraries. This allows building a subset of the system in the same way as @@ -713,7 +823,7 @@ using the .Fl D option of .Xr make 1 : -.Bl -tag -width ".Va -DNO_KERNELCONFIG" +.Bl -tag -width ".Va LOADER_DEFAULT_INTERP" .It Va LOADER_DEFAULT_INTERP Defines what interpreter the default loader program will have. Valid values include @@ -783,6 +893,10 @@ If set, the libraries phase will be skipped. If set, no object directories will be created. This should only be used if object directories were created in a previous build and no new directories are connected. +.It Va UNIVERSE_TOOLCHAIN +Requests use of the toolchain built as part of the +.Cm universe +target as an external toolchain. .It Va WORLDFAST If set, the build target .Cm buildworld @@ -812,7 +926,7 @@ Builds using the and related targets are influenced by the following .Xr make 1 variables: -.Bl -tag -width ".Va MAKE_JUST_KERNELS" +.Bl -tag -width ".Va USE_GCC_TOOLCHAINS" .It Va JFLAG Pass the value of this variable to each .Xr make 1 @@ -834,6 +948,15 @@ target for each supported architecture instead of the default action of building a world and one or more kernels. This variable implies .Va WITHOUT_KERNELS . +.It Va USE_GCC_TOOLCHAINS +Use external GCC toolchains to build the requested targets. +If the required toolchain package for a supported architecture is not installed, +the build for that architecture is skipped. +.Pp +A specific version of GCC can be used by setting the value of this variable +to the desired version +.Pq for example, Dq gcc14 ; +otherwise a default version of GCC is used. .It Va TARGETS Only build the listed targets instead of each supported architecture. .It Va EXTRA_TARGETS @@ -850,30 +973,159 @@ fringe uses that do not have a wide appeal. .It Pa /usr/doc/share/mk/doc.project.mk .It Pa /usr/ports/Mk/bsd.port.mk .It Pa /usr/ports/Mk/bsd.sites.mk -.It Pa /usr/share/examples/etc/make.conf .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 +.Xr make 1 +infrastructure for each tree +.It Pa /usr/ports/UPDATING +.It Pa /usr/src/UPDATING +notable changes in each tree +.It Pa /usr/share/examples/etc/make.conf +example +.Xr make.conf 5 +.It Pa /etc/src.conf +src build configuration, see +.Xr src.conf 5 .El .Sh EXAMPLES -For an -.Dq approved -method of updating your system from the latest sources, please see the -.Sx COMMON ITEMS -section in -.Pa src/UPDATING . +This section describes best practices for common situations. +When manual intervention is necessary, it will be mentioned in +.Pa UPDATING . +Make sure you have full backups before proceeding! +.Ss Example 1: Build and upgrade system in place +If using installed drivers such as graphics or virtual machine guest +drivers, check out the +.Xr ports 7 +tree, and specify the drivers in +.Xr src.conf 5 +so they are built and installed automatically after the kernel: +.Bd -literal -offset indent +git clone https://git.FreeBSD.org/ports.git /usr/ports +cat << EOF >> /etc/src.conf +PORTS_MODULES+=graphics/drm-kmod emulators/virtualbox-ose-kmod +EOF +.Ed .Pp -The following sequence of commands can be used to cross-build the -system for the armv6 architecture on an amd64 host: +Check out the CURRENT branch, build it, and install, +overwriting the current system: .Bd -literal -offset indent +git clone https://git.FreeBSD.org/src.git /usr/src cd /usr/src -make TARGET_ARCH=armv6 buildworld buildkernel -make TARGET_ARCH=armv6 DESTDIR=/clients/arm installworld installkernel +make buildworld buildkernel +make installkernel +shutdown -r now .Ed -.Sh HISTORY -The -.Nm -manpage first appeared in -.Fx 4.3 . +.Pp +For major version upgrades, boot into single-user mode. +After restarting, install userspace, and merge configurations. +After verifying that you do not need them, delete old files +and libraries: +.Bd -literal -offset indent +cd /usr/src +etcupdate -p +make installworld +etcupdate -B +make delete-old delete-old-libs +shutdown -r now +.Ed +.Ss Example 2: Build and upgrade a custom kernel in place +Create a custom kernel configuration, +.Va MYKERNEL , +by including an existing configuration and using +.Cm device Ns / Ns Cm nodevice +and +.Cm options Ns / Ns Cm nooption +to select and configure components: +.Bd -literal -offset indent +cd /usr/src +cat << EOF > sys/amd64/conf/MYKERNEL +include GENERIC +ident MYKERNEL +nodevice sound +EOF +.Ed +.Pp +After creating the new kernel configuration, build a fresh toolchain, +build the kernel, and install it, moving the old kernel to +.Pa /boot/kernel.old/ : +.Bd -literal -offset indent +make kernel-toolchain +make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=MYKERNEL +make -DALWAYS_CHECK_MAKE installkernel KERNCONF=MYKERNEL +shutdown -r now +.Ed +.Pp +To build the kernel to an alternate location, use the +.Va INSTKERNNAME +variable and boot it once to test via +.Xr nextboot 8 : +.Bd -literal -offset indent +make installkernel KERNCONF=MYKERNEL INSTKERNNAME=testkernel +nextboot -k testkernel +shutdown -r now +.Ed +.Ss Example 3: Build and upgrade a single piece of userspace +Rebuild and reinstall a single piece of userspace, in this case +.Xr ls 1 : +.Bd -literal -offset indent +cd /usr/src/bin/ls +make clean all +make install +.Ed +.Ss Example 4: Build and upgrade a loadable kernel module +Rebuild and reinstall a single loadable kernel module, in this case +.Xr sound 4 : +.Bd -literal -offset indent +cd /usr/src/sys/modules/sound +make all install clean cleandepend KMODDIR=/boot/kernel +.Ed +.Ss Example 5: Quickly rebuild a kernel in place +Quickly rebuild and reinstall the kernel, only recompiling the files +changed since last build; note that this will only work if the full +kernel build has been completed in the past, not on a fresh source tree: +.Bd -literal -offset indent +cd /usr/src +make kernel KERNFAST=1 +.Ed +.Ss Example 6: Cross-compiling for different architectures +To rebuild parts of +.Fx +for another CPU architecture, +first prepare your source tree by building the cross-toolchain: +.Bd -literal -offset indent +cd src +make toolchain TARGET_ARCH=aarch64 +.Ed +.Pp +The following sequence of commands can be used to cross-build the system +for the arm64 (aarch64) architecture on a different host architecture, +such as amd64: +.Bd -literal -offset indent +cd /usr/src +make TARGET_ARCH=aarch64 buildworld buildkernel +make TARGET_ARCH=aarch64 DESTDIR=/armclient installworld installkernel +.Ed +.Pp +Afterwards, to build and install a single piece of userspace, use: +.Bd -literal -offset indent +cd src/bin/ls +make buildenv TARGET_ARCH=aarch64 +make clean all install DESTDIR=/armclient +.Ed +.Pp +Likewise, to quickly rebuild and reinstall the kernel, use: +.Bd -literal -offset indent +cd src +make buildenv TARGET_ARCH=aarch64 +make kernel KERNFAST=1 DESTDIR=/armclient +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It Bad system call (core dumped) +.It rescue/sh check failed, installation aborted +.Pp +The kernel was not updated due to incorrect build procedure. +Study the examples above. .Sh SEE ALSO .Xr cc 1 , .Xr install 1 , @@ -881,14 +1133,40 @@ manpage first appeared in .Xr make.conf 5 , .Xr src.conf 5 , .Xr arch 7 , +.Xr development 7 , +.Xr freebsd-base 7 , .Xr pkg 7 , .Xr ports 7 , .Xr release 7 , .Xr tests 7 , .Xr config 8 , .Xr etcupdate 8 , -.Xr mergemaster 8 , -.Xr reboot 8 , +.Xr nextboot 8 , .Xr shutdown 8 +.Sh HISTORY +The +.Nm +manpage first appeared in +.Fx 4.3 . .Sh AUTHORS .An Mike W. Meyer Aq Mt mwm@mired.org +.Sh CAVEATS +Old objects can cause obscure build problems; try +.Ql make cleandir cleandir . +.Pp +Environment poisioning can cause obscure build problems; try prefixing +.Xr make 1 +commands with +.Ql env -i +.Pp +When doing a major release upgrade, +booting into single user mode for +.Cm installworld +is required. +.Pp +Updating the boot +.Xr loader 8 +is architecture specific. +Consult +.Xr boot 8 +for your architecture for more details. diff --git a/share/man/man7/c.7 b/share/man/man7/c.7 index f8943cd9ca29..c95bab1c1f19 100644 --- a/share/man/man7/c.7 +++ b/share/man/man7/c.7 @@ -22,9 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd April 20, 2021 +.Dd November 4, 2024 .Dt C 7 .Os .Sh NAME @@ -36,7 +34,8 @@ .Nm c99 , .Nm c11 , .Nm c17 , -.Nm c2x +.Nm c23 , +.Nm c2y .Nd The C programming language .Sh DESCRIPTION C is a general purpose programming language, which has a strong connection @@ -114,9 +113,12 @@ development of the language did not stop. .Pp The ISO C standard was later extended with an amendment as ISO/IEC 9899/AMD1 in 1995. -This contained, for example, the wide-character support in <wchar.h> and -<wctype.h>, and also restricted character set support via diagraphs and -<iso646.h>. +This contained, for example, the wide-character support in +.In wchar.h +and +.In wctype.h , +and also restricted character set support via diagraphs and +.In iso646.h . This amendment is usually referred to as C95. Two technical corrigenda were also published: Technical Corrigendum 1 as ISO/IEC 9899/COR1 in 1994 and Technical Corrigendum 2 as ISO/IEC 9899/COR2 @@ -132,18 +134,23 @@ The improvements include (but are not limited to) the following: .Bl -bullet -offset indent .It digraphs, trigraphs, and alternative spellings for the operators that -use non-ISO646 characters in <iso646.h> +use non-ISO646 characters in +.In iso646.h .It -extended multibyte and wide character library support in <wchar.h> and -<wctype.h> +extended multibyte and wide character library support in +.In wchar.h +and +.In wctype.h .It variable length arrays .It flexible array members .It -complex (and imaginary) number arithmetic support in <complex.h> +complex (and imaginary) number arithmetic support in +.In complex.h .It -type-generic math macros in <tgmath.h> +type-generic math macros in +.In tgmath.h .It the long long int type and library functions .It @@ -159,15 +166,24 @@ BCPL style single-line comments .It allow mixed declarations and code .It -the vscanf family of functions in <stdio.h> and <wchar.h> +the +.Fn vscanf +family of functions in +.In stdio.h +and +.In wchar.h .It allow trailing comma in enum declaration .It inline functions .It -the snprintf family of functions in <stdio.h> +the +.Fn snprintf +family of functions in +.In stdio.h .It -boolean type and macros in <stdbool.h> +boolean type and macros in +.In stdbool.h .It empty macro arguments .It @@ -175,7 +191,8 @@ _Pragma preprocessing operator .It __func__ predefined identifier .It -va_copy macro in <stdarg.h> +va_copy macro in +.In stdarg.h .It additional strftime conversion specifiers .El @@ -187,24 +204,34 @@ and ISO/IEC 9899:1999/COR3:2007. The improvements include (but are not limited to) the following: .Bl -bullet -offset indent .It -support for multiple threads of execution and atomic operations in <threads.h> -and <stdatomic.h> +support for multiple threads of execution and atomic operations in +.In threads.h +and +.In stdatomic.h .It -additional floating-point characteristic macros in <float.h> +additional floating-point characteristic macros in +.In float.h .It -querying and specifying alignment of objects in <stdalign.h> and <stdlib.h> +querying and specifying alignment of objects in +.In stdalign.h +and +.In stdlib.h .It -Unicode character types and functions in <uchar.h> +Unicode character types and functions in +.In uchar.h .It type-generic expressions .It -static assertions in <assert.h> +static assertions in +.In assert.h .It anonymous structures and unions .It -remove the gets function from <stdio.h> +remove the gets function from +.In stdio.h .It -add the aligned_alloc, at_quick_exit, and quick_exit functions in <stdlib.h> +add the aligned_alloc, at_quick_exit, and quick_exit functions in +.In stdlib.h .El .Pp C11 was later superseded by ISO/IEC 9899:2018, also known as C17 which was @@ -213,17 +240,154 @@ It incorporates the Technical Corrigendum 1 (ISO/IEC 9899:2011/COR1:2012) which was published in 2012. It addressed defects and deficiencies in C11 without introducing new features, only corrections and clarifications. -Since there were no major changes in C17, the current standard for -Programming Language C, is still considered C11 \(em ISO/IEC 9899:2011, published -2011-12-08. .Pp -The next standard, the fifth, is currently referred to as C2x and is scheduled -to be adopted by the end of 2021, with a publication date of 2022. -When published, it will cancel and replace the fourth edition, ISO/IEC -9899:2018. +C23, formally ISO/IEC 9899:2024, is the current standard with significant +updates that supersede C17 (ISO/IEC 9899:2018). +The standardization effort began in 2016, informally as C2x, with the first +WG14 meeting in 2019, and was officially published on October 31, 2024. +C23 was originally anticipated for an earlier release, but the timeline was +extended due to COVID-19 pandemic. +With C23, the value of __STDC_VERSION__ has been updated from 201710L to +202311L. +Key changes include (but are not limited to) the following: +.Bl -bullet -offset indent +.It +Add null pointer type nullptr_t and the nullptr keyword +.It +Add constexpr keyword as a storage-class specifier for objects +.It +Redefine the usage of the auto keyword to support type inference while also +retaining its previous functionality as a storage-class specifier when used +with a type +.It +Add %b binary conversion specifier to the +.Fn printf +and +.Fn scanf +function families +.It +Add binary conversion support (0b and 0B) to the +.Fn strtol +and +.Fn wcstol +function families +.It +Add the #embed directive for binary resource inclusion and __has_embed to +check resource availability with preprocessor directives +.It +Add the #warning directive for diagnostics +.It +Add the #elifdef and #elifndef directives +.It +Add the u8 prefix for character literals to represent UTF-8 encoding, +compatible with C++17 +.It +Add the char8_t type for UTF-8 encoded data and update the types of u8 +character constants and string literals to char8_t +.It +Add functions +.Fn mbrtoc8 +and +.Fn c8rtomb +to convert between narrow multibyte +characters and UTF-8 encoding +.It +Define all char16_t strings and literals as UTF-16 encoded and char32_t +strings and literals as UTF-32 encoded unless specified otherwise +.It +Allow storage-class specifiers within compound literals +.It +Support the latest IEEE 754 standard, ISO/IEC 60559:2020, with binary and +(optional) decimal floating-point arithmetic +.It +Add single-argument _Static_assert for compatibility with C++17 +.It +Add _Decimal32, _Decimal64, _Decimal128 keywords for (optional) decimal +floating-point arithmetic +.It +Add digit separator ' (the single quote character) for literals +.It +Enable specification of the underlying type of an enum +.It +Standardize the +.Fn typeof +operator +.It +Add +.Fn memset_explicit +in +.In string.h +to securely erase sensitive data +regardless of optimizations +.It +Add +.Fn memccpy +in +.In string.h +for efficient string concatenation +.It +Add +.Fn memalignment +in +.In stdlib.h +to determine pointer alignment +.It +Add +.Fn strdup +and +.Fn strndup +in +.In string.h +to allocate string copies +.It +Introduce bit utility functions, macros, and types in the new header +.In stdbit.h +.It +Add +.Fn timegm +in +.In time.h +for converting time structures to calendar time +values +.It +Add __has_include for header availability checking via preprocessor +directives +.It +Add __has_c_attribute to check attribute availability via preprocessor +directives +.It +Add _BitInt(N) and unsigned _BitInt(N) for bit-precise integers, and +BITINT_MAXWIDTH for maximum bit width +.It +Elevate true and false to proper keywords (previously macros from +.In stdbool.h ) +.It +Add keywords alignas, alignof, bool, static_assert, thread_local; previously +defined keywords remain available as alternative spellings +.It +Enable zero initialization with {} (including initialization of VLAs) +.It +Introduce C++11 style attributes using [[]], with adding [[deprecated]], +[[fallthrough]], [[maybe_unused]], [[nodiscard]], and [[noreturn]] +.It +Deprecate _Noreturn, noreturn, header +.In stdnoreturn.h +features introduced +in C11 +.It +Remove trigraph support +.It +Remove K&R function definitions and declarations +.It +Remove non-two's-complement representations for signed integers +.El .Pp -Some useful features have been provided as extensions by some compilers, but -they cannot be considered as standard features. +The next version of the C Standard, informally named C2y, is anticipated +to release within the next six years, targeting 2030 at the latest. +A charter for C2y is still being drafted and discussed, with several +papers under debate from the January 2024 meeting in Strasbourg, France +indicating that this new version may address long-standing requests and +deficiencies noted by the C community, while preserving its core strengths. .Pp ISO/IEC JTC1/SC22/WG14 committee is responsible for the ISO/IEC 9899, C Standard. @@ -351,6 +515,11 @@ C Standard. .%A ISO/IEC .%T 9899:2018 (aka C17) .Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:2024 (aka C23) +.Re .Sh HISTORY This manual page first appeared in .Fx 9.0 . @@ -358,8 +527,6 @@ This manual page first appeared in .An -nosplit This manual page was originally written by .An Gabor Kovesdan Aq Mt gabor@FreeBSD.org . -It was updated for -.Fx 14.0 -by +It was updated by .An Faraz Vahedi Aq Mt kfv@kfv.io with information about more recent C standards. diff --git a/share/man/man7/clocks.7 b/share/man/man7/clocks.7 index 06b41ed551ca..3a218f844450 100644 --- a/share/man/man7/clocks.7 +++ b/share/man/man7/clocks.7 @@ -24,8 +24,6 @@ .\" 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. -.\" -.\" $FreeBSD$ .\" " .Dd January 18, 2008 .Dt CLOCKS 7 diff --git a/share/man/man7/crypto.7 b/share/man/man7/crypto.7 index 941650d16371..37c441562fa4 100644 --- a/share/man/man7/crypto.7 +++ b/share/man/man7/crypto.7 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd January 11, 2022 .Dt CRYPTO 7 .Os diff --git a/share/man/man7/d.7 b/share/man/man7/d.7 new file mode 100644 index 000000000000..4b00d3d71c79 --- /dev/null +++ b/share/man/man7/d.7 @@ -0,0 +1,289 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd October 28, 2025 +.Dt D 7 +.Os +.Sh NAME +.Nm D +.Nd DTrace scripting language overview +.Sh SYNOPSIS +.Sm off +.Ar provider Cm \&: +.Ar module Cm \&: +.Ar function Cm \&: +.Ar name +.Sm on +.Sm off +.Oo +.Oo +.Cm / +.Ar predicate +.Cm / +.Sm on +.Oc +.Cm \&{ Ns Ar action Ns Cm \&} +.Oc +.Sh DESCRIPTION +.Nm D +is the +.Xr dtrace 1 +scripting language. +This manual provides a brief reference of the +.Nm +language and scripting. +.Pp +This manual page serves as a short reference of the language. +Refer to books listed in +.Sx SEE ALSO +for a complete reference. +.Sh PROBE'S DESCRIPTION +A probe's description consists of four elements: +.Sm off +.D1 Ar provider Ns Cm \&: Ns Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on +.Pp +The exact meaning of +.Ar module , +.Ar function , +and +.Ar name +depends on +.Ar provider . +.Sh USER-DEFINED VARIABLE TYPES +.Bl -column "thread-local" "Syntax" +.It Sy Type Ta Sy Syntax +.It global Ta Va variable_name +.It aggregate Ta Sy @ Ns Va variable_name +.It thread-local Ta Sy self-> Ns Va variable_name +.It clause-local Ta Sy this-> Ns Va variable_name +.El +.Pp +.Em Tips : +.Bl -dash -compact +.It +Always use the variable type with the smallest scope +to minimize processing overhead. +.It +Use aggregate variables instead of global variables when possible. +Aggregate variables are multi-CPU safe in contrast to global variables. +.El +.Sh BUILT-IN VARIABLES +.Ss Probe Arguments +.Bl -tag -width "arg0, ..., arg9" +.It Va args[] +The array of typed probe arguments. +.It Va arg0 , ... , arg9 +The untyped probe arguments represented as 64-bit unsigned integers. +Only the first ten arguments are available this way. +.El +.Ss Probe Information +.Bl -tag -width probeprov +.It Va epid +The enabled probe ID which uniquely identifies an enabled probe. +An enabled probe is defined by its probe ID, its predicates, and its actions. +.It Va id +The probe ID which uniquely identifies a probe available to DTrace. +.It Va probeprov +The +.Ar provider +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probemod +The +.Ar module +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probefunc +The +.Ar function +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probename +The +.Ar name +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.El +.Ss Process Information +.Bl -tag -width execname +.It Va execargs +The process arguments. +Effectively, +.Ql curthread->td_proc->p_args . +.It Va execname +The name of the current process. +Effectively, +.Ql curthread->td_proc->p_comm . +.It Va gid +The group ID of the current process. +.It Va pid +The process ID of the current process. +.It Va ppid +The parent process ID of the current process. +.It Va uid +The user ID of the current process. +.El +.Ss Thread Information +.Bl -tag -width curlwpsinfo +.It Va uregs[] +The saved user-mode register values. +.It Va cpu +The ID of the current CPU. +.It Va stackdepth +The kernel stack frame depth. +.It Va ustackdepth +The userspace counterpart of +.Va stackdepth . +.It Va tid +The thread ID. +Depending on the context, +this can be either the ID of a kernel thread or a thread in a user process. +.It Va errno +The +.Xr errno 2 +value of the last system call performed by the current thread. +.It Va curlwpsinfo +A pointer to the +.Vt lwpsinfo_t +representation of the current thread. +Refer to +.Xr dtrace_proc 4 +for more details. +.It Va curpsinfo +A pointer to the +.Vt psinfo_t +representation of the current process. +Refer to +.Xr dtrace_proc 4 +for more details. +.It Va curthread +A pointer to the thread struct that is currently on-CPU. +E.g., +.Ql curthread->td_name +returns the thread name. +The +.In sys/proc.h +header documents all members of +.Vt struct thread . +.It Va caller +The address of the kernel thread instruction at the time of execution +of the current probe. +.It Va ucaller +The userspace counterpart of +.Va caller . +.El +.Ss Timestamps +.Bl -tag -width walltimestamp +.It Va timestamp +The number of nanoseconds since boot. +Suitable for calculating relative time differences of elapsed time and latency. +.It Va vtimestamp +The number of nanoseconds that the current thread spent on CPU. +The counter is not increased during handling of a fired DTrace probe. +Suitable for calculating relative time differences of on-CPU time. +.It Va walltimestamp +The number of nanoseconds since the Epoch +.Pq 1970-01-01T00+00:00 . +Suitable for timestamping logs. +.El +.Sh BUILT-IN FUNCTIONS +.Ss Aggregation Functions +.Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)" +.It Fn avg value +Average +.It Fn count +Count +.It Fn llquantize value factor low high nsteps +Log-linear quantization +.It Fn lquantize value low high nsteps +Linear quantization +.It Fn max value +Maximum +.It Fn min value +Minimum +.It Fn quantize value +Power-of-two frequency distribution +.It Fn stddev value +Standard deviation +.It Fn sum value +Sum +.El +.Ss Kernel Destructive Functions +By default, +.Xr dtrace 1 +does not permit the use of destructive actions. +.Bl -tag -width "chill(nanoseconds)" +.It Fn breakpoint +Set a kernel breakpoint and transfer control to +the +.Xr ddb 4 +kernel debugger. +.It Fn chill nanoseconds +Spin on the CPU for the specified number of +.Fa nanoseconds . +.It Fn panic +Panic the kernel. +.El +.Sh FILES +.Bl -tag -width /usr/share/dtrace +.It Pa /usr/share/dtrace +DTrace scripts shipped with +.Fx +base. +.El +.Sh SEE ALSO +.Xr awk 1 , +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%D 2008 +.%U https://illumos.org/books/dtrace/ +.Re +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Rs +.%A George Neville-Neil +.%A Jonathan Anderson +.%A Graeme Jenkinson +.%A Brian Kidney +.%A Domagoj Stolfa +.%A Arun Thomas +.%A Robert N. M. Watson +.%C Cambridge, United Kingdom +.%D August 2018 +.%T Univeristy of Cambridge Computer Laboratory +.%R OpenDTrace Specification version 1.0 +.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf +.Re +.Sh HISTORY +This manual page first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh BUGS +The +.Va cwd +variable which typically provides the current working directory is +not supported on +.Fx +at the moment. diff --git a/share/man/man7/development.7 b/share/man/man7/development.7 index 346772b4fbb0..348302a50ee7 100644 --- a/share/man/man7/development.7 +++ b/share/man/man7/development.7 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 2018 Edward Tomasz Napierala <trasz@FreeBSD.org> .\" .\" Redistribution and use in source and binary forms, with or without @@ -21,9 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd July 21, 2022 +.Dd September 24, 2025 .Dt DEVELOPMENT 7 .Os .Sh NAME @@ -39,14 +40,14 @@ Doc is the documentation, such as the Handbook. To read more, see: .Pp -.Lk https://www.FreeBSD.org/doc/en/books/fdp-primer/ +.Lk https://docs.FreeBSD.org/en/books/fdp-primer/ .Pp Ports, described further in .Xr ports 7 , are the way to build, package, and install third party software. To read more, see: .Pp -.Lk https://www.FreeBSD.org/doc/en/books/porters-handbook/ +.Lk https://docs.FreeBSD.org/en/books/porters-handbook/ .Pp The last one, src, revolves around the source code for the base system, consisting of the kernel, and the libraries and utilities commonly called @@ -55,7 +56,7 @@ the world. The Committer's Guide, describing topics relevant to all committers, can be found at: .Pp -.Lk https://www.FreeBSD.org/doc/en/articles/committers-guide/ +.Lk https://docs.freebsd.org/en/articles/committers-guide/ .Pp .Fx src development takes place in the project-hosted @@ -69,28 +70,30 @@ The push URL is: .Pp There is also a list of public, read-only Git mirrors at: .Pp -.Lk https://docs.freebsd.org/en/books/handbook/mirrors/#external-mirrors +.Lk https://docs.FreeBSD.org/en/books/handbook/mirrors/#external-mirrors .Pp The .Ql main Git branch represents CURRENT; -all changes are first committed to CURRENT and then usually cherry-picked -back to STABLE, which refers to Git branches such as -.Ql stable/13 . +all changes are first committed to CURRENT and then usually +cherry-picked back to STABLE, which refers to Git branches such as +.Ql stable/14 . Every few years a new STABLE is branched from CURRENT, with an incremented major version number. -Releases are then branched off STABLE and numbered with consecutive minor -numbers. +Releases are then branched off STABLE and numbered with consecutive +minor numbers such as +.Ql releng/14.3 .Pp -Layout of the source tree is described in -.Xr hier 7 . +The layout of the source tree is described in its +.Pa README.md +file. Build instructions can be found in .Xr build 7 and .Xr release 7 . Kernel programming interfaces (KPIs) are documented in section 9 manual pages; use -.Ql "apropos -s 9 ." +.Ql apropos -s 9 \&. for a list. Regression test suite is described in .Xr tests 7 . @@ -105,76 +108,58 @@ such as freebsd-arch@ and freebsd-hackers@: To get your patches integrated into the main .Fx repository use Phabricator; -it is a code review tool that allows other developers to review the changes, -suggest improvements, and, eventually, allows them to pick up the change and -commit it: +it is a code review tool that allows other developers to +review the changes, suggest improvements, and, eventually, +allows them to pick up the change and commit it: .Pp .Lk https://reviews.FreeBSD.org .Pp +Or Github: +.Pp +.Lk https://github.com/freebsd +.Pp To check the latest .Fx build and test status of CURRENT and STABLE branches, the continuous integration system is at: .Pp .Lk https://ci.FreeBSD.org -.Pp -.Sh EXAMPLES -Check out the CURRENT branch, build it, and install, overwriting the current -system: -.Bd -literal -offset indent -git clone https://git.FreeBSD.org/src.git src -cd src -make -sj8 buildworld buildkernel installkernel -shutdown -r now -.Ed -.Pp -After reboot: -.Bd -literal -offset indent -cd src -make -j8 installworld -reboot -.Ed -.Pp -Rebuild and reinstall a single piece of userspace, in this -case -.Xr ls 1 : -.Bd -literal -offset indent -cd src/bin/ls -make clean all install -.Ed -.Pp -Quickly rebuild and reinstall the kernel, only recompiling the files -changed since last build; note that this will only work if the full kernel -build has been completed in the past, not on a fresh source tree: -.Bd -literal -offset indent -cd src -make -sj8 kernel KERNFAST=1 -.Ed -.Pp -To rebuild parts of +.Sh FILES +.Bl -tag -compact -width "/usr/ports/devel/freebsd-git-devtools" +.It Pa /usr/src/CONTRIBUTING.md .Fx -for another CPU architecture, -first prepare your source tree by building the cross-toolchain: -.Bd -literal -offset indent -cd src -make -sj8 toolchain TARGET_ARCH=aarch64 -.Ed -.Pp -Afterwards, to build and install a single piece of userspace, use: -.Bd -literal -offset indent -cd src/bin/ls -make buildenv TARGET_ARCH=aarch64 -make clean all install DESTDIR=/clients/arm -.Ed -.Pp -Likewise, to quickly rebuild and reinstall the kernel, use: -.Bd -literal -offset indent -cd src -make buildenv TARGET_ARCH=aarch64 -make -sj8 kernel KERNFAST=1 DESTDIR=/clients/arm -.Ed +contribution guidelines +.It Pa /usr/src/tools/tools/git/git-arc.sh +Phabricator review tooling +.It Pa /usr/ports/devel/freebsd-git-devtools +Phabricator review tooling as a port +.El +.Sh EXAMPLES +Apply a patch from Github pull #1234, using +.Pa devel/gh : +.Pp +.Dl gh pr checkout 1234 +.Pp +Apply a patch from Phabricator review D1234, using +.Xr git-arc 1 : +.Pp +.Dl git arc patch -c D1234 +.Pp +Apply a manually downloaded +.Xr git-format-patch 1 , +.Pa draft.patch , +from Bugzilla or mail: +.Pp +.Dl git am draft.patch +.Pp +Apply a manually downloaded patch, +.Pa draft.diff , +from Bugzilla or mail: +.Pp +.Dl git apply draft.diff .Sh SEE ALSO .Xr git 1 , +.Xr git-arc 1 , .Xr witness 4 , .Xr build 7 , .Xr hier 7 , @@ -188,8 +173,7 @@ The .Nm manual page was originally written by .An Matthew Dillon Aq Mt dillon@FreeBSD.org -and first appeared -in +and first appeared in .Fx 5.0 , December 2002. It was since extensively modified by diff --git a/share/man/man7/environ.7 b/share/man/man7/environ.7 index 9a77100ff6d3..51fb6544fc5a 100644 --- a/share/man/man7/environ.7 +++ b/share/man/man7/environ.7 @@ -25,10 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)environ.7 8.3 (Berkeley) 4/19/94 -.\" $FreeBSD$ -.\" -.Dd August 5, 2020 +.Dd September 3, 2023 .Dt ENVIRON 7 .Os .Sh NAME @@ -67,6 +64,13 @@ are documented in the section of the appropriate manual page. .Sh ENVIRONMENT .Bl -tag -width LD_LIBRARY_PATH +.It Ev ARCHLEVEL +On +.Em amd64 , +controls the level of SIMD enhancements used. +See +.Xr simd 7 +for details. .It Ev BLOCKSIZE The size of the block units used by several disk-related commands, most notably @@ -197,7 +201,7 @@ The full pathname of the user's login shell. .It Ev TERM The kind of terminal for which output is to be prepared. This information is used by commands, such as -.Xr nroff 1 +.Xr nroff 1 Pq Pa ports/textproc/groff or .Xr plot 1 which may exploit special terminal capabilities. @@ -306,7 +310,8 @@ built-in command in .Xr setlocale 3 , .Xr system 3 , .Xr termcap 3 , -.Xr termcap 5 +.Xr termcap 5 , +.Xr simd 7 .Sh HISTORY The .Nm diff --git a/share/man/man7/ffs.7 b/share/man/man7/ffs.7 deleted file mode 100644 index 13924b936a9e..000000000000 --- a/share/man/man7/ffs.7 +++ /dev/null @@ -1,330 +0,0 @@ -.\" Copyright (c) 2001 Networks Associates Technology, Inc. -.\" All rights reserved. -.\" -.\" This software was developed for the FreeBSD Project by Chris -.\" Costello at Safeport Network Services and NAI Labs, the Security -.\" Research Division of Network Associates, Inc. under DARPA/SPAWAR -.\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS -.\" research program. -.\" -.\" 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 AUTHORS 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 AUTHORS 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. -.\" -.\" $FreeBSD$ -.\" -.Dd May 3, 2020 -.Dt FFS 7 -.Os -.Sh NAME -.Nm ffs -.Nd Berkeley fast file system -.Sh SYNOPSIS -In the kernel configuration file: -.Cd "options FFS" -.Cd "options QUOTA" -.Cd "options SOFTUPDATES" -.Cd "options SUIDDIR" -.Cd "options UFS_ACL" -.Cd "options UFS_DIRHASH" -.Cd "options UFS_EXTATTR" -.Cd "options UFS_EXTATTR_AUTOSTART" -.Cd "options UFS_GJOURNAL" -.Pp -In -.Xr fstab 5 : -.Bd -literal -compact -/dev/disk0a /mnt ufs rw 1 1 -.Ed -.Sh DESCRIPTION -The Berkeley fast file system -provides facilities to store file system data onto a disk device. -.Nm -has been optimized over the years -for speed and reliability -and is the default -.Fx -file system. -.Ss Quotas -.Bl -tag -width 2n -.It Cd "options QUOTA" -This option allows system administrators -to set limits on disk usage -on a per-user basis. -Quotas can be used only on file systems -mounted with the -.Cm quota -option; -see -.Xr quota 1 -and -.Xr edquota 8 . -.El -.Ss Soft Updates -.Bl -tag -width 2n -.It Cd "options SOFTUPDATES" -The soft updates feature tracks writes to the disk -and enforces metadata update dependencies -(e.g., updating free block maps) -to ensure that the file system remains consistent. -.Pp -To create a new file system with the soft updates -enabled, -use -.Xr newfs 8 -command: -.Pp -.D1 Nm newfs Fl U Ar fs -.Pp -.Ar fs -can be either a mount point listed in -.Xr fstab 5 -.Pq e.g. , Pa /usr , -or a disk device -.Pq e.g., Pa /dev/da0a . -.Pp -It is possible to enable soft updates on an -.Em unmounted -file system by using -.Xr tunefs 8 -command: -.Pp -.D1 Nm tunefs Fl n Cm enable Ar fs -.Pp -Soft updates can also add journaling that reduces the time spent by -.Xr fsck_ffs 8 -cleaning up a filesystem after a crash from several minutes to a few seconds. -The journal is placed in an inode named -.Pa .sujournal , -and is kept as a circular log of segments containing -records that describe metadata operations. -.Pp -To create a new file system with both the soft updates -and soft updates journaling enabled, -use the following command: -.Pp -.D1 Nm newfs Fl j Ar fs -.Pp -This runs -.Xr tunefs 8 -command after -.Xr newfs 8 -command with -.Fl U -flag enabled. -It is possible to enable soft updates journaling on an -.Em unmounted -file system by using -.Xr tunefs 8 -command: -.Pp -.D1 Nm tunefs Fl j Cm enable Ar fs -.Pp -This flag automatically enables the soft updates feature -when it is not enabled. -Note that this -.Xr tunefs 8 -command will fail if a file -.Pa .sujournal -already exists before enabling the soft updates journaling. -.El -.Ss File Ownership Inheritance -.Bl -tag -width 2n -.It Cd "options SUIDDIR" -For use in file sharing environments -on networks including -.Tn "Microsoft Windows" -and -.Tn "Apple Macintosh" -computers, -this option allows files on file systems -mounted with the -.Cm suiddir -option -to inherit the ownership of its directory, -i.e., -.Dq "if it's my directory, it must be my file." -.El -.Ss Access Control Lists -.Bl -tag -width 2n -.It Cd "options UFS_ACL" -Access control lists allow the association of -fine-grained discretionary access control information -with files and directories. -This option requires the presence of the -.Dv UFS_EXTATTR -option, and it is recommended that -.Dv UFS_EXTATTR_AUTOSTART -is included as well, -so that ACLs are enabled atomically upon mounting the file system. -.El -.Pp -In order to enable support for ACLs, -two extended attributes must be available in the -.Dv EXTATTR_NAMESPACE_SYSTEM -namespace: -.Pa posix1e.acl_access , -which holds the access ACL, -and -.Pa posix1e.acl_default , -which holds the default ACL for directories. -If you are using file system extended attributes, -the following commands may be used to -allocate space for and create the necessary EA backing files -for ACLs in the root of each file system. -In these examples, the root file system is used; -see -.Sx "Extended Attributes" -for more details. -.Bd -literal -offset indent -mkdir -p /.attribute/system -cd /.attribute/system -extattrctl initattr -p / 388 posix1e.acl_access -extattrctl initattr -p / 388 posix1e.acl_default -.Ed -.Pp -On the next mount of the root file system, -the attributes will be automatically started if -.Dv UFS_EXTATTR_AUTOSTART -is included in the kernel configuration, -and ACLs will be enabled. -.Ss Directory Hashing -.Bl -tag -width 2n -.It Cd "options UFS_DIRHASH" -Implements a hash-based lookup scheme for directories -in order to speed up accesses to very large directories. -.El -.Ss Extended Attributes -.Bl -tag -width 2n -.It Cd "options UFS_EXTATTR" -Extended attributes allow the association of -additional arbitrary metadata with files and directories, -which can be assigned and retrieved from userland -as well as from within the kernel; see -.Xr extattrctl 8 . -.It Cd "options UFS_EXTATTR_AUTOSTART" -If this option is defined, -.Nm -will search for a -.Pa .attribute -subdirectory of the file system root during the mount operation. -If found, extended attribute support will be -automatically started for that file system. -.El -.Ss GEOM-based Journaling -.Bl -tag -width 2n -.It Cd "options UFS_GJOURNAL" -Implements a block level journaling of a UFS file system, -which is for both data and metadata. -To enable this, -create a -.Xr gjournal 8 -GEOM provider for a block device by using the -following command: -.Pp -.D1 Nm gjournal label Ar da0 -.Pp -In this example, -.Pa /dev/da0 -is used as the target block device, -and -.Pa /dev/da0.journal -is created. -Then create a new file system by using -.Xr newfs 8 -with the block level journaling flag and mount it: -.Pp -.D1 Nm newfs Fl J Ar /dev/da0.journal -.D1 Nm mount Fl o Cm async Ar /dev/da0.journal Ar /mnt -.Pp -.Cm async -option is not mandatory but recommended for better performance -because the journaling guarantees the consistency of an -.Cm async -mount. -.Pp -It is also possible to enable the block level journaling -on an existing file system. -To do so, -use -.Xr gjournal 8 -utility to label the underlying block device and -.Xr tunefs 8 -utility to enable the block level journaling flag: -.Pp -.D1 Nm gjournal label Ar da0 -.D1 Nm tunefs Fl J Cm enable Ar /dev/da0.journal -.D1 Nm mount Fl o Cm async Ar /dev/da0.journal Ar /mnt -.El -.Ss Xr sysctl 8 MIBs -The following -.Xr sysctl 8 -MIBs are defined for use with -.Nm : -.Bl -hang -width ".Va vfs.ffs.doreallocblk" -.It Va vfs.ffs.doasyncfree -Asynchronously write out modified i-node and indirect blocks -upon reallocating file system blocks to be contiguous. -.Pq Default: 1 . -.It Va vfs.ffs.doreallocblks -Enable support for the rearrangement of blocks -to be contiguous. -.Pq Default: 1 . -.El -.Sh HISTORY -The -.Nm -manual page first appeared in -.Fx 4.5 . -.Sh SEE ALSO -.Xr quota 1 , -.Xr acl 3 , -.Xr extattr 3 , -.Xr edquota 8 , -.Xr extattrctl 8 , -.Xr fsck_ffs 8 , -.Xr sysctl 8 , -.Xr tunefs 8 -.Rs -.%A M. McKusick -.%A W. Joy -.%A S. Leffler -.%A R. Fabry -.%D August 1984 -.%T "A Fast File System for UNIX" -.%J "ACM Transactions on Computer Systems" -.%N 2 -.%V 3 -.%P 181-197 -.Re -.Rs -.%A M. McKusick -.%D June 2000 -.%T "Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem" -.%J "Proceedings of the Freenix Track at the 1999 Usenix Annual Technical Conference" -.%P 71-84 -.Re -.Rs -.%A M. McKusick -.%A J. Roberson -.%D May 2010 -.%T "Journaled Soft-updates" -.%J "BSD Canada Conference 2010 (BSDCan)" -.Re diff --git a/share/man/man7/firewall.7 b/share/man/man7/firewall.7 index 48558b21d5a8..041c66bdde40 100644 --- a/share/man/man7/firewall.7 +++ b/share/man/man7/firewall.7 @@ -21,8 +21,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd May 26, 2001 .Dt FIREWALL 7 .Os diff --git a/share/man/man7/freebsd-base.7 b/share/man/man7/freebsd-base.7 new file mode 100644 index 000000000000..f84cc7239a1d --- /dev/null +++ b/share/man/man7/freebsd-base.7 @@ -0,0 +1,189 @@ +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2025 Lexi Winter. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd September 25, 2025 +.Dt FREEBSD-BASE 7 +.Os +.Sh NAME +.\" .Nm pkgbase +.Nm freebsd-base +.Nd base system packages +.Sh DESCRIPTION +The +.Fx +base system may be installed as a set of +.Xr pkg 8 +packages, which supersedes the traditional method of installing using +.Xr tar 1 +archives. +.Pp +All base packages have names beginning with the string +.Dq "FreeBSD-" , +and have an origin beginning with +.Dq base/ . +In the default system configuration, the repository containing these +packages is called +.Dq FreeBSD-base , +but any name may be used. +The repository name can be used with +.Xr pkg 8 +to restrict package operations to the base system packages. +.Pp +Packages for all supported +.Fx +releases as well as active +.Dq STABLE +and +.Dq CURRENT +.\" re@ will provide their own repository before release, at which +.\" point this text will need updating. +branches are hosted on the Internet at +.Lk https://pkg.freebsd.org . +These packages are updated when new errata or security updates are +released (for supported release versions), or twice daily for +development branches. +.Pp +Alternatively, packages may be built from the system source tree +according to the instructions in +.Xr build 7 , +allowing the system to be updated from source code using packages. +.Sh PACKAGE ORGANISATION +To allow customisation of the installed system, each package is split +into several subpackages which contain different components of the +package. +For the package +.Sy FreeBSD-foo , +the following subpackages may be available: +.Bl -column "FreeBSD-foo-dev-lib32" "Description" +.It Sy "Package name" Ta Sy "Description" +.It FreeBSD-foo Ta Base files for the package (typically executables) +.It FreeBSD-foo-lib Ta Native runtime libraries +.It FreeBSD-foo-lib32 Ta 32-bit compatibility runtime libraries +.It FreeBSD-foo-dev Ta Development files (headers and static libraries) +.It FreeBSD-foo-dev-lib32 Ta 32-bit development files +.It FreeBSD-foo-dbg Ta Debugging symbols +.It FreeBSD-foo-man Ta Manual pages. +Manual pages are only packaged separately if the +.Sy WITH_MANSPLITPKG +.Xr src.conf 5 +option was enabled when building the system, which is not the default. +.El +.Pp +The exact set of available subpackages differs for each individual +package. For example, some packages may not provide any development +files, in which case the +.Sy -dev +subpackage is not present. +.Sh PACKAGE SETS +Package sets are meta-packages which do not contain any files +themselves, but depend on a selection of other packages, such that each +package set allows the complete set of packages for a supported workload +to be installed. +.Pp +Package sets are provided as packages named +.Sy FreeBSD-set-<name> . +The following package sets are available in the base system: +.Bl -tag -width "minimal-jail" +.It minimal +The minimal set of packages required to bring up a multi-user +.Fx +system. +This includes the core system, along with packages required for +hardware support (such as +.Xr devmatch 8 +and downloadable firmware), and basic networking, including DHCP and +IEEE Std 802.11\(tm wireless networks. +.It minimal-jail +The equivalent of +.Sy minimal +for systems running in a +.Xr jail 8 +environment. +This set excludes hardware support not typically required for jails. +.It devel +Development tools, including C/C++ compilers, the link loader, and +other tools such as +.Xr ar 1 +and +.Xr nm 1 . +This set also includes native development files (headers and static +libraries) for all packages. +.It lib32 +32-compatibility libraries, for running 32-bit applications on a +64-bit host system. +This set includes both runtime libraries and development files. +.It base +The complete base system, excluding tests, the system source code, +and debugging symbols. +.It base-jail +The equivalent of +.Sy base +for systems running in a +.Xr jail 8 +environment. +This set excludes system functionality which typically does not work +or is not useful in a jail. +.It src +The system source tree for the userland and kernel, installed in +.Pa /usr/src . +.It tests +The system test suite, installed in +.Pa /usr/tests . +.It kernels +All available system kernels. +.El +.Sh EXAMPLES +Install the +.Xr vi 1 +text editor on the running system: +.Bd -literal -offset indent +pkg install FreeBSD-vi +.Ed +.Pp +Install a new +.Xr jail 8 +system using the +.Sy minimal-jail +package set: +.Bd -literal -offset indent +pkg -r /jails/myjail install FreeBSD-set-minimal-jail +.Ed +.Pp +Install C/C++ compilers on the running system: +.Bd -literal -offset indent +pkg install FreeBSD-set-devel +.Ed +.Pp +Apply available updates to the running system: +.Bd -literal -offset indent +pkg update -r FreeBSD-base +.Ed +.Pp +Install the development toolchain for FreeBSD/powerpc64le in an +alternate root (for example, to support cross-compiling software +for a different target than the host system): +.Bd -literal -offset indent +pkg -r /ppcdev -oABI=FreeBSD:16:powerpc64le \e + install -r FreeBSD-set-devel +.Ed +.Sh SEE ALSO +.Xr build 7 , +.Xr pkg 8 , +.Xr src.conf 5 +.Sh HISTORY +Support for installing the base system as packages was introduced in +.Fx 15.0 . +Earlier releases supported a subset of this functionality. diff --git a/share/man/man7/growfs.7 b/share/man/man7/growfs.7 index 2e04e00f6abf..43648d8d9f2b 100644 --- a/share/man/man7/growfs.7 +++ b/share/man/man7/growfs.7 @@ -22,48 +22,119 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd May 3, 2020 +.Dd November 22, 2022 .Dt GROWFS 7 .Os .Sh NAME -.Nm growfs -.Nd start up script to grow the root file-system +.Nm growfs , +.Nm growfs_fstab +.Nd start up scripts to grow the root file system and add swap .Sh DESCRIPTION +The +.Nm +script normally runs at the first boot after system installation. +If the boot disk is larger than the root file system and boot partitions, +and the root file system is in the last partition, +.Nm +can expand the root file system. +It can also add a swap partition, with a default size of 10% of the boot disk. +Swap is limited to twice the memory size up to 4 GB, +8 GB up to 8 GB of memory, and memory size over 8 GB. +It is also limited to the +.Xr sysctl 8 +value of +.Li vm.swap_maxpages +divided by 2. +By default, no swap partition is created if an existing swap partition is found +or is listed in +.Pa /etc/fstab , +or the disk is under 15 GB. +The +.Nm growfs_fstab +script adds any new swap partition to +.Pa /etc/fstab +after the root file system is made writable, +and enables its use as a dump partition if the +.Va dumpdev +variable from +.Xr rc.conf 5 +is set to +.Li AUTO . +.Pp The following options in .Pa /etc/rc.conf control the behavior of .Nm : -.Bl -tag -width ".Va growfs_enable" -offset indent +.Bl -tag -width ".Va growfs_swap_size" -offset indent .It Va growfs_enable .Pq Dq Li NO If set to .Dq Li YES , -the first time the machine boots, the root file-system will be automatically -expanded, if possible, to fill up all available space after it. +the first time the machine boots, the root file system will be automatically +expanded, if possible, to fill up all available space after it, +after optionally adding a swap device at the end. +.It Va growfs_swap_size +.Pq Dq Li \& +If set to +.Dq Li 0 , +the addition of a swap partition is disabled. +An empty value +.Pq Dq Li \& +allows the creation of a swap partition with the default size. +If set to another value, +the swap partition will be created with the specified size in bytes, +even if another swap partition is detected. .El .Pp -To expand the root file-system with-out rebooting, run the following command: +A setting for +.Va growfs_swap_size +can be set in the kernel environment, in which case it overrides +the value from +.Pa /etc/rc.conf . +.Pp +To expand the root file system without rebooting, run the following command: .Dl % /etc/rc.d/growfs onestart +In addition, if a swap partition is added, run the command: +.Dl % /etc/rc.d/growfs_fstab onestart +Note that if a disk is expanded again, +and if the root file system had previously been expanded +and a swap partition added, it is necessary to delete the swap +partition before this procedure +in order to expand the root file system to the new size. +A new swap partition can be created during the expansion. .Sh IMPLEMENTATION NOTES +The +.Nm +script only attempts to expand the root file system, +and free space must be available immediately after the root partition. +It is normally used on images that have a single file system. The script requires that -.Pa awk -be present and on the path. +.Xr awk 1 +be present and in the path. This usually means that .Pa /usr -should be mounted prior to running the script. +must be available prior to running the script. .Sh FILES -.Pa /etc/rc.conf +.Bl -tag -compact -width Pa +.It Pa /etc/fstab +.It Pa /etc/rc.conf +.El .Sh EXIT STATUS .Ex -std +.Sh SEE ALSO +.Xr fstab 5 , +.Xr rc.conf 5 , +.Xr growfs 8 , +.Xr zpool 8 .Sh HISTORY The .Nm manual page first appeared in .Fx 10.1 . -.Sh SEE ALSO -.Xr rc.conf 5 +The ability to add a swap partition was added in +.Fx 13.2 . .Sh AUTHORS The man page and script were written by .An John-Mark Gurney Aq Mt jmg@FreeBSD.org . +The ability to create a swap partition was added by +.An Michael Karels Aq Mt karels@FreeBSD.org . diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7 index f33cf5ac62cc..c438511678d4 100644 --- a/share/man/man7/hier.7 +++ b/share/man/man7/hier.7 @@ -1,3 +1,6 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -25,130 +28,325 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)hier.7 8.1 (Berkeley) 6/5/93 -.\" $FreeBSD$ -.\" -.Dd August 4, 2022 +.Dd September 25, 2025 .Dt HIER 7 .Os .Sh NAME .Nm hier -.Nd layout of file systems +.Nd index of +.Fx +file system hierarchy .Sh DESCRIPTION -A sketch of the file system hierarchy. .Bl -tag -width "/libexec/" .It Pa / root directory of the file system +.It Pa /COPYRIGHT +.Fx +copyright information .It Pa /bin/ -user utilities fundamental to both single-user and multi-user environments +fundamental +.Bx +user utilities; see +.Xr intro 1 .It Pa /boot/ -programs and configuration files used during operating system bootstrap +programs and configurations used during +.Fx +.Xr boot 8 .Pp -.Bl -tag -width "defaults/" -compact +.Bl -tag -width "loader.conf.d/" -compact .It Pa defaults/ -default bootstrapping configuration files; see +default boot configuration files; see .Xr loader.conf 5 +.It Pa device.hints +kernel variables for controlling drivers; see +.Xr device.hints 5 .It Pa dtb/ -Compiled flattened device tree (FDT) files; see +compiled flattened device tree (FDT) files; see .Xr fdt 4 and .Xr dtc 1 +.Pp +.Bl -tag -width "overlays/" -compact +.It Pa overlays/ +compiled +.Xr fdt 4 +overlays; see +.Va fdt_overlays +in +.Xr loader.conf 5 +.El +.Pp .It Pa efi/ -Mount point for EFI System Partition (ESP) on UEFI systems +the +.Xr uefi 8 +EFI System Partition (ESP) mount point .It Pa firmware/ -loadable kernel modules containing binary firmware for hardware that needs -firmware downloaded to it to function +loadable binary firmware kernel modules +.It Pa fonts/ +binary bitmap console fonts; see +.Xr loader.conf 5 +and +.Xr vtfontcvt 8 +.It Pa images/ +beastie boot menu images; see +.Xr loader_lua 8 .It Pa kernel/ -pure kernel executable (the operating system loaded into memory -at boot time) and kernel modules +.Fx +kernel and modules; see +.Xr kldstat 8 +.It Pa kernel.old/ +alternative kernel and modules +.It Pa loader.conf +boot loader configuration; see +.Xr loader.conf 5 +.It Pa loader.conf.d/ +.Xr loader.conf 5 +configuration files +.It Pa lua/ +scripts for the Lua boot loader; see +.Xr loader_lua 8 .It Pa modules/ -third-party loadable kernel modules, such as the ones installed from +third-party loadable kernel modules, such as those installed with +.Xr pkg 8 +or from .Xr ports 7 -.It Pa overlays/ -Compiled flattened device tree (FDT) overlays; see -.Xr fdt 4 -and -.Xr dtc 1 .It Pa zfs/ -.Xr zfs 8 -zpool cache files +ZFS +.Xr zpool 8 +cache files .El -.It Pa /cdrom/ -default mount point for CD-ROM drives .It Pa /compat/ -normally a link to -.Pa /usr/compat . -If not, then the -.Pa /usr/compat -comments apply -.It Pa /dev/ -device special files managed by -.Xr devfs 5 +files supporting binary compatibility with other operating systems .Pp -.Bl -tag -width "defaults/" -compact +.Bl -tag -width "loader.conf.d" -compact +.It Pa linux/ +default location for +.Xr linux 4 +compatibility run-time +.El +.It Pa /dev/ +device nodes and special files; see +.Xr intro 4 +and +.Xr devfs 4 +.Pp +.Bl -tag -width "loader.conf.d" -compact +.It Pa ada0 +first ATA storage device +.It Pa ada0p1 +first partition on ada0 +.It Pa cd0 +first optical drive +.It Pa cuaU0 +first USB serial port; see +.Xr cu 1 +.It Pa da0 +first SCSI storage device +.It Pa da0s1 +first partition on da0 +.It Pa dri/ +GPU character device nodes; see +.Xr drm 7 +.It Pa drm/ +GPU +.Xr drm 7 +special files .It Pa fd/ -file descriptor files; -see -.Xr \&fd 4 +file descriptor files; see +.Xr fd 4 +.It Pa fd0 +first floppy drive +.It Pa gpt/ +storage partitions by GPT label +.It Pa mmcsd0 +first SD storage device +.It Pa mmcsd0s1 +first partition on mmcsd0 +.It Pa nda0 +first NVMe storage device attached via +.Xr cam 3 +.It Pa null +infinite loop that accepts anything and contains nothing +.It Pa nvd0 +first NVMe storage device using NVMe namespaces +.It Pa pts/ +pseudo-terminals; see +.Xr pts 4 +.It Pa random +source of weak randomness; see +.Xr random 4 +.It Pa sa0 +first tape drive +.It Pa usb/ +USB busses +.It Pa vmm/ +active +.Xr bhyve 8 +virtual machines +.It Pa zvol/ +.Xr zfs 8 +volumes .El +.It Pa /entropy +provides initial state to RNG; see +.Xr save-entropy 8 .It Pa /etc/ -system configuration files and scripts -.Pp -.Bl -tag -width "defaults/" -compact -.It Pa defaults/ -default system configuration files; -see -.Xr rc 8 +base system configuration files and scripts; see +.Xr intro 5 +.Pp +.Bl -tag -width "freebsd-update.conf" -compact +.It Pa auto_master +autofs +.Xr automount 8 +configuration .It Pa bluetooth/ bluetooth configuration files +.It Pa cron.d/ +tables for driving scheduled tasks; see +.Xr crontab 5 +.It Pa crontab +root's cron table +.It Pa defaults/ +default system configuration files; see +.Xr rc 8 +.It Pa devd/ +configuration for +.Xr devd 8 , +the device state change daemon +.It Pa devfs.conf +boot time device configuration +.It Pa dma/ +configuration for +.Xr dma 8 +.It Pa freebsd-update.conf +configuration for the base system updater; see +.Xr freebsd-update 8 +.It Pa fstab +static filesystem configuration; see +.Xr fstab 5 +.It Pa hosts +database of local hosts if no network name server is running +.It Pa inetd.conf +configuration for +.Bx +heritage internet servers; see +.Xr inetd 8 .It Pa localtime -local timezone information; -see +local timezone information; see .Xr ctime 3 +.It Pa jail.conf.d/ +.Xr jail 8 +startup scripts +.It Pa login.conf +login class capability database; see +.Xr login.conf 5 +.It Pa machine-id +defines the UUID for the local system, required for dbus .It Pa mail/ -Sendmail control files +.Xr sendmail 8 +control files +.Pp +.Bl -tag -width "mailer.conf" -compact +.It Pa aliases +addresses to deliver system mail +.It Pa mailer.conf +.Xr mailwrapper 8 +configuration +.El +.Pp +.It Pa motd.template +message displayed upon tty login; see +.Xr motd 5 .It Pa mtree/ -mtree configuration files; -see +system mapper specification; see .Xr mtree 8 +.It Pa newsyslog.conf.d/ +log rotation configuration files. +.It Pa ntp/ +stored time for the Network Time Protocol +.It Pa ntp.conf +configuration for the NTP client, +.Xr ntpd 8 .It Pa pam.d/ -configuration files for the Pluggable Authentication Modules (PAM) -library +configuration files for the Pluggable Authentication Modules (PAM) library; +see +.Xr pam 3 .It Pa periodic/ -scripts that are run daily, weekly, and monthly, via +scripts that are run daily, weekly, or monthly by .Xr cron 8 ; see .Xr periodic 8 +.It Pa pf.conf +configuration for the Packet Filter firewall; see +.Xr pf 4 +.It Pa pkg/ +default configuration for the package manager, +.Xr pkg 8 +.It Pa ppp/ +PPP configuration files; see +.Xr ppp 8 +.It Pa rc.conf +system and daemon configuration; see +.Xr rc.conf 5 .It Pa rc.d/ -system and daemon startup/control scripts; -see +system and daemon startup/control scripts; see .Xr rc 8 +.It Pa resolv.conf +DNS configuration; see +.Xr resolv.conf 5 +.It Pa resolvconf.conf +DNS configuration manager configuration, often generated by +local-unbound; see +.Xr local-unbound 8 +or +.Xr resolvconf 8 .It Pa security/ -OpenBSM audit configuration files; -see +OpenBSM audit configuration files; see .Xr audit 8 -.It Pa ppp/ -ppp configuration files; -see -.Xr ppp 8 .It Pa ssh/ -OpenSSH configuration files; -see +OpenSSH configuration files; see .Xr ssh 1 .It Pa ssl/ OpenSSL configuration files -.El +.Pp +.Bl -tag -width "untrusted/" -compact +.It Pa cert.pem +System trust store in bundle form; see +.Xr certctl 8 . +.It Pa certs/ +System trust store in OpenSSL hashed-directory form; see +.Xr certctl 8 . +.It Pa openssl.cnf +OpenSSL configuration file; see +.Xr openssl.cnf 5 . +.It Pa untrusted/ +Explicitly distrusted certificates; see +.Xr certctl 8 . +.El +.It Pa sysctl.conf +kernel state defaults; see +.Xr sysctl.conf 5 +.It Pa syslog.conf +system log configuration +.It Pa ttys +tty creation configuration; see +.Xr getty 8 +.It Pa wpa_supplicant.conf +client wifi configuration; see +.Xr wpa_supplicant.conf 5 +.El +.It Pa /home/ +home directories for users; the typical home for an interactive user +.Va beastie +would be +.Pa /home/beastie/ .It Pa /lib/ -critical system libraries needed for binaries in +system libraries critical to binaries in .Pa /bin and .Pa /sbin .Pp -.Bl -tag -width "defaults/" -compact -.It Pa casper/ -service-specific -.Xr libcasper 3 -Capsicum support libraries +.Bl -tag -width "nvmecontrol/" -compact .It Pa geom/ class-specific libraries for the .Xr geom 8 @@ -159,53 +357,55 @@ vendor-specific libraries to extend the utility .El .It Pa /libexec/ -critical system utilities needed for binaries in +system utilities critical to binaries in .Pa /bin and .Pa /sbin .It Pa /media/ -contains subdirectories to be used as mount points -for removable media such as CDs, USB drives, and -floppy disks +mount points for removable storage media such as CDs, DVDs, +and USB drives; see +.Xr automount 8 , +or +.Xr bsdisks 8 +if a using a desktop environment from +.Xr ports 7 .It Pa /mnt/ empty directory commonly used by system administrators as a temporary mount point .It Pa /net/ -automounted NFS shares; -see +automounted NFS shares; see .Xr auto_master 5 .It Pa /nonexistent/ a non-existent directory; -by convention, it serves as a home directory -for special user accounts -that need no home directory; -see also +by convention, it serves as a home directory for user accounts +that need no home directory; see also .Pa /var/empty/ .It Pa /proc/ -process file system; -see -.Xr procfs 5 +process file system; see +.Xr procfs 4 .It Pa /rescue/ -statically linked programs for emergency recovery; -see +statically linked programs for emergency recovery; see .Xr rescue 8 .It Pa /root/ -root's HOME directory +home directory of the root user .It Pa /sbin/ -system programs and administration utilities -fundamental to both single-user and multi-user environments +fundamental +.Bx +system administration utilities; see +.Xr intro 8 .It Pa /tmp/ -temporary files that are not guaranteed to persist across system reboots +temporary files commonly removed between system reboots; +see +.Va clear_tmp_enable +in +.Xr rc.conf 5 .It Pa /usr/ contains the majority of user utilities and applications .Pp .Bl -tag -width "freebsd-dist/" -compact .It Pa bin/ -common utilities, programming tools, and applications -.It Pa compat/ -files needed to support binary compatibility with other operating systems; -see -.Xr linux 4 +common utilities, programming tools, and applications; see +.Xr intro 1 .It Pa freebsd-dist/ distribution files .Pq like base.txz ; @@ -214,302 +414,180 @@ see and .Xr bsdinstall 8 .It Pa include/ -standard C include files -.Pp -.Bl -tag -width "kerberos5/" -compact -.It Pa arpa/ -C include files for Internet service protocols -.It Pa bsnmp/ -C include files for the SNMP daemon -.It Pa c++/ -C++ include files -.It Pa cam/ -C include files for the Common Access Methods Layer -.Bl -tag -width "kerberos5/" -compact -.It Pa scsi/ -SCSI device on top of CAM -.El -.It Pa dev/ -C include files for programming various -.Fx -devices -.Bl -tag -width "kerberos5/" -compact -.It Pa ic/ -various header files describing driver- and bus-independent -hardware circuits -.It Pa ofw/ -Open Firmware support -.It Pa pbio/ -8255 PPI cards; -see -.Xr pbio 4 -.It Pa ppbus/ -parallel port bus; -see -.Xr ppbus 4 -.It Pa usb/ -USB subsystem -.El -.It Pa fs/ -.Bl -tag -width "kerberos5/" -compact -.It Pa fdescfs/ -per-process file descriptors file system -.It Pa msdosfs/ -MS-DOS file system -.It Pa nfs/ -C include files for NFS (Network File System) version 2, 3 and 4 -.It Pa nullfs/ -loopback file system -.It Pa procfs/ -process file system -.It Pa smbfs/ -SMB/CIFS file system -.It Pa udf/ -UDF file system -.It Pa unionfs -union file system -.El -.It Pa geom/ -GEOM framework -.Bl -tag -width "kerberos5/" -compact -.It Pa concat/ -CONCAT GEOM class -.It Pa gate/ -GATE GEOM class -.It Pa mirror/ -MIRROR GEOM class -.It Pa nop/ -NOP GEOM class -.It Pa raid3/ -RAID3 GEOM class -.It Pa stripe/ -STRIPE GEOM class -.El -.It Pa libmilter/ -C include files for libmilter, -the -.Xr sendmail 8 -mail filter API -.It Pa machine/ -machine-specific C include files -.It Pa net/ -miscellaneous network C include files -.Bl -tag -width Fl -compact -.It Pa altq/ -C include files for alternate packet queueing; see -.Xr altq 4 -.El -.It Pa net80211/ -C include files for 802.11 wireless networking; -see -.Xr net80211 4 -.It Pa netinet/ -C include files for Internet standard protocols; -see -.Xr inet 4 -.It Pa netinet6/ -C include files for Internet protocol version 6; -see -.Xr inet6 4 -.It Pa netipsec/ -kernel key-management service; -see -.Xr ipsec 4 -.It Pa netsmb/ -SMB/CIFS requester -.It Pa nfs/ -C include files for NFS (Network File System) version 2 and 3 (legacy) -.It Pa openssl/ -OpenSSL (Cryptography/SSL toolkit) headers -.It Pa protocols/ -C include files for Berkeley service protocols -.It Pa rpc/ -remote procedure calls; -see -.Xr rpc 3 -.It Pa rpcsvc/ -definition of RPC service structures; see -.Xr rpc 3 -.It Pa security/ -PAM; see -.Xr pam 8 -.It Pa sys/ -system C include files (kernel data structures) -.\" .It Pa tcl/ -.\" Tcl language; -.\" see -.\" .Xr Tcl n -.\" .Bl -tag -width "kerberos5/" -compact -.\" .It Pa generic/ -.\" ??? -.\" .It Pa unix/ -.\" ??? -.\" .El -.It Pa ufs/ -C include files for UFS (The U-word File System) -.Bl -tag -width "kerberos5/" -compact -.It Pa ffs/ -Fast file system -.It Pa ufs/ -UFS file system -.El -.It Pa vm/ -virtual memory; -see -.Xr vmstat 8 -.El -.Pp +standard C include header files .It Pa lib/ -shared and archive +shared and .Xr ar 1 Ns -type -libraries +libraries; see +.Xr intro 3 .Pp .Bl -tag -width Fl -compact +.It Pa clang/ +shared libraries for the system compiler, +.Xr clang 1 .It Pa compat/ shared libraries for compatibility .It Pa debug/ standalone debug data for the kernel and base system libraries and binaries .It Pa dtrace/ -DTrace library scripts +.Xr dtrace 1 +library scripts .It Pa engines/ -OpenSSL (Cryptography/SSL toolkit) dynamically loadable engines +OpenSSL +.Pq Cryptography/SSL toolkit +dynamically loadable engines +.It Pa flua/ +.Fx +Lua shared libraries +.It Pa i18n/ +shared libraries for internationalization .El .Pp +.It Pa lib32/ +32-bit compatibility libraries .It Pa libdata/ miscellaneous utility data files .Pp .Bl -tag -width Fl -compact -.It Pa gcc/ -.Xr gcc 1 -configuration data .It Pa ldscripts/ -linker scripts; -see +linker scripts; see .Xr ld 1 .It Pa pkgconfig/ -pc files +collections of compiler and linker flags for the +.Xr pkgconf 1 +development tool .El .Pp .It Pa libexec/ -system daemons & system utilities (executed by other programs) +system daemons and utilities executed by programs .Pp -.Bl -tag -width Fl -compact -.It Pa aout/ -utilities to manipulate a.out executables -.It Pa elf/ -utilities to manipulate ELF executables +.Bl -tag -width "bsdinstall/" -compact +.It Pa bsdconfig/ +utilities called by the ncurses +.Fx +configuration wizard +.It Pa bsdinstall/ +utilities for +.Xr bsdinstall 8 +.It Pa dwatch/ +profiles for +.Xr dwatch 1 +.It Pa fwget/ +utilities called by +.Xr fwget 8 +.It Pa hyperv/ +scripts for communicating with the Hyper-V hypervisor .It Pa lpr/ -utilities and filters for LP print system; -see +utilities and filters for the line printer system; see .Xr lpr 1 .It Pa sendmail/ the .Xr sendmail 8 -binary; -see +binary; see .Xr mailwrapper 8 .It Pa sm.bin/ restricted shell for .Xr sendmail 8 ; see .Xr smrsh 8 +.It Pa zfs/ +Z file system utilities .El .Pp .It Pa local/ -local executables, libraries, etc. -Also used as the default destination for the +local executables, libraries, etc, installed by +.Xr pkg 7 +or .Xr ports 7 -framework. -Within -.Pa local/ , -the general layout sketched out by -.Nm -for -.Pa /usr -should be used. -Exceptions are the -ports documentation -.Po in -.Pa share/doc/<port>/ Ns Pc , -and -.Pa /usr/local/etc -.Po mimics -.Pa /etc Ns Pc . +.Pp +.Bl -tag -width Fl -compact +.It Pa bin/ +local user utilities, see +.Xr intro 1 +.It Pa etc/ +local program configurations +.It Pa include/ +local library headers +.It Pa lib/ +local libraries +.It Pa lib32/ +local 32-bit compatability libraries +.It Pa libdata/ +local utility data files +.It Pa libexec/ +utilities executed by local utilities +.It Pa sbin/ +local administration utilities +.It Pa share/ +local architecture-independent files +.It Pa share/doc/ +local documentation +.It Pa share/doc/freebsd/ +articles, books, FAQ, and handbooks available from the +.Fx +project +.It Pa share/man/ +local manual pages; see +.Xr man 1 +.El +.Pp .It Pa obj/ architecture-specific target tree produced by building .Fx -from source; -see +from source; see .Xr build 7 .It Pa ports/ .Fx ports collection; see .Xr ports 7 .It Pa sbin/ -system daemons & system utilities (executed by users) +system daemons and utilities meant for user execution; see +.Xr intro 8 .It Pa share/ architecture-independent files .Pp .Bl -tag -width Fl -compact +.It Pa atf/ +scripts for the Automated Testing Framework; see +.Xr ATF 7 +.It Pa bhyve/ +.Xr bhyve 8 +keyboard mappings .It Pa calendar/ -a variety of pre-fab calendar files; -see +system-wide calendar files; see .Xr calendar 1 +.It Pa certs/ +TLS certificates for +.Xr openssl 1 .It Pa dict/ -word lists; -see +word lists; see .Xr look 1 +.Pp .Bl -tag -width Fl -compact .It Pa freebsd .Fx Ns -specific terms, proper names, and jargon .It Pa web2 -words from Webster's 2nd International +words from Webster's Second International .El +.Pp .It Pa doc/ -miscellaneous documentation; -source for most of the printed -.Bx -manuals (available -from the -.Tn USENIX -association) -.Bl -tag -width Fl -compact -.It Pa FAQ/ -Frequently Asked Questions -.It Pa IPv6/ -implementation notes for IPv6 -.It Pa es/ -Spanish translations of documents in /usr/share/doc -.It Pa handbook/ -.Fx -Handbook -.It Pa ja/ -Japanese translations of documents in /usr/share/doc -.It Pa legal/ -License files for vendor supplied firmware files -.It Pa ncurses/ -HTML documents pertaining to ncurses; -see -.Xr ncurses 3 -.It Pa ntp/ -HTML documents pertaining to the Network Time Protocol -.It Pa ru/ -Russian translations of documents in /usr/share/doc -.It Pa tutorials/ -.Fx -tutorials -.It Pa zh/ -Chinese translations of documents in /usr/share/doc -.El +miscellaneous documentation +.It Pa dtrace/ +scripts for the Dynamic Tracing Compiler; see +.Xr dtrace 1 .It Pa examples/ various examples for users and programmers .It Pa firmware/ firmware images loaded by userland programs .It Pa games/ -ASCII text files used by various games +ASCII text files used by +.Bx +heritage games, see +.Xr intro 6 .It Pa keys/ known trusted and revoked keys +.Pp .Bl -tag -width Fl -compact .It Pa pkg/ fingerprints for @@ -517,25 +595,31 @@ fingerprints for and .Xr pkg 8 .El +.Pp .It Pa locale/ -localization files; -see +localization files; see .Xr setlocale 3 .It Pa man/ -manual pages +system manual pages; see +.Xr man 1 .It Pa misc/ -miscellaneous system-wide ASCII text files +miscellaneous system-wide files +.Pp .Bl -tag -width Fl -compact -.It Pa fonts/ -??? +.It Pa ascii +chart of the ASCII codepoints +.It Pa flowers +the meanings of flowers +.It Pa magic +magic numbers used by +.Xr file 1 .It Pa termcap -terminal characteristics database; -see +terminal characteristics database; see .Xr termcap 5 .El +.Pp .It Pa mk/ -templates for make; -see +templates for make; see .Xr make 1 .It Pa nls/ national language support files @@ -551,259 +635,149 @@ example (dot) files for new accounts .It Pa snmp/ MIBs, example files and tree definitions for the SNMP daemon +.Pp .Bl -tag -width Fl -compact .It Pa defs/ tree definition files for use with .Xr gensnmptree 1 .It Pa mibs/ -MIB files +management Information Base +.Pq MIB +files .El +.Pp .It Pa syscons/ -files used by syscons; -see .Xr syscons 4 +files +.Pp .Bl -tag -width Fl -compact .It Pa fonts/ -console fonts; -see +console fonts; see .Xr vidcontrol 1 and .Xr vidfont 1 .It Pa keymaps/ -console keyboard maps; -see +console keyboard maps; see .Xr kbdcontrol 1 and .Xr kbdmap 1 .It Pa scrnmaps/ console screen maps .El +.Pp .It Pa sysroot/ files necessary for the -sysroot compiler/linker argument to build non-native -binaries. -.Bl -tag -width Fl -compact +binaries +.Pp +.Bl -tag -width "VERSION/" -compact .It Pa VERSION/ files for .Fx -release VERSION. -By convention, +release VERSION; +by convention, .Dq VERSION matches .Xr uname 1 -.Fl r . -.Bl -tag -width Fl -compact -.It Pa MACHINE.MACHINE_ARCH/ -represent the binary ABI for these files. +.Fl r +.It Pa VERSION/MACHINE.MACHINE_ARCH/ +represent the binary ABI for these files; .Dq MACHINE matches .Xr uname 1 -.Fl m . +.Fl m ; .Dq MACHINE_ARCH matches .Xr uname 1 -.Fl p . -.El +.Fl p .El +.Pp .It Pa tabset/ tab description files for a variety of terminals; used in -the termcap file; -see +the termcap file; see .Xr termcap 5 .It Pa vi/ -localization support and utilities for +localization support and utilities for the .Xr vi 1 +editor .It Pa vt/ -files used by vt; -see +files used by the system console; see .Xr vt 4 +.Pp .Bl -tag -width Fl -compact .It Pa fonts/ -console fonts; -see -.Xr vidcontrol 1 +console fonts; see +.Xr vidcontrol 1 , +.Xr vidfont 1 , and -.Xr vidfont 1 +.Xr vtfontcvt 8 .It Pa keymaps/ -console keyboard maps; -see +console keyboard maps; see .Xr kbdcontrol 1 and .Xr kbdmap 1 -.\" .It Pa scrnmaps/ -.\" console screen maps .El +.Pp .It Pa zoneinfo/ -timezone configuration information; -see +timezone configuration information; see .Xr tzfile 5 .El .Pp .It Pa src/ .Fx source code; see -.Xr development 7 -.Pp -.Bl -tag -width "kerberos5/" -compact -.It Pa bin/ -source code for files in /bin -.It Pa cddl/ -utilities covered by the Common Development and Distribution License -.It Pa contrib/ -source code for contributed software -.It Pa crypto/ -source code for contributed cryptography software -.It Pa etc/ -source code for files in -.Pa /etc -.It Pa gnu/ -utilities covered by the GNU General Public License -.It Pa include/ -source code for files in -.Pa /usr/include -.It Pa kerberos5/ -build infrastructure for Kerberos version 5 -.It Pa lib/ -source code for files in -.Pa /lib -and -.Pa /usr/lib -.It Pa libexec/ -source code for files in -.Pa /usr/libexec -.It Pa release/ -files required to produce a -.Fx -release -.It Pa rescue/ -source code for files in -.Pa /rescue -.It Pa sbin/ -source code for files in -.Pa /sbin -.It Pa secure/ -build directory for files in -.Pa /usr/src/crypto -.It Pa share/ -source for files in -.Pa /usr/share -.It Pa stand/ -boot loader source code -.It Pa sys/ -kernel source code -.Bl -tag -width Fl -compact -.It Pa amd64/ -AMD64 architecture support -.It Pa arm/ -ARM architecture support -.It Pa arm64/ -ARMv8 architecture support -.It Pa cam/ -.Xr cam 4 -and -.Xr ctl 4 -.It Pa cddl/ -CDDL-licensed optional sources, including ZFS -and DTrace -.It Pa ddb/ -.Xr ddb 4 -.It Pa fs/ -most filesystems -.It Pa dev/ -device drivers -.It Pa geom/ -.Xr geom 4 -.It Pa i386/ -i386 (32 bit) architecture support -.It Pa kern/ -main part of the kernel -.It Pa net80211/ -.Xr net80211 4 -.It Pa netgraph/ -.Xr netgraph 4 -.It Pa netinet/ -.Xr inet 4 -.It Pa netinet6/ -.Xr inet6 4 -.It Pa netipsec/ -.Xr ipsec 4 -.It Pa netpfil/ -.Xr ipfw 4 -and -.Xr pf 4 -.It Pa opencrypto/ -.Xr crypto 7 -.It Pa powerpc/ -PowerPC/POWER architecture support -.It Pa riscv/ -RISC-V architecture support -.It Pa security/ -.Xr audit 4 -and -.Xr mac 4 -.It Pa sys/ -kernel headers -.It Pa ufs/ -Unix File System -.It Pa x86/ -code shared by AMD64 and i386 architectures -.El -.It Pa targets/ -support for experimental DIRDEPS_BUILD -.It Pa tests/ -source code for files in -.Pa /usr/tests -.It Pa tools/ -tools used for maintenance and testing of -.Fx -.It Pa usr.bin/ -source code for files in -.Pa /usr/bin -.It Pa usr.sbin/ -source code for files in -.Pa /usr/sbin -.El +.Xr development 7 ; +the layout of the source tree is described by the top-level +.Pa README.md +file .Pp .It Pa tests/ -The +the .Fx test suite; see .Xr tests 7 .El .It Pa /var/ -multi-purpose log, temporary, transient, and spool files +log, temporary, transient, and spool files .Pp -.Bl -tag -width "defaults/" -compact +.Bl -tag -width "preserve/" -compact .It Pa account/ system accounting files .Pp -.Bl -tag -width Fl -compact +.Bl -tag -width Ds -compact .It Pa acct -execution accounting file; -see +execution accounting file; see .Xr acct 5 .El .Pp .It Pa at/ -timed command scheduling files; -see -.Xr \&at 1 +timed command scheduling files; see +.Xr at 1 .Pp -.Bl -tag -width Fl -compact +.Bl -tag -width Ds -compact .It Pa jobs/ -directory containing job files +job files .It Pa spool/ -directory containing output spool files +output spool files .El .Pp +.It Pa audit/ +security event audit trail files; see +.Xr audit 8 +.It Pa authpf/ +user shell sessions for authenticating gateways; see +.Xr authpf 8 .It Pa backups/ -miscellaneous backup files +critical system configuration backups .It Pa cache/ -miscellaneous cached files +miscellaneous cache files .Pp -.Bl -tag -width Fl -compact +.Bl -tag -width Ds -compact .It Pa pkg/ cached packages for .Xr pkg 8 +.It Pa cups/ +cached printers for the Common Unix Prinitng system; see +.Xr cups 1 .El .Pp .It Pa crash/ @@ -812,66 +786,127 @@ default directory to store kernel crash dumps; see and .Xr savecore 8 .It Pa cron/ -files used by cron; -see +files used by cron; see .Xr cron 8 .Pp -.Bl -tag -width Fl -compact +.Bl -tag -width Ds -compact .It Pa tabs/ -crontab files; -see +crontab files; see .Xr crontab 5 .El .Pp .It Pa db/ -miscellaneous automatically generated system-specific database files -.Bl -tag -width Fl -compact +autogenerated system-specific database files +.Pp +.Bl -tag -width "freebsd-update/" -compact +.It Pa etcupdate/ +temporary files and log for +.Xr etcupdate 8 .It Pa freebsd-update/ +downloads and temporary files for .Xr freebsd-update 8 -work directory for temporary files and downloaded updates +.It Pa pkg/ +package database .El +.Pp .It Pa empty/ -empty directory for use by programs that need a specifically empty directory. -Used for instance by +for use by programs that require an empty directory, +used for instance by .Xr sshd 8 for privilege separation .It Pa games/ -miscellaneous game status and score files +status and score files for +.Bx +heritage games .It Pa heimdal/ Kerberos server databases; see .Xr kdc 8 +.It Pa lib/ +state information for ported Linux applications .It Pa log/ -miscellaneous system log files -.Pp -.Bl -tag -width Fl -compact -.It Pa utx.lastlogin -last login log; +system log files +.Pp +.Bl -tag -width "bsdinstall_log" -compact +.It Pa Xorg.0.log +.Xr Xserver 1 +log, if +.Xr X 7 +is installed rotates to +.Pa Xorg.0.log.old +.It Pa aculog +serial line access log; see +.Xr cu 1 +.It Pa auth.log +system authentication log +.It Pa bsdinstall_log +system installation log +.It Pa cron +scheduled task log; see +.Xr cron 8 +.It Pa cups/ +logs for +.Xr cups 1 +.It Pa daemon.log +default log for system daemons +.It Pa devd.log +default log for device state change daemon +.It Pa dmesg.today +system message buffer log, rotates to +.Pa dmesg.yesterday +.It Pa debug.log +undiscarded debug syslog messages +.It Pa lpd-errs +logs for the line printer spooler daemon; see +.Xr lpd 8 +.It Pa maillog +.Xr sendmail 8 +log, rotates and compresses to maillog.0.bz2 +.It Pa messages +general system log; see +.Xr syslogd 8 +.It Pa mount.today +currently loaded +.Xr fstab 5 , +rotates to +.Pa mount.yesterday +.It Pa pf.today +packet filter firewall log; see +.Xr pf 4 +.It Pa pflog +saved packets caught by +.Xr pflogd 8 +.It Pa ppp.log see +.Xr ppp 8 +.It Pa security +transcript of events marked with the security flag +.It Pa setuid.today +listing of executable files which run with elevated permissions, rotates +to +.Pa setuid.yesterday +.It Pa userlog +logs changes in users or groups +.It Pa utx.lastlogin +last login log; see .Xr getutxent 3 .It Pa utx.log -login/logout log; -see +login/logout log; see .Xr getutxent 3 .El .Pp .It Pa mail/ user mailbox files .It Pa msgs/ -system messages database; -see +system messages database; see .Xr msgs 1 .It Pa preserve/ -temporary home of files preserved after an accidental death -of an editor; -see -.Xr \&ex 1 +unused, present for historical reasons .It Pa quotas/ -file system quota information files +UFS quota information files .It Pa run/ -system information files describing various info about -system since it was booted +files containing information about the operating system since it was booted .Pp -.Bl -tag -width Fl -compact +.Bl -tag -width "wpa_supplicant/" -compact .It Pa bhyve/ .Xr bhyve 8 virtual machine @@ -882,46 +917,58 @@ writable by the group for command connection sockets; see .Xr ppp 8 .It Pa utx.active -database of current users; -see +database of current users; see .Xr getutxent 3 +.It Pa wpa_supplicant/ +IEEE Std. 802.11 wifi run time files .El .Pp .It Pa rwho/ -rwho data files; -see +information about other systems on the local network; see .Xr rwhod 8 , .Xr rwho 1 , and .Xr ruptime 1 .It Pa spool/ -miscellaneous printer and mail system spooling directories +printer and mail system spooling directories .Pp -.Bl -tag -width Fl -compact +.Bl -tag -width "clientmqueue/" -compact .It Pa clientmqueue/ -undelivered submission mail queue; -see +undelivered submission mail queue; see .Xr sendmail 8 -.It Pa ftp/ -ftp root directory; -see -.Xr ftpd 8 +.It Pa cups/ +print jobs and temporary files for +.Xr cups 1 +.It Pa dma/ +undelivered mail queue for +.Dx +Mail Agent; see +.Xr dma 8 +.It Pa lock/ +serial device locks; see +.Xr uucplock 3 +.It Pa lpd/ +line printer spooler daemon spool .It Pa mqueue/ -undelivered mail queue; -see +undelivered mail queue for .Xr sendmail 8 .It Pa output/ line printer spooling directories .El .Pp .It Pa tmp/ -temporary files that are kept between system reboots +temporary files not removed between system reboots .Pp -.Bl -tag -width Fl -compact +.Bl -tag -width "vi.recover/" -compact .It Pa vi.recover/ -the directory where recovery files are stored +recovery files for the +.Xr vi 1 +editor .El .Pp +.It Pa unbound/ +files and configuration for +.Xr unbound 8 .It Pa yp/ the NIS maps; see .Xr yp 8 @@ -930,8 +977,8 @@ the NIS maps; see .Sh NOTES This manual page documents the default .Fx -file system layout, but -the actual hierarchy on a given system is defined at the system +file system layout. +The actual hierarchy on a given system is defined at the system administrator's discretion. A well-maintained installation will include a customized version of this document. @@ -945,5 +992,5 @@ this document. .Sh HISTORY A .Nm -manual page appeared in +manual page first appeared in 1979 with .At v7 . diff --git a/share/man/man7/hostname.7 b/share/man/man7/hostname.7 index ac00bd9c8818..2c15fb6f47b8 100644 --- a/share/man/man7/hostname.7 +++ b/share/man/man7/hostname.7 @@ -25,9 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)hostname.7 8.2 (Berkeley) 12/30/93 -.\" $FreeBSD$ -.\" .Dd December 25, 2013 .Dt HOSTNAME 7 .Os diff --git a/share/man/man7/intro.7 b/share/man/man7/intro.7 index 76385eca7144..43e48de87bc5 100644 --- a/share/man/man7/intro.7 +++ b/share/man/man7/intro.7 @@ -25,10 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)intro.7 8.1 (Berkeley) 6/5/93 -.\" $FreeBSD$ -.\" -.Dd November 19, 2020 +.Dd July 14, 2025 .Dt INTRO 7 .Os .Sh NAME @@ -52,14 +49,14 @@ system timekeeping clocks available in .It Xr crypto 7 cryptographic algorithms provided by OpenCrypto in .Fx +.It Xr d 7 +.Xr dtrace 1 +scripting language overview .It Xr development 7 development introduction to .Fx .It Xr environ 7 user environment -.It Xr ffs 7 -commonly used filesystem in -.Fx .It Xr firewall 7 simple firewalls under .Fx @@ -68,6 +65,8 @@ file system hierarchy in .Fx .It Xr hostname 7 host name resolution description +.It Xr networking 7 +network connection quickstart guide .It Xr release 7 layout of .Fx @@ -85,6 +84,8 @@ statistics utilities available in introduction to the .Fx Test Suite +.It Xr tracing 7 +introduction to tracing and performance monitoring facilities .It Xr tuning 7 general advice on tuning .Fx diff --git a/share/man/man7/maclabel.7 b/share/man/man7/maclabel.7 index 0648fb565c9a..5006cc47beb3 100644 --- a/share/man/man7/maclabel.7 +++ b/share/man/man7/maclabel.7 @@ -31,8 +31,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 25, 2002 .Dt MACLABEL 7 .Os diff --git a/share/man/man7/mitigations.7 b/share/man/man7/mitigations.7 new file mode 100644 index 000000000000..c3c6ab55c480 --- /dev/null +++ b/share/man/man7/mitigations.7 @@ -0,0 +1,496 @@ +.\"- +.\" SPDX-License-Identifer: BSD-2-Clause +.\" +.\" Copyright © 2023 The FreeBSD Foundation +.\" +.\" This documentation was written by Ed Maste <emaste@freebsd.org>, and +.\" Olivier Certner <olce.freebsd@certner.fr> at Kumacom SAS, under +.\" sponsorship of the FreeBSD Foundation. +.\" +.\" 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 January 29, 2025 +.Dt MITIGATIONS 7 +.Os +.Sh NAME +.Nm mitigations +.Nd FreeBSD Security Vulnerability Mitigations +.Sh SYNOPSIS +In +.Fx , +various security mitigations are employed to limit the impact of +vulnerabilities and protect the system from malicious attacks. +Some of these mitigations have run-time controls to enable them on a global +or per-process basis, some are optionally enabled or disabled at compile time, +and some are inherent to the implementation and have no controls. +.Pp +The following vulnerability mitigations are covered in this document: +.Pp +.Bl -bullet -compact +.It +Address Space Layout Randomization (ASLR) +.It +Position Independent Executable (PIE) +.It +Write XOR Execute page protection policy +.It +.Dv PROT_MAX +.It +Relocation Read-Only (RELRO) +.It +Bind Now +.It +Stack Overflow Protection +.It +Supervisor Mode Memory Protection +.It +Capsicum +.It +Firmware and Microcode +.It +Architectural Vulnerability Mitigations +.El +.Pp +Please note that the effectiveness and availability of these mitigations may +vary depending on the +.Fx +version and system configuration. +.Sh DESCRIPTION +Security vulnerability mitigations are techniques employed in +.Fx +to limit the potential impact of security vulnerabilities in software and +hardware. +It is essential to understand that mitigations do not directly address the +underlying security issues. +They are not a substitute for secure coding practices. +Mitigations serve as an additional layer of defense, helping to reduce the +likelihood of a successful exploitation of vulnerabilities by making it +more difficult for attackers to achieve their objectives. +.Pp +This manual page describes the security mitigations implemented in +.Fx +to enhance the overall security of the operating system. +Each mitigation is designed to protect against specific types of attacks +and vulnerabilities. +.\" +.Sh SOFTWARE VULNERABILITY MITIGATIONS +.Ss Address Space Layout Randomization (ASLR) +Address Space Layout Randomization (ASLR) is a security mitigation technique +that works by randomizing the memory addresses where system and application +code, data, and libraries are loaded, making it more challenging for attackers +to predict the memory layout and exploit vulnerabilities. +.Pp +ASLR introduces randomness into the memory layout during process execution, +reducing the predictability of memory addresses. +ASLR is intended to make exploitation more difficult in the event that an +attacker discovers a software vulnerability, such as a buffer overflow. +.Pp +ASLR can be enabled on both a global and per-process basis. +Global control is provided by a separate set of +.Xr sysctl 8 +knobs for 32- and 64-bit processes. +It can be or disabled on a per-process basis via +.Xr proccontrol 1 . +Note that an ASLR mode change takes effect upon address space change, +i.e., upon +.Xr execve 2 . +.Pp +Global controls for 32-bit processes: +.Bl -tag -width kern.elf32.aslr.pie_enable +.It Va kern.elf32.aslr.enable +Enable ASLR for 32-bit ELF binaries, other than Position Independent +Executable (PIE) binaries. +.It Va kern.elf32.aslr.pie_enable +Enable ASLR for 32-bit Position Independent Executable (PIE) ELF binaries. +.It Va kern.elf32.aslr.honor_sbrk +Reserve the legacy +.Xr sbrk 2 +region for compatibility with older binaries. +.It Va kern.elf32.aslr.stack +Randomize the stack location for 32-bit ELF binaries. +.El +.Pp +Global controls for 64-bit processes: +.Bl -tag -width kern.elf64.aslr.pie_enable +.It Va kern.elf64.aslr.enable +Enable ASLR for 64-bit ELF binaries, other than Position Independent +Executable (PIE) binaries. +.It Va kern.elf64.aslr.pie_enable +Enable ASLR for 64-bit Position Independent Executable (PIE) ELF binaries. +.It Va kern.elf64.aslr.honor_sbrk +Reserve the legacy +.Xr sbrk 2 +region for compatibility with older binaries. +.It Va kern.elf64.aslr.stack +Randomize the stack location for 64-bit ELF binaries. +.El +.Pp +To execute a command with ASLR enabled or disabled: +.Pp +proccontrol +.Fl m Ar aslr +.Op Fl s Ar enable | disable +.Ar command +.\" +.Ss Position Independent Executable (PIE) +PIE binaries are executable files that do not have a fixed load address. +They can be loaded at an arbitrary memory address by the +.Xr rtld 1 +run-time linker. +With ASLR they are loaded at a random address on each execution. +.\" +.Ss Write XOR Execute page protection policy +Write XOR Execute (W^X) is a vulnerability mitigation strategy that strengthens +the security of the system by controlling memory access permissions. +.Pp +Under the W^X mitigation, memory pages may be writable (W) or executable (E), +but not both at the same time. +This means that code execution is prevented in areas of memory that are +designated as writable, and writing or modification of memory is restricted in +areas marked for execution. +Applications that perform Just In Time (JIT) compilation need to be adapted +to be compatible with W^X. +.Pp +There are separate +.Xr sysctl 8 +knobs to control W^X policy enforcement for 32- and 64-bit processes. +The W^X policy is enabled by setting the appropriate +.Dv allow_wx +sysctl to 0. +.Bl -tag -width kern.elf64.allow_wx +.It Va kern.elf32.allow_wx +Allow 32-bit processes to map pages simultaneously writable and executable. +.It Va kern.elf64.allow_wx +Allow 64-bit processes to map pages simultaneously writable and executable. +.El +.\" +.Ss PROT_MAX +.Dv PROT_MAX +is a +.Fx Ns +-specific extension to +.Xr mmap 2 . +.Dv PROT_MAX +provides the ability to set the maximum protection of a region allocated by +.Xr mmap 2 +and later altered by +.Xr mprotect 2 . +For example, memory allocated originally with an mmap prot argument of +PROT_MAX(PROT_READ | PROT_WRITE) | PROT_READ +may be made writable by a future +.Xr mprotect 2 +call, but may not be made executable. +.\" +.Ss Relocation Read-Only (RELRO) +Relocation Read-Only (RELRO) is a mitigation tool that makes certain portions +of a program's address space that contain ELF metadata read-only, after +relocation processing by +.Xr rtld 1 . +.Pp +When enabled in isolation the RELRO option provides +.Em partial RELRO +support. +In this case the Procedure Linkage Table (PLT)-related part of the +Global Offset Table (GOT) (in the section typically named .got.plt) remains +writable. +.Pp +RELRO is enabled by default. +The +.Xr src.conf 5 +build-time option +.Va WITHOUT_RELRO +may be used to disable it. +.Ss BIND_NOW +The +.Va WITH_BIND_NOW +.Xr src.conf 5 +build-time option causes binaries to be built with the +.Dv DF_BIND_NOW +flag set. +The run-time loader +.Xr rtld 1 +will then perform all relocation processing when the process starts, instead of +on demand (on the first access to each symbol). +.Pp +When enabled in combination with +.Dv RELRO +(which is enabled by default) this provides +.Em full RELRO . +The entire GOT (.got and .got.plt) are made read-only at program startup, +preventing attacks on the relocation table. +Note that this results in a nonstandard Application Binary Interface (ABI), +and it is possible that some applications may not function correctly. +.\" +.Ss Stack Overflow Protection +.Fx +supports stack overflow protection using the Stack Smashing Protector +.Pq SSP +compiler feature. +Stack clash protection is also enabled, +if supported by the compiler for the given architecture. +In userland, SSP adds a per-process randomized canary at the end of every stack +frame which is checked for corruption upon return from the function, +and stack probing in +.Dv PAGE_SIZE +chunks. +In the kernel, a single randomized canary is used globally except on aarch64, +which has a +.Dv PERTHREAD_SSP +.Xr config 8 +option to enable per-thread randomized canaries. +If stack corruption is detected, then the process aborts to avoid potentially +malicious execution as a result of the corruption. +SSP may be enabled or disabled when building +.Fx +base with the +.Xr src.conf 5 +SSP knob. +.Pp +When +.Va WITH_SSP +is enabled, which is the default, world is built with the +.Fl fstack-protector-strong +and +.Fl fstack-clash-protection +compiler options. +The kernel is built with the +.Fl fstack-protector +option. +.Pp +In addition to SSP, a +.Dq FORTIFY_SOURCE +implementation is supported up to level 2 by defining +.Va _FORTIFY_SOURCE +to +.Dv 1 +or +.Dv 2 +before including any +.Fx +headers. +.Fx +world builds can set +.Va FORTIFY_SOURCE +in the environment or +.Pa /etc/src-env.conf +to provide a default value for +.Va _FORTIFY_SOURCE . +When enabled, +.Dq FORTIFY_SOURCE +enables extra bounds checking in various functions that accept buffers to be +written into. +These functions currently have extra bounds checking support: +.Bl -column -offset indent "snprintf()" "memmove()" "strncpy()" "vsnprintf()" "readlink()" +.It Fn bcopy Ta Fn bzero Ta Fn fgets Ta Fn getcwd Ta Fn gets +.It Fn memcpy Ta Fn memmove Ta Fn memset Ta Fn read Ta Fn readlink +.It Fn snprintf Ta Fn sprintf Ta Fn stpcpy Ta Fn stpncpy Ta Fn strcat +.It Fn strcpy Ta Fn strncat Ta Fn strncpy Ta Fn vsnprintf Ta Fn vsprintf +.El +.Pp +.Dq FORTIFY_SOURCE +requires compiler support from +.Xr clang 1 +or +.Xr gcc 1 , +which provide the +.Xr __builtin_object_size 3 +function that is used to determine the bounds of an object. +This feature works best at optimization levels +.Fl O1 +and above, as some object sizes may be less obvious without some data that the +compiler would collect in an optimization pass. +.Pp +Similar to SSP, violating the bounds of an object will cause the program to +abort in an effort to avoid malicious execution. +This effectively provides finer-grained protection than SSP for some class of +function and system calls, along with some protection for buffers allocated as +part of the program data. +.\" +.Ss Supervisor mode memory protection +Certain processors include features that prevent unintended access to memory +pages accessible to userspace (non-privileged) code, while in a privileged +mode. +One feature prevents execution, intended to mitigate exploitation of kernel +vulnerabilities from userland. +Another feature prevents unintended reads from or writes to user space memory +from the kernel. +This also provides effective protection against NULL pointer dereferences from +kernel. +.Bl -column -offset indent "Architecture" "Feature" "Access Type Prevented" +.It Sy Architecture Ta Sy Feature Ta Sy Access Type Prevented +.It amd64 Ta SMAP Ta Read / Write +.It amd64 Ta SMEP Ta Execute +.It arm64 Ta PAN Ta Read / Write +.It arm64 Ta PXN Ta Execute +.It riscv Ta SUM Ta Read / Write +.It riscv Ta - Ta Execute +.El +.Pp +These features are automatically used by the kernel. +There is no user-facing configuration. +.\" +.Ss Capsicum +Capsicum is a lightweight OS capability and sandbox framework. +See +.Xr capsicum 4 +for more information. +.Sh HARDWARE VULNERABILITY MITIGATIONS +.Ss Firmware and Microcode +Recent years have seen an unending stream of new hardware vulnerabilities, +notably CPU ones generally caused by detectable microarchitectural side-effects +of speculative execution which leak private data from some other thread or +process or sometimes even internal CPU state that is normally inaccessible. +Hardware vendors usually address these vulnerabilities as they are discovered by +releasing microcode updates, which may then be bundled into platform firmware +updates +.Pq historically called BIOS updates for PCs +or packages to be updated by the operating system at boot time. +.Pp +Platform firmware updates, if available from the manufacturer, +are the best defense as they provide coverage during early boot. +Install them with +.Pa sysutils/flashrom +from the +.Fx +Ports Collection. +.Pp +If platform firmware updates are no longer available, +packaged microcode is available for installation at +.Pa sysutils/cpu-microcode +and can be loaded at runtime using +.Xr loader.conf 5 , +see the package message for more details. +.Pp +The best defense overall against hardware vulnerabilities is to timely apply +these updates when available, as early as possible in the boot process, +and to disable the affected hardware's problematic functionalities when possible +(e.g., CPU Simultaneous Multi-Threading). +Software mitigations are only partial substitutes for these, but they can be +helpful on out-of-support hardware or as complements for just-discovered +vulnerabilities not yet addressed by vendors. +Some software mitigations depend on hardware capabilities provided by a +microcode update. +.Ss Architectural Vulnerability Mitigations +.Fx Ap s +usual policy is to apply by default all OS-level mitigations that do +not require recompilation, except those the particular hardware it is running on +is known not to be vulnerable to +.Pq which sometimes requires firmware updates , +or those that are extremely detrimental to performance in proportion to the +protection they actually provide. +OS-level mitigations generally can have noticeable performance impacts on +specific workloads. +If your threat model allows it, you may want to try disabling some of them in +order to possibly get better performance. +Conversely, minimizing the risks may require you to explicitly enable the most +expensive ones. +The description of each vulnerability/mitigation indicates whether it is enabled +or disabled by default and under which conditions. +It also lists the knobs to tweak to force a particular status. +.Ss Zenbleed +The +.Dq Zenbleed +vulnerability exclusively affects AMD processors based on the Zen2 +microarchitecture. +In contrast with, e.g., Meltdown and the different variants of Spectre, which +leak data by leaving microarchitectural traces, Zenbleed is a genuine hardware +bug affecting the CPU's architectural state. +With particular sequences of instructions whose last ones are mispredicted by +speculative execution, it is possible to make appear in an XMM register data +previously put in some XMM register by some preceding or concurrent task +executing on the same physical core +.Po disabling Simultaneous Muti-Threading +.Pq SMT +is thus not a sufficient protection +.Pc . +.Pp +According to the vulnerability's discoverer, all Zen2-based processors are +affected +.Po see +.Lk https://lock.cmpxchg8b.com/zenbleed.html +.Pc . +As of August 2023, AMD has not publicly listed any corresponding errata but has +issued a security bulletin +.Pq AMD-SB-7008 +entitled +.Dq Cross-Process Information Leak +indicating that platform firmware fixing the vulnerability will be distributed +to manufacturers no sooner than the end of 2023, except for Rome processors for +which it is already available. +No standalone CPU microcodes have been announced so far. +The only readily-applicable fix mentioned by the discoverer is to set a bit of +an undocumented MSR, which reportedly completely stops XMM register leaks. +.Pp +.Fx +currently sets this bit by default on all Zen2 processors. +In the future, it might set it by default only on those Zen2 processors whose +microcode has not been updated to revisions fixing the vulnerability, once such +microcode updates have been actually released and community-tested. +To this mitigation are associated the following knobs: +.Bl -tag -width indent +.It Va machdep.mitigations.zenbleed.enable +A read-write integer tunable and sysctl indicating whether the mitigation should +be forcibly disabled (0), enabled (1) or if it is left to +.Fx +to selectively apply it (2). +Any other integer value is silently converted to and treated as value 2. +Note that this setting is silently ignored when running on non-Zen2 processors +to ease applying a common configuration to heterogeneous machines. +.It Va machdep.mitigations.zenbleed.state +A read-only string indicating the current mitigation state. +It can be either +.Dq Not applicable , +if the processor is not Zen2-based, +.Dq Mitigation enabled +or +.Dq Mitigation disabled . +This state is automatically updated each time the sysctl +.Va machdep.mitigations.zenbleed.enable +is written to. +Note that it can become inaccurate if the chicken bit is set or cleared +directly via +.Xr cpuctl 4 +.Po which includes the +.Xr cpucontrol 8 +utility +.Pc . +.El +.Pp +The performance impact and threat models related to these mitigations +should be considered when configuring and deploying them in a +.Fx +system. +.Pp +Additional mitigation knobs are listed in the +.Sx KNOBS AND TWEAKS +section of +.Xr security 7 . +.Sh SEE ALSO +.Xr elfctl 1 , +.Xr proccontrol 1 , +.Xr rtld 1 , +.Xr mmap 2 , +.Xr src.conf 5 , +.Xr sysctl.conf 5 , +.Xr security 7 , +.Xr cpucontrol 8 , +.Xr sysctl 8 diff --git a/share/man/man7/named_attribute.7 b/share/man/man7/named_attribute.7 new file mode 100644 index 000000000000..a0599ef71496 --- /dev/null +++ b/share/man/man7/named_attribute.7 @@ -0,0 +1,320 @@ +.\" +.\" Copyright (c) 2025 Rick Macklem +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd August 5, 2025 +.Dt NAMED_ATTRIBUTE 7 +.Os +.Sh NAME +.Nm named_attribute +.Nd Solaris-like extended attribute system interface +.Sh DESCRIPTION +Description of the system interface for named attributes +(the NFS Version 4 terminology). +.Ss Introduction +This document describes an alternate system interface for extended +attributes as compared to +.Xr extattr 2 . +It is based on the interface provided by Solaris and NFS Version 4. +.Pp +This interface associates a directory, known as a named attribute directory, +to a file system object. +This directory is read in the same manner as a normal directory via the +.Xr getdents 2 +or +.Xr getdirentries 2 +system calls. +The +.Pa .\& +and +.Pa ..\& +entries refer to the directory itself and to the associated file object, +respectively. +The other entries in this directory +are the names of the extended attributes for the associated file object +and are referred to as named attributes. +These named attributes are regular files used to store the attribute's +value. +.Pp +A named attribute directory does not live in the file system's name space. +It is accessed via an +.Xr open 2 +or +.Xr openat 2 +system call done on a file to query the named attributes for the file, +with the +.Dv O_NAMEDATTR +flag specified and a +.Fa path +argument of +.Pa .\& . +This file descriptor can be used as the +.Fa fd +argument for a variety of system calls, such as: +.Xr fchdir 2 , +.Xr unlinkat 2 +and +.Xr renameat 2 . +.Xr renameat 2 +is only permitted to rename a named attribute within the same named +attribute directory. +.Pp +When a file descriptor for a file object in the file system's namespace +is used as the +.Fa fd +argument of an +.Xr openat 2 +along with the +.Fa flag +.Dv O_NAMEDATTR +and a +.Fa path +argument that is the name of a named attribute (not +.Pa .\& +or +.Pa ..\& +), a file descriptor for the named attribute is returned. +If the +.Fa flag +.Dv O_CREAT +is specified, the named attribute will be created if it does not exist. +The +.Fa path +argument must be a single component name, with no embedded +.Dq / +in it. +I/O on these named attribute file descriptors may be performed by +standard I/O system calls +such as: +.Xr read 2 , +.Xr write 2 , +.Xr lseek 2 +and +.Xr ftruncate 2 . +.Pp +The +.Dv _PC_NAMEDATTR_ENABLED +.Fa name +argument to +.Xr pathconf 2 +will return 1 if the file system supports named attributes. +The +.Dv _PC_HAS_NAMEDATTR +.Fa name +argument to +.Xr pathconf 2 +will return 1 if there are one or more named attributes for the file. +If an application does a +.Xr openat 2 +of +.Dq .\& +to open a named attribute directory when no named attribute directory exists, +an empty named attribute directory will be created. +Testing +.Dv _PC_HAS_NAMEDATTR +can be done to avoid creating these named attribute directories unnecessarily. +.Pp +The named attribute interface is a different mechanism/system call interface for +manipulating extended attributes compared with +.Xr extattr 2 . +Although the named attribute machanism might require different internal +implementation +of extended attributes within a file system, both ZFS and NFSv4 provide +both mechanisms, which can be used interchangeably to manipulate +extended attributes, but with a few limitations. +.Bl -bullet +.It +The +.Xr extattr 2 +interface requires that an extended attribute's value be set or acquired +via a single system call using a single buffer. +This limits the size of the attribute's value. +.It +The named attribute interface does not support system namespace +extended attributes and, +as such, system namespace extended attributes must be manipulated via +.Xr extattr 2 . +.It +For ZFS, if an extended attribute with a value +that is a small length in bytes is created when the ZFS +.Dv xattr +property is set to +.Dq sa , +that extended attribute is only visible via +.Xr extattr 2 +and not as a named attribute. +Archiving/de-archiving the file via +.Xr tar 1 +after setting the +.Dv xattr +property to +.Dq dir +will make the attribute(s) visible as both named attributes +and via +.Xr extattr 2 . +.It +For ZFS, it is also possible to create two attributes with the same +name by creating one when the ZFS +.Dv xattr +property is set to +.Dq sa +and then creating another one with the same name after the ZFS +property +.Dv xattr +has been changed to +.Dq dir . +The one created when the ZFS +.Dv xattr +property is set to +.Dq sa +may be removed via +.Xr rmextattr 8 . +.It +To avoid these issues for ZFS, it is strongly recommended that the ZFS +property +.Dv xattr +be set to +.Dq dir +as soon as the file system is created, if named attributes +are to be used on the file system. +.El +.Pp +The named attribute mechanism/system call interface provides certain +advantages over +.Xr extattr 2 . +Since the attribute's value is updated via +.Xr read 2 +and +.Xr write 2 +system calls, the attribute's data may be as large as any regular file +and may be partially updated. +(Note that this interface does not provide the atomicity guarantee that +.Xr extattr 2 +does.) +The permission to access a named attribute directory is determined from +the access control information for the associated file object. +However, access control information can be set on each individual attribute +in a manner similar to a regular file. +This provides +.Dq per attribute +granular control over attribute permissions via +.Xr fchown 2 . +.Pp +At this time, the only local file system which supports this interface +is ZFS and only if the +.Dv xattr +property is set to +.Dq dir . +(Note that, even when +.Dq zfs get xattr <file-system> +shows +.Dq on +the command +.Dq zfs set xattr=dir <file-system> +must be done, followed by a remount to make the setting take effect.) +A NFSv4 mount will also support this interface, but only if the NFSv4 +server file system supports named attributes (the openattr operation). +The +.Fx +NFSv4 server supports named attributes only +for ZFS exported file systems where the +.Dq xattr +property is set to +.Dq dir +for the file system. +.Sh EXAMPLES +.Bd -literal +#include <stdio.h> +#include <dirent.h> +#include <fcntl.h> +#include <unistd.h> + +\&... + +/* For a file called "myfile". Failure checks removed for brevity. */ +int file_fd, nameddir_fd, namedattr_fd; +ssize_t siz; +char buf[DIRBLKSIZ], *cp; +struct dirent *dp; +long named_enabled, has_named_attrs; + +\&... +/* Check to see if named attributes are supported. */ +named_enabled = pathconf("myfile", _PC_NAMEDATTR_ENABLED); +if (named_enabled <= 0) + err(1, "Named attributes not enabled"); +/* Test to see if named attribute(s) exist for the file. */ +has_named_attrs = pathconf("myfile", _PC_HAS_NAMEDATTR); +if (has_named_attrs == 1) + printf("myfile has named attribute(s)\\n"); +else + printf("myfile does not have any named attributes\\n"); +/* Open a named attribute directory. */ +file_fd = open("myfile", O_RDONLY, 0); +nameddir_fd = openat(file_fd, ".", O_NAMEDATTR, 0); +\&... +/* and read it, assuming it all fits in DIRBLKSIZ for simplicity. */ +siz = getdents(fd, buf, sizeof(buf)); +cp = buf; +while (cp < &buf[siz]) { + dp = (struct dirent *)cp; + printf("name=%s\\n", dp->d_name); + cp += dp->d_reclen; +} +\&... +/* Open/create a named attribute called "foo". */ +namedattr_fd = openat(file_fd, "foo", O_CREAT | O_RDWR | + O_TRUNC | O_NAMEDATTR, 0600); +\&... +/* Write foo's attribute value. */ +write(namedattr_fd, "xxxyyy", 6); +\&... +/* Read foo's attribute value. */ +lseek(namedattr_fd, 0, SEEK_SET); +siz = read(namedattr_fd, buf, sizeof(buf)); +\&... +/* And close "foo". */ +close(namedattr_fd); +\&... +/* Rename "foo" to "oldfoo". */ +renameat(nameddir_fd, "foo", nameddir_fd, "oldfoo"); +/* and delete "oldfoo". */ +unlinkat(nameddir_fd, "oldfoo", AT_RESOLVE_BENEATH); +.Ed +.Pp +The +.Xr runat 1 +command may be used to perform shell commands on named attributes. +For example: +.Bd -literal +$ runat myfile cp /etc/hosts attrhosts # creates attrhosts +$ runat myfile cat attrhosts # displays contents of attrhosts +$ runat myfile ls -l # lists the attributes for myfile +.Ed +.Pp +If using the +.Xr bash 1 +shell, the command +.Dq cd -@ foo +enters the named attribute directory for the file object +.Dq foo . +.Sh SEE ALSO +.Xr bash 1 , +.Xr runat 1 , +.Xr tar 1 , +.Xr chdir 2 , +.Xr extattr 2 , +.Xr lseek 2 , +.Xr open 2 , +.Xr pathconf 2 , +.Xr read 2 , +.Xr rename 2 , +.Xr truncate 2 , +.Xr unlinkat 2 , +.Xr write 2 , +.Xr zfsprops 7 , +.Xr rmextattr 8 +.Sh HISTORY +This interface first appeared in +.Fx 15.0 . diff --git a/share/man/man7/networking.7 b/share/man/man7/networking.7 new file mode 100644 index 000000000000..2174577eb6a3 --- /dev/null +++ b/share/man/man7/networking.7 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2024 Alexander Ziaee. Ohio. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd March 21, 2025 +.Dt NETWORKING 7 +.Os +.Sh NAME +.Nm networking , +.Nm wifi +.Nd quickstart guide to connecting to a network +.Sh DESCRIPTION +In the following examples, it is assumed that +we are connecting to Ethernet with the first interface found by the +.Xr ix 4 +driver, and Wi-Fi with the first interface found by the +.Xr iwlwifi 4 +driver, though your hardware will vary. +.Sh EXAMPLES +.Bl -tag -width 0n +.It Sy Example 1: Connecting to an Ethernet network with DHCP +.Pp +Ask for a DHCP lease on the first Intel 10Gb Ethernet interface: +.Bd -literal -offset 2n +.Ic # dhclient ix0 +.Ed +.It Sy Example 2: Connecting to a cellular network with USB tethering +.Pp +Ask for a DHCP lease on the first USB tethering interface: +.Bd -literal -offset 2n +.Ic # dhclient ue0 +.Ed +.It Sy Example 3: Connecting to a Wi-Fi network +.Pp +Identify your Wi-Fi hardware: +.Bd -literal -offset 2n +.Ic % sysctl net.wlan.devices +.Ed +.Pp +Create the +.Sy wlan0 +interface with the first Intel Wi-Fi adapter: +.Bd -literal -offset 2n +.Ic # sysrc wlans_iwlwifi0="wlan0" +.Ed +.Pp +Set that interface to ask for a DHCP lease with +.Xr wpa_supplicant 8 : +.Bd -literal -offset 2n +.Ic # sysrc ifconfig_wlan0="WPA SYNCDHCP" +.Ed +.Pp +Enter the details of the Wi-Fi network: +.Bd -literal -offset 2n +.Ic # cd /etc/ +.Ic # wpa_passphrase \(dqmyssid\(dq \(dqmypassphrase\(dq >> wpa_supplicant.conf +.Ed +.Pp +Restart the network interface daemon: +.Bd -literal -offset 2n +.Ic # service netif restart +.Ed +.It Sy Example 4: Scanning for Wi-Fi networks +.Bd -literal -offset 2n +.Ic % ifconfig wlan0 scan +.Ed +.It Sy Example 5: Airplane mode +.Bd -literal -offset 2n +.Ic # service netif stop +.Ed +.El +.Sh SEE ALSO +.Xr bsdconfig 8 , +.Xr dhclient 8 , +.Xr ifconfig 8 , +.Xr wpa_passphrase 8 +.Pp +The Advanced Networking chapter of the +.Fx +Handbook. +.Sh CAVEATS +Shell Special Characters in the +.Ar SSID +or +.Ar passphrase +will need to be escaped for +.Xr wpa_passphrase 8 , +commonly using +.Ql \e , +see the manual page for your shell for more details. +.Pp +Stopping the network interface service also stops internal networking. diff --git a/share/man/man7/operator.7 b/share/man/man7/operator.7 index 1971f2ff7ff0..8d6f0d7085a4 100644 --- a/share/man/man7/operator.7 +++ b/share/man/man7/operator.7 @@ -25,9 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)operator.7 8.1 (Berkeley) 6/9/93 -.\" $FreeBSD$ -.\" .Dd April 8, 2009 .Dt OPERATOR 7 .Os diff --git a/share/man/man7/orders.7 b/share/man/man7/orders.7 index e8aa4d79f9f2..c1c2c1200e42 100644 --- a/share/man/man7/orders.7 +++ b/share/man/man7/orders.7 @@ -27,9 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd August 6, 2011 +.Dd November 20, 2022 .Dt ORDERS 7 .Os .Sh NAME @@ -48,6 +46,8 @@ The following table lists common multiples of bytes. .It Exabyte Ta EB Ta 2^60 Ta 10^18 .It Zettabyte Ta ZB Ta 2^70 Ta 10^21 .It Yottabyte Ta YB Ta 2^80 Ta 10^24 +.It Ronnabyte Ta RB Ta 2^90 Ta 10^27 +.It Quettabyte Ta QB Ta 2^100 Ta 10^30 .El .Pp The following table lists common bit rates as a power of ten. @@ -70,6 +70,8 @@ The following table lists common orders of magnitude as a power of ten. .Bl -column -offset 2n \ "Septillionth" "Order" "Prefix" "Symbol" "Decimal" .It Sy Name Ta Sy Order Ta Sy Prefix Ta Sy Symbol Ta Sy Decimal +.It Nonillionth Ta 10^-30 Ta quecto Ta q Ta 0.000000000000000000000000000001 +.It Octillionth Ta 10^-27 Ta ronto Ta r Ta 0.000000000000000000000000001 .It Septillionth Ta 10^-24 Ta yocto Ta y Ta 0.000000000000000000000001 .It Sextillionth Ta 10^-21 Ta zepto Ta z Ta 0.000000000000000000001 .It Quintillionth Ta 10^-18 Ta atto Ta a Ta 0.000000000000000001 @@ -91,6 +93,8 @@ The following table lists common orders of magnitude as a power of ten. .It Quintillion Ta 10^18 Ta exa Ta E Ta 1000000000000000000 .It Sextillion Ta 10^21 Ta zetta Ta Z Ta 1000000000000000000000 .It Septillion Ta 10^24 Ta yotta Ta Y Ta 1000000000000000000000000 +.It Octillion Ta 10^27 Ta ronna Ta R Ta 1000000000000000000000000000 +.It Nonillion Ta 10^30 Ta quetta Ta Q Ta 1000000000000000000000000000000 .El .Sh SEE ALSO .Xr units 1 , diff --git a/share/man/man7/ports.7 b/share/man/man7/ports.7 index 4ffa418d1dbb..75070ce852fe 100644 --- a/share/man/man7/ports.7 +++ b/share/man/man7/ports.7 @@ -1,4 +1,6 @@ .\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 1997 David E. O'Brien .\" .\" All rights reserved. @@ -23,9 +25,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. .\" -.\" $FreeBSD$ -.\" -.Dd July 22, 2021 +.Dd September 10, 2025 .Dt PORTS 7 .Os .Sh NAME @@ -165,7 +165,7 @@ target. Configure .Va OPTIONS for this port using -.Xr dialog4ports 1 . +.Xr portconfig 1 Pq Pa ports/ports-mgmt/portconfig . .It Cm fetch Fetch all of the files needed to build this port from the sites listed in @@ -247,22 +247,22 @@ configured. Configure .Va OPTIONS for this port and all its dependencies using -.Xr dialog4ports 1 . +.Xr portconfig 1 Pq Pa ports/ports-mgmt/portconfig . .It Cm fetch-list -Show list of files to be fetched in order to build the port. +Show the list of files to fetch in order to build the port (but not its +dependencies). .It Cm fetch-recursive Fetch the distfiles of the port and all its dependencies. .It Cm fetch-recursive-list Show list of files that would be retrieved by .Cm fetch-recursive . -.It Cm run-depends-list , build-depends-list -Print a list of all the compile and run dependencies, and dependencies -of those dependencies, by port directory. +.It Cm build-depends-list , run-depends-list +Print a list of all the direct compile or run dependencies for this port. .It Cm all-depends-list -Print a list of all dependencies for the port. -.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list -Print a list of all the compile and run dependencies, and dependencies -of those dependencies, by port name and version. +Print a list of all recursive dependencies for this port. +.It Cm pretty-print-build-depends-list , pretty-print-run-depends-list +Print a list of all the recursive compile or run dependencies for this port by +port name and version. .It Cm missing Print a list of missing dependencies to be installed for the port. .It Cm clean @@ -506,7 +506,7 @@ cluster (for .Cm fetchindex target). Defaults to -.Pa https://www.FreeBSD.org/ports/ . +.Pa https://download.FreeBSD.org/ports/index/ . .It Va FETCHINDEX Command to get .Pa INDEX @@ -683,7 +683,7 @@ WITH_DEBUG_PORTS= mail/dovecot security/krb5 .Pp It is also possible to use the debug variables on the command line: .Bd -literal -offset 2n -.Li # Ic make -DWITH_DEBUG DEBUG_FLAGS="-g -O0" build +.Li # Ic make WITH_DEBUG DEBUG_FLAGS="-g -O0" build .Ed .Pp See the @@ -739,16 +739,16 @@ Additional user documentation: .It .Xr pkg 8 .It -.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" +.Lk "https://ports.FreeBSD.org" "Searchable index of all ports" .El .Sh HISTORY The Ports Collection appeared in .Fx 1.0 . It has since spread to -.Nx -and -.Ox . +.Nx , +.Ox , +and macOS. .Sh AUTHORS .An -nosplit This manual page was originated by diff --git a/share/man/man7/release.7 b/share/man/man7/release.7 index be475979dd0f..2493a34721bc 100644 --- a/share/man/man7/release.7 +++ b/share/man/man7/release.7 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 2002 Murray Stokely <murray@FreeBSD.org> .\" All rights reserved. .\" @@ -22,9 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd July 21, 2022 +.Dd October 13, 2025 .Dt RELEASE 7 .Os .Sh NAME @@ -138,6 +139,8 @@ configuration file supports the following variables: .Bl -tag -width Ev .It Va CHROOTDIR The directory within which the release will be built. +Defaults to +.Pa /scratch . .It Va CHROOT_MAKEENV Additional .Xr make 1 @@ -152,7 +155,7 @@ The .Xr git 1 host used to check out the various trees. Defaults to -.Pa https://git.FreeeBSD.org . +.Pa https://git.FreeBSD.org . .It Va SRCBRANCH The .Li src/ @@ -284,6 +287,23 @@ within the This is intended for use only when .Fa /usr/ports is expected to exist by alternative means. +.It Va PKGBASE +Include base system packages for use with +.Xr pkg 8 +on the install media, instead of legacy tarball distribution sets. +.It Va PKG_CMD +A path to the +.Xr pkg 8 +executable to use when installing packages in release images as a non-root user. +.It Va PKG_REPOS_DIR +An optional path to a directory containing +.Xr pkg 8 +repository configuration files. +These configuration files will be used when installing packages in release +images as a non-root user. +.It Va PKG_REPO_NAME +The name of the repository configuration to use when installing packages in +release images as a non-root user. .El .Sh EMBEDDED BUILDS The following @@ -365,6 +385,25 @@ is used, the resulting files compressed with .Xr xz 1 compress to roughly the same size, regardless of the specified disk image size. +.It Va VMFS +(Deprecated.) +Set to specify which of the filesystem(s) listed in +.Va VMFSLIST +is linked to the historical non-filesystem-labelled file name. +Valid values are +.Va ufs +and +.Va zfs . +The default value is +.Va ufs . +.It Va VMFSLIST +Set to specify the list of file system types to build images for. +Valid values are one or both of +.Va ufs +and +.Va zfs . +The default value is +.Va ufs zfs . .It Va VMFORMATS Set to the target virtual disk image format(s) to create. By default, the @@ -426,6 +465,18 @@ values, run: cd /usr/src make -C release list-cloudware .Ed +.Sh OCI IMAGES +The +.Fx +release build tools have experimental support for building +Open Container Initiative (OCI) format container base images. +This is enabled using a +.Fa release.conf +variable: +.Bl -tag -width Ev +.It Va WITH_OCIIMAGES +Set to a non-null value to build OCI base images. +.El .Sh MAKEFILE TARGETS The release makefile .Pq Pa src/release/Makefile @@ -503,7 +554,7 @@ Displays the list of valid values. .It Cm list-vmtargets Displays the list of valid -.Va VMFORMAT +.Va VMFORMATS and .Va CLOUDWARE values. @@ -590,6 +641,7 @@ Typically, one only needs to set .El .Sh FILES .Bl -tag -compact -width Pa +.It Pa /scratch .It Pa /usr/doc/Makefile .It Pa /usr/doc/share/mk/doc.project.mk .It Pa /usr/ports/Mk/bsd.port.mk @@ -642,16 +694,10 @@ the Raspberry Pi, exist in the directory corresponding to the .Va TARGET .Xr make 1 variable. -For example, to build an image for the Raspberry Pi: -.Bd -literal -offset indent -cd /usr/src/release -sh release.sh -c arm/RPI-B.conf -.Ed -.Pp -To build an image for the Raspberry Pi 3: +For example, to build an image for 64-bit Raspberry Pis: .Bd -literal -offset indent cd /usr/src/release -sh release.sh -c arm64/RPI3.conf +sh release.sh -c arm64/RPI.conf .Ed .Pp After running these commands, all prepared release files are available in the diff --git a/share/man/man7/sdoc.7 b/share/man/man7/sdoc.7 index d678c97e2818..cdfb25f0f59a 100644 --- a/share/man/man7/sdoc.7 +++ b/share/man/man7/sdoc.7 @@ -26,7 +26,6 @@ .\" SUCH DAMAGE. .\" .\" $Id: sec-doc.7,v 1.7 2001/12/22 00:14:12 rwatson Exp$ -.\" $FreeBSD$ .\" .Dd September 5, 2005 .Dt SDOC 7 diff --git a/share/man/man7/security.7 b/share/man/man7/security.7 index 49701bbe80f1..f1035fd093d5 100644 --- a/share/man/man7/security.7 +++ b/share/man/man7/security.7 @@ -1,5 +1,5 @@ .\" Copyright (C) 1998 Matthew Dillon. All rights reserved. -.\" Copyright (c) 2019 The FreeBSD Foundation, Inc. +.\" Copyright (c) 2019 The FreeBSD Foundation .\" .\" Parts of this documentation were written by .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship @@ -26,15 +26,21 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd January 14, 2022 +.Dd June 1, 2024 .Dt SECURITY 7 .Os .Sh NAME .Nm security .Nd introduction to security under FreeBSD .Sh DESCRIPTION +See +.Xr mitigations 7 +for a description of vulnerability mitigations in +.Fx . +This man page documents other +.Fx +security related topics. +.Pp Security is a function that begins and ends with the system administrator. While all .Bx @@ -97,9 +103,9 @@ It may not be able to take your machine down, but it can fill up your Internet pipe. .Pp A user account compromise is even more common than a DoS attack. -Many -sysadmins still run standard -.Xr telnetd 8 +Some +sysadmins still run +.Nm telnetd and .Xr ftpd 8 servers on their machines. @@ -338,8 +344,8 @@ virtually every server ever run as root, including basic system servers. If you are running a machine through which people only log in via .Xr sshd 8 and never log in via -.Xr telnetd 8 -then turn off those services! +.Nm telnetd +then turn off this service! .Pp .Fx now defaults to running @@ -358,7 +364,6 @@ There are a number of other servers that typically do not run in sandboxes: .Xr sendmail 8 , .Xr popper 8 , .Xr imapd 8 , -.Xr ftpd 8 , and others. There are alternatives to some of these, but installing them may require more work than you are willing @@ -537,7 +542,10 @@ kernel modules (see may not be loaded or unloaded. The kernel debugger may not be entered using the .Va debug.kdb.enter -sysctl. +sysctl unless a +.Xr MAC 9 +policy grants access, for example using +.Xr mac_ddb 4 . A panic or trap cannot be forced using the .Va debug.kdb.panic , .Va debug.kdb.panic_str @@ -958,16 +966,18 @@ Backwards compatibility shims for the interim sysctls under will not be added. .Bl -tag -width security.bsd.unprivileged_proc_debug .It Dv security.bsd.see_other_uids -Controls visibility of processes owned by different uid. +Controls visibility and reachability of subjects (e.g., processes) and objects +(e.g., sockets) owned by a different uid. The knob directly affects the .Dv kern.proc sysctls filtering of data, which results in restricted output from utilities like .Xr ps 1 . .It Dv security.bsd.see_other_gids -Same, for processes owned by different gid. +Same, for subjects and objects owned by a different gid. .It Dv security.bsd.see_jail_proc -Same, for processes belonging to a jail. +Same, for subjects and objects belonging to a different jail, including +sub-jails. .It Dv security.bsd.conservative_signals When enabled, unprivileged users are only allowed to send job control and usual termination signals like @@ -1047,7 +1057,7 @@ Controls mitigation of Special Register Buffer Data Sampling versus optimization of the MCU access. When set to zero, the mitigation is disabled, and the RDSEED and RDRAND instructions do not incur serialization overhead for shared buffer accesses, -and do not serialize off-core memory accessses. +and do not serialize off-core memory accesses. .It Dv kern.elf32.aslr.enable Controls system-global Address Space Layout Randomization (ASLR) for normal non-PIE (Position Independent Executable) 32-bit ELF binaries. @@ -1062,8 +1072,7 @@ position-independent (PIE) 32-bit binaries. Makes ASLR less aggressive and more compatible with old binaries relying on the sbrk area. .It Dv kern.elf32.aslr.stack -If ASLR is enabled for a binary, a non-zero value enables randomization -of the stack. +Enable randomization of the stack for 32-bit binaries. Otherwise, the stack is mapped at a fixed location determined by the process ABI. .It Dv kern.elf64.aslr.enable @@ -1098,6 +1107,7 @@ Enables mapping of simultaneously writable and executable pages for .Xr xdm 1 Pq Pa ports/x11/xorg-clients , .Xr group 5 , .Xr ttys 5 , +.Xr mitigations 7 , .Xr accton 8 , .Xr init 8 , .Xr sshd 8 , diff --git a/share/man/man7/simd.7 b/share/man/man7/simd.7 new file mode 100644 index 000000000000..d5092348d9b3 --- /dev/null +++ b/share/man/man7/simd.7 @@ -0,0 +1,242 @@ +.\" Copyright (c) 2023 The FreeBSD Foundation +. +.\" This documentation was written by Robert Clausecker <fuz@FreeBSD.org> +.\" under sponsorship from the FreeBSD Foundation. +. +.\" 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 November 18, 2024 +.Dt SIMD 7 +.Os +.Sh NAME +.Nm simd +.Nd SIMD enhancements +. +.Sh DESCRIPTION +On some architectures, the +.Fx +.Em libc +provides enhanced implementations of commonly used functions, replacing +the architecture-independent implementations used otherwise. +Depending on architecture and function, an enhanced +implementation of a function may either always be used or the +.Em libc +detects at runtime which SIMD instruction set extensions are +supported and picks the most suitable implementation automatically. +On +.Cm amd64 , +the environment variable +.Ev ARCHLEVEL +can be used to override this mechanism. +.Pp +Enhanced functions are present for the following architectures: +.Bl -column FUNCTION_________ aarch64_ arm_ amd64_ i386_ ppc64_ -offset indent +.It Em FUNCTION Ta Em AARCH64 Ta Em ARM Ta Em AMD64 Ta Em I386 Ta Em PPC64 +.It bcmp Ta A Ta Ta S1 Ta S +.It bcopy Ta A Ta S Ta S Ta S Ta SV +.It bzero Ta A Ta S Ta S Ta S +.It div Ta Ta Ta S Ta S +.It index Ta A Ta Ta S1 +.It ldiv Ta Ta Ta S Ta S +.It lldiv Ta Ta Ta S +.It memchr Ta A Ta Ta S1 +.It memcmp Ta A Ta S Ta S1 Ta S +.It memccpy Ta A Ta Ta S1 +.It memcpy Ta A Ta S Ta S Ta S Ta SV +.It memmove Ta A Ta S Ta S Ta S Ta SV +.It memrchr Ta A Ta Ta S1 +.It memset Ta A Ta S Ta S Ta S +.It rindex Ta A Ta Ta S1 Ta S +.It stpcpy Ta A Ta Ta S1 +.It stpncpy Ta Ta Ta S1 +.It strcat Ta A Ta Ta S1 Ta S +.It strchr Ta A Ta Ta S1 Ta S +.It strchrnul Ta A Ta Ta S1 +.It strcmp Ta A Ta S Ta S1 Ta S +.It strcpy Ta A Ta Ta S1 Ta S Ta S2 +.It strcspn Ta S Ta Ta S2 +.It strlcat Ta A Ta Ta S1 +.It strlcpy Ta A Ta Ta S1 +.It strlen Ta A Ta S Ta S1 +.It strncat Ta A Ta Ta S1 +.It strncmp Ta A Ta S Ta S1 Ta S +.It strncpy Ta Ta Ta S1 Ta Ta S2 +.It strnlen Ta A Ta Ta S1 +.It strrchr Ta A Ta Ta S1 Ta S +.It strpbrk Ta S Ta Ta S2 +.It strsep Ta S Ta Ta S2 +.It strspn Ta S Ta Ta S2 +.It swab Ta Ta Ta Ta S +.It timingsafe_bcmp Ta A Ta Ta S1 +.It timingsafe_memcmp Ta S Ta Ta S +.It wcschr Ta Ta Ta Ta S +.It wcscmp Ta Ta Ta Ta S +.It wcslen Ta Ta Ta Ta S +.It wmemchr Ta Ta Ta Ta S +.El +.Pp +.Sy S Ns :\ scalar (non-SIMD), +.Sy 1 Ns :\ amd64 baseline, +.Sy 2 Ns :\ x86-64-v2 +or PowerPC\ 2.05, +.Sy 3 Ns :\ x86-64-v3, +.Sy 4 Ns :\ x86-64-v4, +.Sy V Ns :\ PowerPC\ VSX, +.Sy A Ns :\ Arm\ ASIMD (NEON). +. +.Sh ENVIRONMENT +.Bl -tag +.It Ev ARCHLEVEL +On +.Em amd64 , +controls the level of SIMD enhancements used. +If this variable is set to an architecture level from the list below +and that architecture level is supported by the processor, SIMD +enhancements up to +.Ev ARCHLEVEL +are used. +If +.Ev ARCHLEVEL +is unset, not recognised, or not supported by the processor, the highest +level of SIMD enhancements supported by the processor is used. +.Pp +A suffix beginning with +.Sq ":" +or +.Sq "+" +in +.Ev ARCHLEVEL +is ignored and may be used for future extensions. +The architecture level can be prefixed with a +.Sq "!" +character to force use of the requested architecture level, even if the +processor does not advertise that it is supported. +This usually causes applications to crash and should only be used for +testing purposes or if architecture level detection yields incorrect +results. +.Pp +The architecture levels follow the AMD64 SysV ABI supplement: +.Bl -tag -width x86-64-v2 +.It Cm scalar +scalar enhancements only (no SIMD) +.It Cm baseline +cmov, cx8, x87 FPU, fxsr, MMX, osfxsr, SSE, SSE2 +.It Cm x86-64-v2 +cx16, lahf/sahf, popcnt, SSE3, SSSE3, SSE4.1, SSE4.2 +.It Cm x86-64-v3 +AVX, AVX2, BMI1, BMI2, F16C, FMA, lzcnt, movbe, osxsave +.It Cm x86-64-v4 +AVX-512F/BW/CD/DQ/VL +.El +.El +. +.Sh DIAGNOSTICS +.Bl -diag +.It "Illegal Instruction" +Printed by +.Xr sh 1 +if a command is terminated through delivery of a +.Dv SIGILL +signal, see +.Xr signal 3 . +.Pp +Use of an unsupported architecture level was forced by setting +.Ev ARCHLEVEL +to a string beginning with a +.Sq "!" +character, causing a process to crash due to use of an unsupported +instruction. +Unset +.Ev ARCHLEVEL , +remove the +.Sq "!" +prefix or select a supported architecture level. +.Pp +Message may also appear for unrelated reasons. +.El +. +.Sh SEE ALSO +.Xr string 3 , +.Xr arch 7 +.Rs +.%A H. J. Lu +.%A Michael Matz +.%A Milind Girkar +.%A Jan Hubi\[u010D]ka \" \(vc +.%A Andreas Jaeger +.%A Mark Mitchell +.%B System V Application Binary Interface +.%D May 23, 2023 +.%T AMD64 Architecture Processor Supplement +.%O Version 1.0 +.Re +. +.Sh HISTORY +Architecture-specific enhanced +.Em libc +functions were added starting +with +.Fx 2.0 +for +.Cm i386 , +.Fx 6.0 +for +.Cm arm , +.Fx 6.1 +for +.Cm amd64 , +.Fx 11.0 +for +.Cm aarch64 , +and +.Fx 12.0 +for +.Cm powerpc64 . +SIMD-enhanced functions were first added with +.Fx 13.0 +for +.Cm powerpc64 +and with +.Fx 14.1 +for +.Cm amd64 . +.Pp +A +.Nm +manual page appeared in +.Fx 14.1 . +. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org +. +.Sh CAVEATS +Other parts of +.Fx +such as cryptographic routines in the kernel or in +OpenSSL may also use SIMD enhancements. +These enhancements are not subject to the +.Ev ARCHLEVEL +variable and may have their own configuration +mechanism. +. +.Sh BUGS +Use of SIMD enhancements cannot be configured on powerpc64. diff --git a/share/man/man7/sizeof.7 b/share/man/man7/sizeof.7 new file mode 100644 index 000000000000..b3c3af1acb52 --- /dev/null +++ b/share/man/man7/sizeof.7 @@ -0,0 +1,308 @@ +.\" +.\" Copyright (C) 2022 Jan Schaumann <jschauma@netmeister.org>. +.\" +.\" 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 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 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 December 12, 2022 +.Dt sizeof 7 +.Os +.Sh NAME +.Nm sizeof +operator +.Nd yield the storage size of the given operand +.Sh SYNTAX +.Nm Vt ( type ) +.br +.Nm Vt expression +.Sh DESCRIPTION +The +.Nm +operator yields the size of its operand. +The +.Nm +operator cannot be applied to incomplete types and expressions +with incomplete types (e.g. +.Vt void , +or forward-defined +.Vt struct foo ), +and function types. +.Pp +The size of primitive (non-derived) data types in C may differ +across hardware platforms and implementations. +They are defined by corresponding Application Binary Interface (ABI) +specifications, see +.Xr arch 7 +for details about ABI used by +.Fx . +It may be necessary or useful for a program to be able +to determine the storage size of a data type or object +to account for the platform specifics. +.Pp +The unary +.Nm +operator yields the storage size of an expression or +data type in +.Em char sized units +(C language bytes). +As a result, +.Ql sizeof(char) +is always guaranteed to be 1. +(The number of bits per +.Vt char +is given by the +.Dv CHAR_BIT +definition in the +.In limits.h +header; many systems also provide the "number of bits +per byte" definition as +.Dv NBBY +in the +.In sys/param.h +header.) +.Sh EXAMPLES +Different platforms may use different data models. +For example, systems on which integers, longs, and +pointers are using 32 bits (e.g., i386) are referred +to as using the "ILP32" data model, systems using +64 bit longs and pointers (e.g., amd64 / x86_64) +as the "LP64" data model. +.Pp +The following examples illustrate the possible results +of calling +.Nm +on an ILP32 vs. an LP64 system: +.Pp +When applied to a simple variable or data type, +.Nm +returns the storage size of the data type of the object: +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32)" ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(char) \ + Ta 1 \ + Ta 1 +.It Li sizeof(int) \ + Ta 4 \ + Ta 4 +.It Li sizeof(long) \ + Ta 4 \ + Ta 8 +.It Li sizeof(float) \ + Ta 4 \ + Ta 4 +.It Li sizeof(double) \ + Ta 8 \ + Ta 8 +.It Li sizeof(char *) \ + Ta 4 \ + Ta 8 +.El +.Pp +For initialized data or uninitialized arrays of a +fixed size known at compile time, +.Nm +will return the correct storage size: +.Bd -literal -offset indent +#define DATA "1234567890" +char buf1[] = "abc"; +char buf2[1024]; +char buf3[1024] = { 'a', 'b', 'c' }; +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result" +.It Sy Object or type \ + Ta Sy Result +.It Li sizeof(DATA) \ + Ta 11 +.It Li sizeof(buf1) \ + Ta 4 +.It Li sizeof(buf2) \ + Ta 1024 +.It Li sizeof(buf3) \ + Ta 1024 +.El +.Pp +The examples above are the same for ILP32 and LP64 +platforms, as they are based on character units. +.Pp +When applied to a struct or union, +.Nm +returns the total number of bytes in the object, +including any internal or trailing padding used to +align the object in memory. +This result may thus be larger than if the storage +size of each individual member had been added: +.Bd -literal -offset indent +struct s1 { + char c; +}; + +struct s2 { + char *s; + int i; +}; + +struct s3 { + char *s; + int i; + int j; +}; + +struct s4 { + int i; + uint64_t i64; +}; + +struct s5 { + struct s1 a; + struct s2 b; + struct s3 c; + struct s4 d; +}; +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32) " ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(struct s1) \ + Ta 1 \ + Ta 1 +.It Li sizeof(struct s2) \ + Ta 8 \ + Ta 16 +.It Li sizeof(struct s3) \ + Ta 12 \ + Ta 16 +.It Li sizeof(struct s4) \ + Ta 12 \ + Ta 16 +.It Li sizeof(struct s5) \ + Ta 36 \ + Ta 56 +.El +.Pp +When applied to a struct containing a flexible array +member, +.Nm +returns the size of the struct +.Em without +the array, although again possibly including any +padding the compiler deemed appropriate: +.Bd -literal -offset indent +struct flex { + char c; + long b; + char array[]; +} +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32) " ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(struct flex) \ + Ta 8 \ + Ta 16 +.El +.Pp +One of the more common uses of the +.Nm +operator is to determine the correct amount of memory +to allocate: +.Bd -literal -offset indent +int *nums = calloc(512, sizeof(int)); +.Ed +.Pp +The +.Nm +operator can be used to calculate the number of +elements in an array by dividing the size of the array +by the size of one of its elements: +.Bd -literal -offset indent +int nums[] = { 1, 2, 3, 4, 5 }; +const int howmany = sizeof(nums) / sizeof(nums[0]); +.Ed +.Pp +Many systems provide this shortcut as the macro +.Dv ntimes() +via the +.In sys/param.h +header file. +.Sh RESULT +The result of the +.Nm +operator is an unsigned integer type, defined in the +.Dv stddef.h +header as a +.Vt size_t . +.Sh NOTES +It is a common mistake to apply +.Nm +to a dynamically allocated array: +.Bd -literal -offset indent +char *buf; +if ((buf = malloc(BUFSIZ)) == NULL) { + perror("malloc"); +} +/* Warning: wrong! */ +(void)strncat(buf, input, sizeof(buf) - 1); +.Ed +.Pp +In that case, the operator will return the storage +size of the pointer ( +.Ql sizeof(char *) +), not the +allocated memory. +.Pp +.Nm +determines the +.Ev size +of the result of the expression given, but +.Em does not +evaluate the expression: +.Bd -literal -offset indent +int a = 42; +printf("%ld - %d\\n", sizeof(a = 10), a); /* Result: "4 - 42" */ +.Ed +.Pp +Since it is evaluated by the compiler and not the +preprocessor, the +.Nm +operator cannot be used in a preprocessor expression. +.Sh SEE ALSO +.Xr arch 7 , +.Xr operator 7 +.Sh STANDARDS +The +.Nm +operator conforms to +.St -ansiC . +.Pp +Handling of flexible array members in structures +conforms to +.St -isoC-99 . +.Sh AUTHORS +This manual page was written by +.An Jan Schaumann Aq Mt jschauma@netmeister.org . diff --git a/share/man/man7/sprog.7 b/share/man/man7/sprog.7 index f5a2d9ca4ec6..cc021a39b807 100644 --- a/share/man/man7/sprog.7 +++ b/share/man/man7/sprog.7 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd June 3, 2001 .Dt SPROG 7 .Os diff --git a/share/man/man7/stats.7 b/share/man/man7/stats.7 index 8be124392d19..0b57d525522c 100644 --- a/share/man/man7/stats.7 +++ b/share/man/man7/stats.7 @@ -1,5 +1,5 @@ .\" -.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2020 Daniel Ebdrup Jensen .\" @@ -24,9 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd April 22, 2021 +.Dd October 28, 2025 .Dt STATS 7 .Os .Sh NAME @@ -102,6 +100,7 @@ Report ZFS I/O statistics .Xr stat 1 , .Xr systat 1 , .Xr intro 7 , +.Xr tuning 7 , .Xr ctlstat 8 , .Xr gstat 8 , .Xr ibstat 8 , diff --git a/share/man/man7/stdint.7 b/share/man/man7/stdint.7 index 2f36953d9a16..70bfac4ba283 100644 --- a/share/man/man7/stdint.7 +++ b/share/man/man7/stdint.7 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd September 15, 2002 .Dt STDINT 7 .Os diff --git a/share/man/man7/sticky.7 b/share/man/man7/sticky.7 index 28fab62ea4c9..7c2ae04e2532 100644 --- a/share/man/man7/sticky.7 +++ b/share/man/man7/sticky.7 @@ -25,9 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)sticky.8 8.1 (Berkeley) 6/5/93 -.\" $FreeBSD$ -.\" .Dd June 5, 1993 .Dt STICKY 7 .Os diff --git a/share/man/man7/tests.7 b/share/man/man7/tests.7 index b253c1ab2458..61b0789b9149 100644 --- a/share/man/man7/tests.7 +++ b/share/man/man7/tests.7 @@ -1,4 +1,3 @@ -.\" $FreeBSD$ .\" $NetBSD: tests.kyua.7,v 1.2 2013/07/20 21:39:59 wiz Exp $ .\" .\" Copyright (c) 2010 The NetBSD Foundation, Inc. @@ -26,7 +25,7 @@ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd August 19, 2020 +.Dd April 1, 2025 .Dt TESTS 7 .Os .Sh NAME @@ -158,7 +157,7 @@ The following configuration variables are available in the .Fx Test Suite: .Bl -tag -width "allow_sysctl_side_effects" -.It allow_devfs_side_effects +.It Va allow_devfs_side_effects If defined, enables tests that may destroy and recreate semipermanent device nodes, like disk devices. Without this variable, tests may still create and destroy devices nodes that @@ -167,16 +166,19 @@ them up afterwards. However, tests that require this variable have a relaxed cleanup requirement; they must recreate any devices that they destroyed, but not necessarily with the same devnames. -.It allow_sysctl_side_effects +.It Va allow_sysctl_side_effects Enables tests that change globally significant .Xr sysctl 8 variables. The tests will undo any changes in their cleanup phases. -.It disks +.It Va allow_network_access +Enables tests that need to access the network the test host is connected to. +Such tests may require properly configured Internet access. +.It Va disks Must be set to a space delimited list of disk device nodes. Tests that need destructive access to disks must use these devices. Tests are not required to preserve any data present on these disks. -.It fibs +.It Va fibs Must be set to a space delimited list of FIBs (routing tables). Tests that need to modify a routing table may use any of these. Tests will cleanup any new routes that they create. diff --git a/share/man/man7/tracing.7 b/share/man/man7/tracing.7 new file mode 100644 index 000000000000..7085bac78385 --- /dev/null +++ b/share/man/man7/tracing.7 @@ -0,0 +1,100 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 12, 2025 +.Dt TRACING 7 +.Os +.Sh NAME +.Nm tracing +.Nd introduction to FreeBSD tracing and performance monitoring +.Sh DESCRIPTION +.Fx +features a large variety of tracing and performance monitoring facilities. +Use them to measure performance and +troubleshoot kernel and userland problems both during +.Xr development 7 +and potentially on production systems. +The facilities differ in scope, ease of use, overhead, design, and limitations. +.Ss DTrace +.Xr dtrace 1 +is the most versatile tracing framework available on +.Fx +and is capable of tracing throughout the +.Fx +software stack from the kernel to the applications running in userland. +Refer to +.Xr dtrace 1 +and +.Xr SDT 9 +for more details. +.Pp +.Xr dwatch 1 +is a user-friendly wrapper for DTrace. +It simplifies common DTrace usage patterns and requires less expert knowledge +to operate. +.Ss Userland Tracing +.Xr truss 1 +traces system calls. +It uses +.Xr sysdecode 3 +to pretty-print system call arguments and +.Xr ptrace 2 +to trace processes. +.Pp +.Xr ktrace 1 +is useful for debugging user programs. +It enables kernel trace logging for specified processes. +Like +.Xr truss 1 , +it mainly traces system calls, but instead of using +.Xr ptrace 2 , +it asynchronously logs entries to a trace file configured with +.Xr ktrace 2 +(typically +.Pa ktrace.out ) , +and it can log other types of kernel events, such as page faults +and name lookups +.Po refer to +.Fl t +in +.Xr ktrace 1 +.Pc . +Also, programs can log to a +.Xr ktrace 1 +stream using the +.Xr utrace 2 +system call. +.Ss Kernel Tracing +.Xr ktr 4 +is a facility for logging strings in the kernel. +It comes in handy for some niche purposes during kernel development. +It lets kernel programmers log events to a global ring buffer, +which can later be dumped using +.Xr ktrdump 8 . +.Ss Hardware-Accelerated Tracing +.Xr hwt 4 +is a kernel trace framework providing infrastructure +for hardware-assisted tracing. +.Ss Hardware Counters +.Xr pmcstat 8 , +and its kernel counterpart, +.Xr hwpmc 4 , +is the +.Fx +facility for conducting performance measurements with hardware counters. +.Ss Boot-Time And Shutdown Tracing +.Xr boottrace 4 +is a facility for tracing events at boot and shutdown. +Its target audience are system administrators. +.Pp +.Xr tslog 4 +is a developer-oriented tool for tracing boot-time events. +.Sh HISTORY +The +.Nm +manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +It first appeared in +.Fx 15.0 . diff --git a/share/man/man7/tuning.7 b/share/man/man7/tuning.7 index 63e09ecce098..44c427c4559d 100644 --- a/share/man/man7/tuning.7 +++ b/share/man/man7/tuning.7 @@ -22,9 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd April 16, 2020 +.Dd October 28, 2025 .Dt TUNING 7 .Os .Sh NAME @@ -153,8 +151,7 @@ Striping can also improve the performance of a file system by splitting I/O operations across two or more disks. The -.Xr gstripe 8 , -.Xr gvinum 8 , +.Xr gstripe 8 and .Xr ccdconfig 8 utilities may be used to create simple striped file systems. @@ -482,7 +479,7 @@ By default is set at the maximum allowable port number. .Pp The -.Va kern.ipc.somaxconn +.Va kern.ipc.soacceptqueue sysctl limits the size of the listen queue for accepting new TCP connections. The default value of 128 is typically too low for robust handling of new connections in a heavily loaded web server environment. @@ -506,29 +503,6 @@ The read-only .Va kern.openfiles sysctl may be interrogated to determine the current number of open files on the system. -.Pp -The -.Va vm.swap_idle_enabled -sysctl is useful in large multi-user systems where you have lots of users -entering and leaving the system and lots of idle processes. -Such systems -tend to generate a great deal of continuous pressure on free memory reserves. -Turning this feature on and adjusting the swapout hysteresis (in idle -seconds) via -.Va vm.swap_idle_threshold1 -and -.Va vm.swap_idle_threshold2 -allows you to depress the priority of pages associated with idle processes -more quickly then the normal pageout algorithm. -This gives a helping hand -to the pageout daemon. -Do not turn this option on unless you need it, -because the tradeoff you are making is to essentially pre-page memory sooner -rather than later, eating more swap and disk bandwidth. -In a small system -this option will have a detrimental effect but in a large system that is -already doing moderate paging this option allows the VM system to stage -whole processes into and out of memory more easily. .Sh LOADER TUNABLES Some aspects of the system behavior may not be tunable at runtime because memory allocations they perform must occur early in the boot process. @@ -697,12 +671,14 @@ over services you export from your box (web services, email). .Xr ata 4 , .Xr dummynet 4 , .Xr eventtimers 4 , +.Xr ffs 4 , .Xr login.conf 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr firewall 7 , .Xr hier 7 , .Xr ports 7 , +.Xr stats 7 , .Xr boot 8 , .Xr bsdinstall 8 , .Xr ccdconfig 8 , @@ -711,7 +687,6 @@ over services you export from your box (web services, email). .Xr gjournal 8 , .Xr gpart 8 , .Xr gstripe 8 , -.Xr gvinum 8 , .Xr ifconfig 8 , .Xr ipfw 8 , .Xr loader 8 , |