git: 6469f9c595c6 - main - hier(7): improvement, modernisation
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 10 Jun 2023 08:46:28 UTC
The branch main has been updated by grahamperrin:
URL: https://cgit.FreeBSD.org/src/commit/?id=6469f9c595c609dd552ec198a16c471c87df7c57
commit 6469f9c595c609dd552ec198a16c471c87df7c57
Author: Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-06-10 08:41:35 +0000
Commit: Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-06-10 08:41:35 +0000
hier(7): improvement, modernisation
Consistent use of lowercase, spacing between sections, etc.
Cease mentioning floppy disks.
De-list /usr/share/misc/fonts/, which has been ??? (without a
description) for twenty-seven years.
Change zpool to pool. (zpool is a command.)
Uppercase PPP for Point-to-Point Protocol.
A few other changes to wording, including avoidance of the phrase
pre-fab.
Update the descriptions of:
* /tmp/
* /usr/share/misc/
* /var/preserve/
* /var/tmp/
* /var/tmp/vi.recover/.
Refer to vi(1) instead of ex(1).
https://bugs.freebsd.org/261349
PR: 261349
Reviewed by: mhorne
Approved by: mhorne
Pull request: https://github.com/freebsd/freebsd-src/pull/763
---
share/man/man7/hier.7 | 301 ++++++++++++++++++++++----------------------------
1 file changed, 135 insertions(+), 166 deletions(-)
diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7
index 18b72fa03ecb..39159e51b7b8 100644
--- a/share/man/man7/hier.7
+++ b/share/man/man7/hier.7
@@ -28,51 +28,51 @@
.\" @(#)hier.7 8.1 (Berkeley) 6/5/93
.\" $FreeBSD$
.\"
-.Dd May 30, 2023
+.Dd June 10, 2023
.Dt HIER 7
.Os
.Sh NAME
.Nm hier
.Nd layout of file systems
.Sh SYNOPSIS
-A sketch of the file system hierarchy.
+An overview of the file system hierarchy.
.Sh DESCRIPTION
.Bl -tag -width "/libexec/"
.It Pa /
-root directory of the file system
+root directory
.It Pa /bin/
-user utilities fundamental to both single-user and multi-user environments
+user utilities that are fundamental to single-user and multi-user modes
.It Pa /boot/
-programs and configuration files used during operating system bootstrap
+programs and configuration files used during bootstrap of the operating system
.Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
.It Pa defaults/
-default bootstrapping configuration files; see
+default bootstrap configuration files; see
.Xr loader.conf 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
.It Pa efi/
-Mount point for EFI System Partition (ESP) on UEFI systems
+mount point for the EFI System Partition (ESP) on UEFI systems
.It Pa firmware/
-loadable kernel modules containing binary firmware for hardware that needs
-firmware downloaded to it to function
+loadable kernel modules containing binary firmware, for hardware to which
+firmware must be downloaded
.It Pa kernel/
-pure kernel executable (the operating system loaded into memory
-at boot time) and kernel modules
+pure kernel executable (the operating system loaded into memory at boot time)
+and kernel modules
.It Pa modules/
-third-party loadable kernel modules, such as the ones installed from
+third-party loadable kernel modules, such as those associated with
.Xr ports 7
.It Pa overlays/
-Compiled flattened device tree (FDT) overlays; see
+compiled flattened device tree (FDT) overlays; see
.Xr fdt 4
and
.Xr dtc 1
.It Pa zfs/
.Xr zfs 8
-zpool cache files
+pool cache files
.El
.It Pa /compat/
normally a link to
@@ -81,75 +81,67 @@ If not, then the
.Pa /usr/compat
comments apply
.It Pa /dev/
-device special files managed by
+the normal mount point for
.Xr devfs 5
.Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
.It Pa fd/
-file descriptor files;
-see
+file descriptor files; see
.Xr fd 4
.El
.It Pa /etc/
system configuration files and scripts
.Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
.It Pa bluetooth/
bluetooth configuration files
.It Pa defaults/
-default system configuration files;
-see
+default system configuration files; see
.Xr rc 8
.It Pa localtime
-local timezone information;
-see
+local timezone information; see
.Xr ctime 3
.It Pa mail/
-Sendmail control files
+.Xr sendmail 8
+control files
.It Pa mtree/
-mtree configuration files;
-see
.Xr mtree 8
+configuration files
.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 ppp/
-ppp configuration files;
-see
+PPP configuration files; see
.Xr ppp 8
.It Pa rc.d/
-system and daemon startup/control scripts;
-see
+system and daemon startup/control scripts; see
.Xr rc 8
.It Pa security/
-OpenBSM audit configuration files;
-see
+OpenBSM audit configuration files; see
.Xr audit 8
.It Pa ssh/
-OpenSSH configuration files;
-see
+OpenSSH configuration files; see
.Xr ssh 1
.It Pa ssl/
OpenSSL configuration files
.El
.It Pa /home/
-users' HOME directories;
-the layout is not standardized, but a typical interactive user
+users' home directories; whilst the layout is not standardized, the typical home for an interactive user
.Dv beastie
-might receive their own directory
-.Pa /home/beastie
+would be
+.Pa /home/beastie/
.It Pa /lib/
-critical system libraries needed for binaries in
+system libraries that are critial to binaries in
.Pa /bin
and
.Pa /sbin
.Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
.It Pa casper/
service-specific
.Xr libcasper 3
@@ -164,43 +156,41 @@ vendor-specific libraries to extend the
utility
.El
.It Pa /libexec/
-critical system utilities needed for binaries in
+system utilities that are critial 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
+contains subdirectories that are mount points for removable media such as
+USB drives, CDs and DVDs
.It Pa /mnt/
-empty directory commonly used by
-system administrators as a temporary mount point
+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
+a non-existent directory; conventionally, a home directory for special user
+accounts that do not require a home directory. See also
.Pa /var/empty/
.It Pa /proc/
-process file system;
-see
+process file system; see
.Xr procfs 5
.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
+system programs and administration utilities that are fundamental to
+single-user and multi-user modes
.It Pa /tmp/
-temporary files that are not guaranteed to persist across system reboots
+temporary files that may be removed by
+.Xr rc 8 ;
+see the
+.It Va clear_tmp_enable
+variable of
+.Xr rc.conf 5
.It Pa /usr/
contains the majority of user utilities and applications
.Pp
@@ -208,19 +198,16 @@ contains the majority of user utilities and applications
.It Pa bin/
common utilities, programming tools, and applications
.It Pa compat/
-files needed to support binary compatibility with other operating systems;
-see
+files needed to support binary compatibility with other operating systems; see
.Xr linux 4
.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 files
-.Pp
.It Pa lib/
shared and archive
.Xr ar 1 Ns -type
@@ -244,17 +231,16 @@ miscellaneous utility data files
.It Pa gcc/
GCC configuration data
.It Pa ldscripts/
-linker scripts;
-see
+linker scripts; see
.Xr ld 1
.It Pa pkgconfig/
.Xr pc 5 Pq Pa ports/devel/pkgconf
-files: collections of compiler flags, linker flags, and other
-information relevant to library use
+files; collections of compiler flags, linker flags, and other information
+relevant to library use
.El
.Pp
.It Pa libexec/
-system daemons & system utilities (executed by other programs)
+system daemons and system utilities that are executed by other programs
.Pp
.Bl -tag -width Fl -compact
.It Pa aout/
@@ -262,14 +248,12 @@ utilities to manipulate a.out executables
.It Pa elf/
utilities to manipulate ELF executables
.It Pa lpr/
-utilities and filters for LP print system;
-see
+utilities and filters for LP print 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
@@ -290,8 +274,7 @@ the general layout sketched out by
for
.Pa /usr
should be used.
-Exceptions are the
-ports documentation
+Exceptions are the ports documentation
.Po in
.Pa share/doc/<port>/ Ns Pc ,
and
@@ -301,27 +284,25 @@ and
.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 system utilities that are executed by users
.It Pa share/
architecture-independent files
.Pp
.Bl -tag -width Fl -compact
.It Pa calendar/
-a variety of pre-fab calendar files;
-see
+system-wide calendar files; see
.Xr calendar 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
@@ -329,6 +310,7 @@ terms, proper names, and jargon
.It Pa web2
words from Webster's Second International
.El
+.Pp
.It Pa doc/
miscellaneous documentation
.It Pa examples/
@@ -336,9 +318,10 @@ 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
+used by various games
.It Pa keys/
known trusted and revoked keys
+.Pp
.Bl -tag -width Fl -compact
.It Pa pkg/
fingerprints for
@@ -346,25 +329,23 @@ 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
.It Pa misc/
-miscellaneous system-wide ASCII text files
+miscellaneous system-wide files
+.Pp
.Bl -tag -width Fl -compact
-.It Pa fonts/
-???
.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
@@ -380,6 +361,7 @@ 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
@@ -387,29 +369,30 @@ tree definition files for use with
.It Pa mibs/
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.
+binaries
+.Pp
.Bl -tag -width Fl -compact
.It Pa VERSION/
files for
@@ -420,6 +403,7 @@ By convention,
matches
.Xr uname 1
.Fl r .
+.Pp
.Bl -tag -width Fl -compact
.It Pa MACHINE.MACHINE_ARCH/
represent the binary ABI for these files.
@@ -433,37 +417,35 @@ matches
.Fl p .
.El
.El
+.Pp
.It Pa tabset/
-tab description files for a variety of terminals; used in
-the termcap file;
+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
.Xr vi 1
.It Pa vt/
-files used by vt;
-see
.Xr vt 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 zoneinfo/
-timezone configuration information;
-see
+timezone configuration information; see
.Xr tzfile 5
.El
.Pp
@@ -476,41 +458,39 @@ The layout of the source tree is described by the top-level
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
.It Pa acct
-execution accounting file;
-see
+execution accounting file; see
.Xr acct 5
.El
.Pp
.It Pa at/
-timed command scheduling files;
-see
+timed command scheduling files; see
.Xr at 1
.Pp
.Bl -tag -width Fl -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 backups/
miscellaneous backup files
.It Pa cache/
-miscellaneous cached files
+miscellaneous cache files
.Pp
.Bl -tag -width Fl -compact
.It Pa pkg/
@@ -519,34 +499,33 @@ cached packages for
.El
.Pp
.It Pa crash/
-default directory to store kernel crash dumps; see
+default directory for kernel crash dumps; see
.Xr crash 8
and
.Xr savecore 8
.It Pa cron/
-files used by cron;
-see
.Xr cron 8
+files
.Pp
.Bl -tag -width Fl -compact
.It Pa tabs/
-crontab files;
-see
.Xr crontab 5
+files
.El
.Pp
.It Pa db/
-miscellaneous automatically generated system-specific database files
-.Bl -tag -width Fl -compact
+miscellaneous automatically-generated system-specific database files
+.Pp
+.Bl -tag -width "freebsd-update/" -compact
.It Pa freebsd-update/
+temporary files and downloads for
.Xr freebsd-update 8
-work directory for temporary files and downloaded updates
.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.
+Uses include privilege separation by
.Xr sshd 8
-for privilege separation
.It Pa games/
miscellaneous game status and score files
.It Pa heimdal/
@@ -555,33 +534,26 @@ Kerberos server databases; see
.It Pa log/
miscellaneous system log files
.Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width "utx.lastlogin" -compact
.It Pa utx.lastlogin
-last login log;
-see
+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
.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
.It Pa bhyve/
@@ -594,14 +566,12 @@ 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
.El
.Pp
.It Pa rwho/
-rwho data files;
-see
+rwho data files; see
.Xr rwhod 8 ,
.Xr rwho 1 ,
and
@@ -609,29 +579,28 @@ and
.It Pa spool/
miscellaneous 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
+ftp root directory; see
.Xr ftpd 8
.It Pa mqueue/
-undelivered mail queue;
-see
+undelivered mail queue; see
.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 that are not removed by
+.Xr rc 8
.Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width "vi.recover/" -compact
.It Pa vi.recover/
-the directory where recovery files are stored
+.Xr vi 1
+recovery files
.El
.Pp
.It Pa yp/
@@ -642,8 +611,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.