Improve Linuxulator man pages to better reflect the current state,

and add some missing Xrs.

Reviewed by:	brueffer, emaste (earlier version)
MFC after:	2 weeks
Sponsored by:	The FreeBSD Foundation
Differential Revision:	https://reviews.freebsd.org/D22277

1 files changed, 48 insertions, 59 deletions

diff --git a/share/man/man4/linux.4 b/share/man/man4/linux.4
index 73f4235c6b02..a5b48fda3f7d 100644
--- a/share/man/man4/linux.4
+++ b/share/man/man4/linux.4
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 1, 2017
+.Dd November 13, 2019
 .Dt LINUX 4
 .Os
 .Sh NAME
@@ -52,10 +52,10 @@ linux_load="YES"
 .Sh DESCRIPTION
 The
 .Nm
-module provides limited
-Linux ABI (application binary interface) compatibility
-for userland applications.
-The module provides the following significant facilities:
+module provides limited Linux ABI (application binary interface) compatibility,
+making it possible to run many unmodified Linux applications and libraries
+without the need for virtualization or emulation.
+Some of the facilities provided are:
 .Bl -bullet
 .It
 An image activator
@@ -66,76 +66,61 @@ executable images
 Special signal handling for activated images
 .It
 Linux to native system call translation
+.It
+Linux-specific system calls
 .El
 .Pp
-It is important to note that the Linux ABI support
-it not provided through an emulator.
-Rather, a true (albeit limited) ABI implementation is provided.
+Note that dynamically linked Linux executables
+will require a suitable environment in
+.Pa /compat/linux .
+This includes native Linux shared libraries, and Linux-specific virtual
+filesystems.
+To set it up, install the
+.Pa emulators/linux_base-c7
+port or the linux_base-c7
+package, and add the following line to the
+.Xr rc.conf 5
+file:
+.Pp
+.Dl linux_enable="YES"
+.Pp
+To avoid mounting Linux-specific filesystems at startup, also add the following
+line:
 .Pp
-The following
+.Dl linux_mounts_enable="NO"
+.Sh SYSCTL VARIABLES
+The following variables are available as both
 .Xr sysctl 8
-tunable variables are available:
-.Bl -tag -width compat.linux.oss_version
-.It compat.linux.osname
+variables and
+.Xr loader 8
+tunables:
+.Bl -tag -width indent
+.It Va compat.linux.osname
 Linux kernel operating system name.
-.It compat.linux.osrelease
+.It Va compat.linux.osrelease
 Linux kernel operating system release.
 Changing this to something else is discouraged on non-development systems,
 because it may change the way Linux programs work.
 Recent versions of GNU libc are known to use different syscalls depending
 on the value of this sysctl.
-.It compat.linux.oss_version
+.It Va compat.linux.oss_version
 Linux Open Sound System version.
-.El
-.Pp
-The
-.Nm
-module can be linked into the kernel statically with the
-.Dv COMPAT_LINUX
-kernel configuration option
-or loaded as required.
-The following command will load the module
-if it is neither linked into the kernel
-nor already loaded as a module:
-.Bd -literal -offset indent
-if ! kldstat -v | grep -E 'linux(aout|elf)' > /dev/null; then
-	kldload linux > /dev/null 2>&1
-fi
-.Ed
-.Pp
-Note that dynamically linked Linux executables
-will require a suitable environment in
-.Pa /compat/linux .
-Specifically, the Linux run-time linker's hints files
-should be correctly initialized.
-For this reason, it is common to execute the following commands
-to prepare the system to correctly run Linux executables:
-.Bd -literal -offset indent
-if [ -x /compat/linux/sbin/ldconfig ]; then
-	/compat/linux/sbin/ldconfig -r /compat/linux
-fi
-.Ed
-.Pp
-For information on loading the
-.Nm
-kernel loadable module automatically on system startup,
-see
-.Xr rc.conf 5 .
-This information applies
-regardless of whether the
-.Nm
-module is statically linked into the kernel
-or loaded as a module.
 .Sh FILES
-.Bl -tag -width /compat/linux/dev/fd -compact
+.Bl -tag -width /compat/linux/dev/shm -compact
 .It Pa /compat/linux
 minimal Linux run-time environment
 .It Pa /compat/linux/dev/fd
-limited Linux file-descriptor file system
+file-descriptor file system, see
+.Xr fdescfs 5
+.It Pa /compat/linux/dev/shm
+in-memory file system, see
+.Xr tmpfs 5
 .It Pa /compat/linux/proc
-limited Linux process file system
+Linux process file system, see
+.Xr linprocfs 5
 .It Pa /compat/linux/sys
-limited Linux system file system
+Linux kernel objects file system, see
+.Xr linsysfs 5
 .El
 .Sh SEE ALSO
 .Xr brandelf 1 ,
@@ -143,7 +128,11 @@ limited Linux system file system
 .Xr elf 5 ,
 .Xr fdescfs 5 ,
 .Xr linprocfs 5 ,
-.Xr linsysfs 5
+.Xr linsysfs 5 ,
+.Xr tmpfs 5
 .Sh HISTORY
 Linux ABI support first appeared in
 .Fx 2.1 .
+.Sh BUGS
+Support for some of the Linux-specific system calls and system call arguments
+is missing.