share/man/man4/aout.4

   1 .\" Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org>
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  13 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  14 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  15 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  16 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  17 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  18 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  19 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  20 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  21 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  22 .\"
  23 .\" $FreeBSD$
  24 .\"
  25 .Dd August 14, 2012
  26 .Dt AOUT 4
  27 .Os
  28 .Sh NAME
  29 .Nm aout
  30 .Nd kernel support for executing binary files in legacy a.out format
  31 .Sh SYNOPSIS
  32 .Bd -literal -offset indent
  33 kldload a.out
  34 .Ed
  35 .Sh DESCRIPTION
  36 The
  37 .Xr a.out 5
  38 executable format was used before the release of
  39 .Fx 3.0 .
  40 Since i386 was the only supported architecture at that time,
  41 .Xr a.out 5
  42 executables can only be activated on platforms that support
  43 execution of i386 code, such as i386, amd64 and (partially) ia64.
  44 .Pp
  45 To add kernel support for old syscalls and old syscall invocation methods,
  46 place the following options in the kernel configuration file:
  47 .Bd -ragged -offset indent
  48 .Cd "options COMPAT_43"
  49 .br
  50 .Cd "options COMPAT_FREEBSD32"
  51 .Ed
  52 .Pp
  53 The
  54 .Va COMPAT_FREEBSD32
  55 option is only required on 64-bit CPU architectures.
  56 .Pp
  57 The
  58 .Va aout.ko
  59 module needs to be loaded with the
  60 .Xr kldload 8
  61 utility in order to support the
  62 .Xr a.out 5
  63 image activator:
  64 .Bd -ragged -offset indent
  65 .Ic kldload aout
  66 .Ed
  67 .Pp
  68 Alternatively, to load the module at boot time, place the following line in
  69 .Xr loader.conf 5 :
  70 .Bd -literal -offset indent
  71 aout_load="YES"
  72 .Ed
  73 .Pp
  74 The
  75 .Xr a.out 5
  76 format was mainstream quite a long time ago.
  77 Reasonable default settings and security requirements of
  78 modern operating systems today contradict the default environment of that time
  79 and require adjustments of the system to mimic natural environment for
  80 old binaries.
  81 .Pp
  82 The following
  83 .Xr sysctl 8
  84 tunables are useful for this:
  85 .Bl -tag -offset indent -width "XXXXXXXXXXXXXXXXXXXXXXXXX"
  86 .It Xo Va security.bsd.map_at_zero
  87 .Xc
  88 Set to 1 to allow mapping of process pages at address 0.
  89 Some very old
  90 .Va ZMAGIC
  91 executable images require text mapping at address 0.
  92 .It Xo Va kern.pid_max
  93 .Xc
  94 Old versions of
  95 .Fx
  96 used signed 16-bit type for
  97 .Vt pid_t .
  98 Current kernels use 32-bit type for
  99 .Vt pid_t ,
 100 and allow process id's up to 99999.
 101 Such values cannot be represented by old
 102 .Vt pid_t ,
 103 mostly causing issues for processes using
 104 .Xr wait 2
 105 syscalls, for example shells.
 106 Set the sysctl to 30000 to work around the problem.
 107 .It Xo Va kern.elf32.read_exec
 108 .Xc
 109 Set to 1 to force any accessible memory mapping performed by 32-bit
 110 process to allow execution, see
 111 .Xr mmap 2 .
 112 Old i386 CPUs did not have a bit in PTE which disallowed execution
 113 from the page, so many old programs did not specify
 114 .Va PROT_EXEC
 115 even for mapping of executable code.
 116 The sysctl forces
 117 .Va PROT_EXEC
 118 if mapping has any access allowed at all.
 119 The setting is only needed if the host architecture allows
 120 non-executable mappings.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr execve 2 ,
 124 .Xr a.out 5 ,
 125 .Xr elf 5 ,
 126 .Xr sysctl 8 .
 127 .Sh HISTORY
 128 The
 129 .Xr a.out 5
 130 executable format was used on ancient
 131 .At
 132 and served as the main executable format for
 133 .Fx
 134 from the beginning up to
 135 .Fx 2.2.9 .
 136 In
 137 .Fx 3.0
 138 it was superseded by
 139 .Xr elf 5 .
 140 .Sh AUTHORS
 141 The
 142 .Nm
 143 manual page was written by
 144 .An Konstantin Belousov Aq kib@FreeBSD.org .
 145 .Sh BUGS
 146 On 64bit architectures, not all wrappers for older syscalls are implemented.