IBCS2(5) BSD Programmer's Manual IBCS2(5)NAME
ibcs2, coff, sco - Intel386 Family Binary Compatibility Specification 2
SYNOPSIS
options COFF
DESCRIPTION
BSD/OS offers limited support for executable binary files that conform to
iBCS2 with some extensions; SCO System V Release 3.2 binaries are the
canonical example. To enable this binary compatibility, the current ker-
nel must be configured with the COFF option.
When you execute an iBCS2 COFF binary file, the kernel loads it with an-
other image called the emulator library. The kernel passes control to the
emulator, which then performs some initializations and jumps to the entry
point in the executable file. The most important initialization is to
change the local descriptor table (LDT) to replace segment 0, the system
call segment. Subsequently when the program executes a system call, the
hardware pushes a return address on the stack and calls the emulator.
The emulator switches stacks and performs initializations, then dispatch-
es the call through a system call switch. Automatically generated stub
routines then convert from iBCS2 data formats and parameters to BSD for-
mats and parameters, and call the appropriate support routine or BSD sys-
tem call. BSD system calls are always available using an LDT segment
specifically reserved for them.
Since the BSD kernel does not implement the iBCS2 interface directly, the
emulator maintains its own state in some situations. For example, the
emulator notices when the program opens a directory rather than a regular
file, and when the program reads directory entries from the file, the em-
ulator simulates the reads using getdirentries(3). The emulator also
treats terminal and socket special files specially. The emulator main-
tains quite a bit of state about signals, so that it can reproduce the
old signal semantics ``reliably''. Signals are always handled on the
program stack. If a signal arrives while the emulator is executing, the
emulator either backs out of its current state, executes the signal han-
dler and then re-executes the system call, or it continues executing with
signals blocked until the system call is serviced, then builds signal
frames on the stack and executes handlers. The precise action depends on
emulator and kernel state.
The emulator contains a filename substitution facility. When the program
first opens a file, the emulator reads in a list of filename translations
from /sco/filemap. Comments (from `#' to the end of the line) are ig-
nored, as are blank lines. Each content line should contain a path pre-
fix and a substitution string, separated by white space. Filenames that
match the prefix are modified inside the emulator such that the prefix is
replaced with the substitution string. The emulator only recognizes com-
plete matches against pathname elements, and only substitutes absolute
pathname prefixes. No regular expression or globbing characters are sup-
ported.
Since a COFF program can exec a BSD elf(5) program, the emulator is load-
ed into BSD programs that are exec'ed by COFF programs so that the emula-
tor will also translate filenames for BSD programs, making them appear to
live in a SCO environment; this can be useful for installation scripts,
for example. To explicitly load the emulator with a BSD program, use the
sco(1) command.
The emulator supports debug traces using the environment variable
EMULATE_DEBUG. The emulator will print out a trace of its emulated system
calls if you run a program with EMULATE_DEBUG set to 1. If you set
EMULATE_DEBUG to 8, the emulator will execute a built-in breakpoint in
its startup code, which is useful for breakpoint debugging inside the em-
ulator (see BUGS below). Adding 4 to EMULATE_DEBUG enables filename
translation debugging. To turn on two debug modes simultaneously, just
add the values. Note that emulator debugging is disabled for `setuid'
programs.
FILES
/sco/emulator the emulator image
/sco/filemap the filename translation table
/sco/shlib directory of emulated iBCS2/SCO shared libraries
/sco/dev/socksys empty file with protections for socket emulation
/sco/bin simple emulations of a few System V programs
/sco/etc simple emulations of SCO custom and fixperm
SEE ALSOelf(5), sco(1)
Intel386 Family Binary Compatibility Specification 2
HISTORY
Written by Donn Seeley at BSDI for BSD/OS 1.1.
BUGS
Releases of BSD/OS prior to release 3.0 came with a -lipc library. In
those earlier releases, it was necessary to link BSD/OS programs with
-lipc if you wanted them to use System V IPC (shared memory, semaphores,
message queues). Several bugs were related to this IPC implementation.
These bugs are no longer present in 3.0, which has a completely different
System V IPC emulation. However, as a consequence of the new implementa-
tion, BSD/OS programs linked with the old -lipc library will no longer
interoperate with SCO programs running under the emulation if they use
System V IPC. The BSD/OS programs must be re-linked without -lipc under
3.0 in order for them to interoperate.
The emulator and the shared libraries can print an error message and exit
in certain unusual situations. Please report any such messages to BSDI
support. If you want to debug the emulator yourself, the following
.gdbinit file can be useful:
add-sym /sco/emulator 0x1000
dir /usr/src/sco/emulator
add-sym /sco/shlib/libc_s 0
dir /usr/src/sco/shlib/libc
The emulator does not support alternate signal stacks, and neither does
the iBCS2. However BSD programs that use alternate signal stacks may not
work properly when loaded with the emulator.
There is only limited support for the huge number of standard iBCS2
ioctl(2) calls. In particular, none of the console ioctl(2) calls work
yet. Standard console escape sequences are supported, however, as are
termio terminal ioctl(2) calls.
Several system calls are not yet emulated. These include: mount,
umount, stime, uadmin, sysfs, ptrace, pgrp, plock, mknod (except
for FIFOs), and ustat. None of the STREAMS-related system calls are sup-
ported, although TLI calls using the shared NSL library work, since they
can be emulated without STREAMS.
The iBCS2 mandates support for Xenix binaries. This is not currently
available. Also, COFF binaries other than ZMAGIC format are not support-
ed. Support for COFF shared libraries has been coded but never tested;
BSDI only supports elf(5) format shared libraries. Currently the only
functional shared library emulations are the C library,
/sco/shlib/libc_s, and the network services shared library,
/sco/shlib/libnsl_s.
There are no cross-development tools supplied for the iBCS2 environment.
There are no compilers, assemblers or linkers to help you produce iBCS2
executable files.
The emulated custom and fixperm utilities have been only lightly tested,
and handle only small subsets of the functionality of the equivalent Sys-
tem V programs.
There are only ad hoc replacements for System V style utilities. A few
are listed in /sco/filemap; for some installations of third party soft-
ware, it may be necessary to add a few more. Note that in writing a re-
placement script, you can access absolute pathnames without translation
through /sco/filemap by using `//' instead of `/' at the root; for exam-
ple, //bin/expr locates the real /bin/expr, not a mapped version.
BSDI BSD/OS October 18, 1996 3
