share/man/man4/linux.4

   1 .\" Copyright (c) 2000 Sheldon Hearn
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd February 8, 2010
  28 .Dt LINUX 4
  29 .Os
  30 .Sh NAME
  31 .Nm linux
  32 .Nd Linux ABI support
  33 .Sh SYNOPSIS
  34 To compile support for this ABI into the kernel,
  35 place the following line in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "options COMPAT_LINUX"
  39 .Ed
  40 .Pp
  41 Alternatively, to load the ABI as a
  42 module at boot time, place the following line in
  43 .Xr loader.conf 5 :
  44 .Bd -literal -offset indent
  45 linux_load="YES"
  46 .Ed
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 module provides limited
  51 Linux ABI (application binary interface) compatibility
  52 for userland applications.
  53 The module provides the following significant facilities:
  54 .Bl -bullet
  55 .It
  56 An image activator
  57 for correctly branded
  58 .Xr elf 5
  59 executable images
  60 .It
  61 Special signal handling for activated images
  62 .It
  63 Linux to native system call translation
  64 .El
  65 .Pp
  66 It is important to note that the Linux ABI support
  67 it not provided through an emulator.
  68 Rather, a true (albeit limited) ABI implementation is provided.
  69 .Pp
  70 The following
  71 .Xr sysctl 8
  72 tunable variables are available:
  73 .Bl -tag -width compat.linux.oss_version
  74 .It compat.linux.osname
  75 Linux kernel operating system name.
  76 .It compat.linux.osrelease
  77 Linux kernel operating system release.
  78 Changing this to something else is discouraged on non-development systems,
  79 because it may change the way Linux programs work.
  80 Recent versions of GNU libc are known to use different syscalls depending
  81 on the value of this sysctl.
  82 .It compat.linux.oss_version
  83 Linux Open Sound System version.
  84 .El
  85 .Pp
  86 The
  87 .Nm
  88 module can be linked into the kernel statically with the
  89 .Dv COMPAT_LINUX
  90 kernel configuration option
  91 or loaded as required.
  92 The following command will load the module
  93 if it is neither linked into the kernel
  94 nor already loaded as a module:
  95 .Bd -literal -offset indent
  96 if ! kldstat -v | grep -E 'linux(aout|elf)' > /dev/null; then
  97         kldload linux > /dev/null 2>&1
  98 fi
  99 .Ed
 100 .Pp
 101 Note that dynamically linked Linux executables
 102 will require a suitable environment in
 103 .Pa /compat/linux .
 104 Specifically, the Linux run-time linker's hints files
 105 should be correctly initialized.
 106 For this reason, it is common to execute the following commands
 107 to prepare the system to correctly run Linux executables:
 108 .Bd -literal -offset indent
 109 if [ -x /compat/linux/sbin/ldconfig ]; then
 110         /compat/linux/sbin/ldconfig -r /compat/linux
 111 fi
 112 .Ed
 113 .Pp
 114 For information on loading the
 115 .Nm
 116 kernel loadable module automatically on system startup,
 117 see
 118 .Xr rc.conf 5 .
 119 This information applies
 120 regardless of whether the
 121 .Nm
 122 module is statically linked into the kernel
 123 or loaded as a module.
 124 .Sh FILES
 125 .Bl -tag -width /compat/linux/proc -compact
 126 .It Pa /compat/linux
 127 minimal Linux run-time environment
 128 .It Pa /compat/linux/proc
 129 limited Linux process file system
 130 .It Pa /compat/linux/sys
 131 limited Linux system file system
 132 .El
 133 .Sh SEE ALSO
 134 .Xr brandelf 1 ,
 135 .Xr elf 5 ,
 136 .Xr linprocfs 5 ,
 137 .Xr linsysfs 5
 138 .Sh HISTORY
 139 Linux ABI support first appeared in
 140 .Fx 2.1 .