From 9dfe484e126d0e477a0d79b3f7a2350af9f5e025 Mon Sep 17 00:00:00 2001 From: Alexander Ziaee Date: Wed, 20 Mar 2024 13:40:57 -0400 Subject: 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// - /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 --- 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// 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/ -- cgit v1.2.3