From f54d9519862f59dede0f289383cc367a7823388e Mon Sep 17 00:00:00 2001 From: Edward Tomasz Napierala Date: Wed, 13 Nov 2019 20:32:23 +0000 Subject: [PATCH] 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 --- share/man/man4/linux.4 | 107 +++++++++++++++++-------------------- share/man/man5/linprocfs.5 | 3 +- share/man/man5/linsysfs.5 | 5 +- 3 files changed, 53 insertions(+), 62 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 -The following +.Dl linux_enable="YES" +.Pp +To avoid mounting Linux-specific filesystems at startup, also add the following +line: +.Pp +.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. diff --git a/share/man/man5/linprocfs.5 b/share/man/man5/linprocfs.5 index a85afe96fd31..23578c058af9 100644 --- a/share/man/man5/linprocfs.5 +++ b/share/man/man5/linprocfs.5 @@ -2,7 +2,7 @@ .\" Written by Garrett Wollman .\" This file is in the public domain. .\" -.Dd August 10, 1994 +.Dd November 13, 2019 .Dt LINPROCFS 5 .Os .Sh NAME @@ -75,6 +75,7 @@ file system on .Sh SEE ALSO .Xr mount 2 , .Xr unmount 2 , +.Xr linux 4 , .Xr procfs 5 , .Xr pseudofs 9 .Sh HISTORY diff --git a/share/man/man5/linsysfs.5 b/share/man/man5/linsysfs.5 index f3ea3cff08ed..99cf3fe2fe41 100644 --- a/share/man/man5/linsysfs.5 +++ b/share/man/man5/linsysfs.5 @@ -3,12 +3,12 @@ .\" .\" $FreeBSD$ .\" -.Dd February 5, 2007 +.Dd November 13, 2019 .Dt LINSYSFS 5 .Os .Sh NAME .Nm linsysfs -.Nd Linux system file system +.Nd Linux kernel objects file system .Sh SYNOPSIS .Bd -literal linsys /compat/linux/sys linsysfs rw 0 0 @@ -76,6 +76,7 @@ is a mount point. .Sh SEE ALSO .Xr nmount 2 , .Xr unmount 2 , +.Xr linux 4 , .Xr linprocfs 5 , .Xr pseudofs 9 .Sh HISTORY