The branch stable/14 has been updated by mhorne:
URL:
https://cgit.FreeBSD.org/src/commit/?id=63b747823bead05837f6893a2f2d38b516bc1e49
commit 63b747823bead05837f6893a2f2d38b516bc1e49
Author: Alexander Ziaee <concussi...@runbox.com>
AuthorDate: 2024-03-20 17:40:57 +0000
Commit: Mitchell Horne <mho...@freebsd.org>
CommitDate: 2024-05-01 18:43:20 +0000
hier.7: polish entry to system manual
Entries reworded to improve grammar or add keywords:
- document description: substitute layout for index for first-glance
- /etc/freebsd/update.conf
- /usr/share/vi/
Entries that have been wordshuffled for brevity or consistency:
- /{bin,libexec,nonexistent,sbin,tmp}/
- /boot/dtb/overlays/
- /boot/{defaults,efi,kernel,lua}/
- /usr/libexec/
- /var/{db,games,lib,log/{bsdisks.log,spool/,tmp/}}
- /usr/share/sysroot/VERSION/MACHINE.MACHINE_ARCH/ (unfold a little)
- /usr/local/share/doc/freebsd/ (unfold a little)
Entries that have macro or linking adjustments:
- /{boot,boot/efi,dev,etc,home,sbin,usr/bin}/ (overview or intro pages)
- /media/ (bsdisks is from ports, but afaik pulled by every desktop)
- /usr/share/{lib/,lib/dtrace/,libdata/games/,man/}/ (intro pages)
- /var/log/messages (syslog(3) -> syslogd(8))
Entries that have been added:
- /dev/{cuaU0,vmm,zvol}/
- /usr/share/{atf,bhyve}/
- /usr/share/libexec/hyperv/ (thanks @rtprio)
- /local/<subdirectories>/
- /var/log/debug.log (thanks @pauamma)
- /var/spool/{lock,lpd}
Please forgive my earlier mistakes fixed in this commit:
- /{dev,/usr/share/{calendar,misc}} : accidentally reverted description
- /etc/local-unbound.conf/ (wrong link)
- /usr/{freebsd-dist,lib32,libdata},/var/log/{dmesg.today,lpd-errs} (typos)
- /{usr/libdata/gcc/,var/log/bsdisks.log} (removed, unnecessary)
PR: 261349
Reviewed by: mhorne
MFC after: 1 week
Pull Request: https://github.com/freebsd/freebsd-src/pull/1131
(cherry picked from commit 9dfe484e126d0e477a0d79b3f7a2350af9f5e025)
---
share/man/man7/hier.7 | 207 ++++++++++++++++++++++++++++++--------------------
1 file changed, 123 insertions(+), 84 deletions(-)
diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7
index 8cd6ff338b5c..7d164b5683d6 100644
--- a/share/man/man7/hier.7
+++ b/share/man/man7/hier.7
@@ -28,12 +28,12 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd March 21, 2024
+.Dd April 18, 2024
.Dt HIER 7
.Os
.Sh NAME
.Nm hier
-.Nd layout of
+.Nd index of
.Fx
file system hierarchy
.Sh DESCRIPTION
@@ -44,15 +44,18 @@ root directory of the file system
.Fx
copyright information
.It Pa /bin/
-user utilities fundamental to both single and multi-user modes
+fundamental
+.Bx
+user utilities; see
+.Xr intro 1
.It Pa /boot/
programs and configurations used during
.Fx
-bootstrap
+.Xr boot 8
.Pp
.Bl -tag -width "loader.conf.d/" -compact
.It Pa defaults/
-default bootstrap configuration files; see
+default boot configuration files; see
.Xr loader.conf 5
.It Pa device.hints
kernel variables for controlling drivers; see
@@ -65,14 +68,18 @@ and
.Pp
.Bl -tag -width "overlays/" -compact
.It Pa overlays/
-compiled flattened device tree (FDT) overlays; these can be applied using the
+compiled
+.Xr fdt 4
+overlays; see
.Va fdt_overlays
-setting in
+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 binary firmware kernel modules
.It Pa fonts/
@@ -84,9 +91,8 @@ and
beastie boot menu images; see
.Xr loader_lua 8
.It Pa kernel/
-pure kernel executable
-.Pq the operating system loaded into memory at boot time
-and kernel modules; see
+.Fx
+kernel and modules; see
.Xr kldstat 8
.It Pa kernel.old/
alternative kernel and modules
@@ -97,7 +103,7 @@ boot loader configuration; see
.Xr loader.conf 5
configuration files
.It Pa lua/
-scripts for kernel bootstrapping final stage; see
+scripts for the Lua boot loader; see
.Xr loader_lua 8
.It Pa modules/
third-party loadable kernel modules, such as those installed with
@@ -119,7 +125,9 @@ default location for
compatibility run-time
.El
.It Pa /dev/
-device special files managed by
+device nodes and special files; see
+.Xr intro 4
+and
.Xr devfs 5
.Pp
.Bl -tag -width "loader.conf.d" -compact
@@ -129,12 +137,15 @@ first ATA storage device
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 node; see
+GPU character device nodes; see
.Xr drm 7
.It Pa drm/
GPU
@@ -157,7 +168,8 @@ infinite loop that accepts anything and contains nothing
.It Pa nvd0
first NVMe storage device using NVMe namespaces
.It Pa pts/
-pseduo-terminals
+pseduo-terminals; see
+.Xr pts 4
.It Pa random
source of weak randomness; see
.Xr random 4
@@ -165,12 +177,20 @@ source of weak randomness; see
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 wide configuration files and scripts
+base system configuration files and scripts; see
+.Xr intro 5
.Pp
.Bl -tag -width "freebsd-update.conf" -compact
.It Pa auto_master
@@ -197,7 +217,7 @@ boot time device configuration
configuration for
.Xr dma 8
.It Pa freebsd-update.conf
-configuration for the base system updater
+configuration for the base system updater; see
.Xr freebsd-update 8
.It Pa fstab
static filesystem configuration; see
@@ -214,7 +234,7 @@ local timezone information; see
.Xr ctime 3
.It Pa jail.conf.d/
.Xr jail 8
-startup scripts.
+startup scripts
.It Pa login.conf
login class capability database; see
.Xr login.conf 5
@@ -275,7 +295,7 @@ DNS configuration; see
.It Pa resolvconf.conf
DNS configuration manager configuration, often generated by
local-unbound; see
-.Xr local_unbound 8
+.Xr local-unbound 8
or
.Xr resolvconf 8
.It Pa security/
@@ -300,11 +320,11 @@ client wifi configuration; see
.El
.It Pa /home/
home directories for users; the typical home for an interactive user
-.Dv beastie
+.Va beastie
would be
.Pa /home/beastie/
.It Pa /lib/
-system libraries that are critical to binaries in
+system libraries critical to binaries in
.Pa /bin
and
.Pa /sbin
@@ -320,16 +340,18 @@ vendor-specific libraries to extend the
utility
.El
.It Pa /libexec/
-system utilities that are critical to binaries in
+system utilities critical to binaries in
.Pa /bin
and
.Pa /sbin
.It Pa /media/
mount points for removable storage media such as CDs, DVDs,
and USB drives; see
-.Xr automount 8
+.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
@@ -338,8 +360,7 @@ 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
+by convention, it serves as a home directory for user accounts
that need no home directory; see also
.Pa /var/empty/
.It Pa /proc/
@@ -351,33 +372,37 @@ statically linked programs for emergency recovery; see
.It Pa /root/
home directory of the root user
.It Pa /sbin/
-system programs and administration utilities
-fundamental to both single and multi-user modes
+fundamental
+.Bx
+system administration utilities; see
+.Xr intro 8
.It Pa /tmp/
-temporary files that may be removed by
-.Xr rc 8 ;
-see the
+temporary files commonly removed between system reboots;
+see
.Va clear_tmp_enable
-variable of
+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
+common utilities, programming tools, and applications; see
+.Xr intro 1
.It Pa freebsd-dist/
distribution files
-.Pq like base.txz ; see
+.Pq like base.txz ;
+see
.Xr release 7
and
.Xr bsdinstall 8
.It Pa include/
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/
@@ -388,7 +413,8 @@ 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
.Pq Cryptography/SSL toolkit
@@ -401,7 +427,7 @@ shared libraries for internationalization
.El
.Pp
.It Pa lib32/
-32-bit comparability libraries
+32-bit compatibility libraries
.It Pa libdata/
miscellaneous utility data files
.Pp
@@ -414,8 +440,9 @@ collections of compiler and linker flags for the
.Xr pkgconf 1
development tool
.El
+.Pp
.It Pa libexec/
-system daemons and utilities that are executed by other programs
+system daemons and utilities executed by programs
.Pp
.Bl -tag -width "bsdinstall/" -compact
.It Pa bsdconfig/
@@ -432,7 +459,7 @@ profiles for
utilities called by
.Xr fwget 8
.It Pa hyperv/
-???
+scripts for communicating with the Hyper-V hypervisor
.It Pa lpr/
utilities and filters for the line printer system; see
.Xr lpr 1
@@ -451,26 +478,36 @@ Z file system utilities
.El
.Pp
.It Pa local/
-default destination for local executables, libraries, etc, installed by
+local executables, libraries, etc, installed by
.Xr pkg 7
or
.Xr ports 7
.Pp
-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 man/
+local manual pages; see
+.Xr man 1
+.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
@@ -487,13 +524,20 @@ from source; see
ports collection; see
.Xr ports 7
.It Pa sbin/
-system daemons and utilities meant for user execution
+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
@@ -522,7 +566,8 @@ firmware images loaded by userland programs
.It Pa games/
ASCII text files used by
.Bx
-heritage games
+heritage games, see
+.Xr intro 6
.It Pa keys/
known trusted and revoked keys
.Pp
@@ -538,9 +583,10 @@ and
localization files; see
.Xr setlocale 3
.It Pa man/
-system 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 ascii
@@ -606,7 +652,7 @@ console screen maps
files necessary for the -sysroot compiler/linker argument to build non-native
binaries
.Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width "VERSION/" -compact
.It Pa VERSION/
files for
.Fx
@@ -616,9 +662,7 @@ by convention,
matches
.Xr uname 1
.Fl r
-.Pp
-.Bl -tag -width Fl -compact
-.It Pa MACHINE.MACHINE_ARCH/
+.It Pa VERSION/MACHINE.MACHINE_ARCH/
represent the binary ABI for these files;
.Dq MACHINE
matches
@@ -629,15 +673,15 @@ matches
.Xr uname 1
.Fl p
.El
-.El
.Pp
.It Pa tabset/
tab description files for a variety of terminals; used in
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 the system console; see
.Xr vt 4
@@ -735,7 +779,7 @@ crontab files; see
.El
.Pp
.It Pa db/
-miscellaneous automatically-generated system-specific database files
+autogenerated system-specific database files
.Pp
.Bl -tag -width "freebsd-update/" -compact
.It Pa etcupdate/
@@ -754,14 +798,14 @@ used for instance by
.Xr sshd 8
for privilege separation
.It Pa games/
-miscellaneous game status and score files for
+status and score files for
.Bx
heritage games
.It Pa heimdal/
Kerberos server databases; see
.Xr kdc 8
.It Pa lib/
-holds state information for applications ported from linux
+state information for ported Linux applications
.It Pa log/
system log files
.Pp
@@ -770,8 +814,7 @@ system log files
.Xr Xserver 1
log, if
.Xr X 7
-is installed
-rotates to
+is installed rotates to
.Pa Xorg.0.log.old
.It Pa aculog
serial line access log; see
@@ -780,11 +823,6 @@ serial line access log; see
system authentication log
.It Pa bsdinstall_log
system installation log
-.It Pa bsdisks.log
-FreeDesktop.org automounter log, if a desktop environment is using
-.Xr bsdisks 8 ,
-from
-.Xr ports 7
.It Pa cron
scheduled task log; see
.Xr cron 8
@@ -796,20 +834,19 @@ 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
+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 daemon; see
+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 syslog 3
+.Xr syslogd 8
.It Pa mount.today
currently loaded
.Xr fstab 5 ,
@@ -879,7 +916,7 @@ information about other systems on the local network; see
and
.Xr ruptime 1
.It Pa spool/
-miscellaneous printer and mail system spooling directories
+printer and mail system spooling directories
.Pp
.Bl -tag -width "clientmqueue/" -compact
.It Pa clientmqueue/
@@ -894,7 +931,10 @@ undelivered mail queue for
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 ftp/
ftp root directory; see
.Xr ftpd 8
@@ -906,8 +946,7 @@ line printer spooling directories
.El
.Pp
.It Pa tmp/
-temporary files that are not removed between system reboots by
-.Xr rc 8
+temporary files not removed between system reboots
.Pp
.Bl -tag -width "vi.recover/" -compact
.It Pa vi.recover/
