-.TH EM_B 6
+.TH EM_B 6 2017-01-18
.ad
-
-
.SH NAME
em_b \- ACK B compiler
-
-
.SH SYNOPSIS
.B ~em/lib/ack/em_b
-.RI [ options ]
-
-
+.RI [ options ]
.SH DESCRIPTION
.I em_b
-is a port of the ABC B compiler to the ACK. Interested parties will be
+is a port of the ABC B compiler to the ACK.
+Interested parties will be
interested in the upstream distribution here:
-
.nf
.sp
https://github.com/aap/abc
.fi
-
-However, the version here has been heavily modified --- bug reports should be
+.PP
+However, the version here has been heavily modified \(em bug reports should be
filed with the ACK, not with the upstream compiler.
-
.PP
Since B was designed for machines with word addressing, some hacking is
-required to make it work on modern, byte addressed machines. The generated
+required to make it work on modern, byte addressed machines.
+The generated
code expects B variables to contain word addresses, and then generates
code to transform these into native addresses before use (which,
-unfortunately, impacts performance). However, the ACK's linker doesn't know
+unfortunately, impacts performance).
+However, the ACK's linker doesn't know
how to emit word addresses into the program's data sections, and so a
separate fixup stage has to happen at runtime, just before \fBmain()\fP,
to convert the byte addresses into word addresses.
-
.PP
The end result is that using multiple source files with B is somewhat
unwieldy, requiring each module to be explicitly named and then an extra
-stage to generate the fixup code. See the \fBack\fP(1) and \fBabmodules\fP(1)
-for details.
-
-
+stage to generate the fixup code.
+See the \fBack\fP(1) and \fBabmodules\fP(1) for details.
.SH OPTIONS
-
.I em_b
accepts the following flags:
-
.IP \-w\ \fIsize\fP
-Sets the word size, used for scaling addresses. Usually either 2 or 4.
-
+Sets the word size, used for scaling addresses.
+Usually either 2 or 4.
.IP \-B\ \fIname\fP
Sets the name of the module currently being compiled (used to generate the
-fixup table symbol name). Defaults to \fImain\fP if not specified.
-
+fixup table symbol name).
+Defaults to \fImain\fP if not specified.
.IP \-i\ \fIfilename\fP
The source B file.
-
.IP \-o\ \fIfilename\fP
The output compact EM bytecode file.
-
-
-
.SH SEE ALSO
\fIack\fR(1), \fIabmodules\fR(1)
-
.SH REMARKS
It is very unlikely the \fIem_b\fP will ever be useful for anything.
-.TH EM_M2 6 "$Revision$"
+.TH EM_M2 6 2017-01-18
.ad
.SH NAME
em_m2 \- ACK Modula\-2 compiler
.SH SYNOPSIS
.B ~em/lib.bin/em_m2
-.RI [ option ]
+.RI [ option ]
.I source
.I destination
.SH DESCRIPTION
The input is taken from
.IR source ,
while the
-EM code is written on
+EM code is written on
.IR destination .
-.br
+.PP
.I Option
is a, possibly empty, sequence of the following combinations:
.IP \fB\-I\fIdirname\fR
.IP \fB\-g\fR
produce a DBX-style symbol table.
.IP \fB\-l\fR
-enable local extensions. Currently, there are two local extensions:
+enable local extensions.
+Currently, there are two local extensions:
procedure constants, and the type LONGCARD.
.IP \fB\-s\fR
make INTEGER ranges symmetric, t.i., MIN(INTEGER) = - MAX(INTEGER).
enable extra array bound checks, for machines that do not implement the
EM ones.
.IP \fB-U\fR
-allow for underscores within identifiers. Identifiers may not start with
+allow for underscores within identifiers.
+Identifiers may not start with
an underscore, even if this flag is given.
.IP \fB-3\fR
only accept Modula-2 programs that strictly conform to [1].
-.LP
.SH SEE ALSO
\fIack\fR(1), \fImodula-2\fR(1)
.IP [1]
-.TH EM_PC 6 "$Revision$"
+.TH EM_PC 6 2017-01-18
.ad
.SH NAME
em_pc \- Pascal compiler
Absence of \fIm\fR or \fIn\fR causes a default value to be retained.
.IP \fB\-w\fR
suppress warning messages.
-.IP
.IP \fB\-R\fR
-disable range checks. Additionally, the run-time tests to see if
+disable range checks.
+Additionally, the run-time tests to see if
a function is assigned, are skipped.
.IP \fB\-A\fR
enable extra array bound checks, for machines that do not implement the
.IP \fB\-C\fR
the lower case and upper case letters are treated differently.
.IP "\fB\-u\fR, \fB\-U\fR"
-allow underscores in identifiers. It is not allowed to start an identifier
+allow underscores in identifiers.
+It is not allowed to start an identifier
with an underscore.
.IP \fB\-a\fR
don't generate code for assertions.
.IP \fB\-c\fR
-allow C-like strings. This option is mainly intended for usage with
-C-functions. This option will cause the type 'string' to be known.
+allow C-like strings.
+This option is mainly intended for usage with C-functions.
+This option will cause the type 'string' to be known.
.IP \fB\-d\fR
allow the type 'long'.
.IP \fB\-i\fR\fIn\fR
set the size of integer sets to \fIn\fR. When not used, a default value is
retained.
.IP \fB\-s\fR
-allow only standard Pascal. This disables the \fB\-c\fR, \fB\-d\fR, \fB\-u\fR,
-\fB\-U\fR and \fB\-C\fR
-options. Furthermore, assertions are not recognized at all (instead of just
+allow only standard Pascal.
+This disables the \fB\-c\fR, \fB\-d\fR, \fB\-u\fR,
+\fB\-U\fR and \fB\-C\fR options.
+Furthermore, assertions are not recognized at all (instead of just
being skipped).
.IP \fB\-t\fR
trace calls and exits of procedures and functions.
-.PP
.SH FILES
.IR ~em/lib/em_pc :
binary of the Pascal compiler.
-.\" $Id$
-.de SB
-.\" SuBheader
-.sp 1
-.PP
-.nr Sf \\n(.f
-.ft B
-\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
-.ft \\n(Sf
-.sp 1
-..
-.TH ACK 1 "$Revision$"
+.TH ACK 1 2017-01-18
.ad
-
+.
.SH NAME
ack \- Amsterdam Compiler Kit
-
+.
.SH SYNOPSIS
\fBack\fP arguments
-
+.
.SH DESCRIPTION
This program transforms sources in several
languages to load files for a variety of machines,
Machine assembly language code.
.IP .o
Object file.
-.PP
-
+.
.SH OPTIONS
-
\fIAck\fP accepts the following flags:
.IP \-m\fImachine\fP
This flag tells \fIack\fP to generate a load file for \fImachine\fP.
Preserve all intermediate files.
If two \fB\-t\fP are used,
\fIack\fP also preserves output of failed transformations.
-
+.
+.sp 1
.IP \-w
Suppress all warning messages.
.IP \-v
Tell \fIack\fP to use the ANSI C compiler instead of the old one.
.IP \-fp
Use the software floating point package, if present.
-
+.
+.sp 1
.IP \-I\fIdir\fP
\&\`#include\' files whose names do not begin with \`/\' are
always sought first in the directory of the \fIfile\fP argument,
Don't generate line directives.
.IP \-C
Leave C-comments in.
-
+.
+.sp 1
.IP \-p
This flag tells both the Pascal and C front ends to include
code enabling the user to do some monitoring/debugging.
is called and just before each return \fBprocexit\fP is called.
These routines are supplied with one parameter, a pointer
to a string containing the name of the routine.
-
+.
+.sp 1
.IP \-B\fIname\fP
Tells the B front end what the name of the module being compiled is, for use
-with separate compilation. Defaults to
+with separate compilation.
+Defaults to
.I main
if not specified. See the section below on compiling B.
-
+.
+.sp 1
.IP \-O
.IP \-O\fInum\fP
.IP \-O\fIopt1,opt2,...\fP
Disable the generation of code by the front ends to
record line number and source file name at run-time.
(This is the default for C and Fortran).
-
+.
+.sp 1
.IP \-l\fIname\fP
Tells \fIack\fP to insert a library module at this point.
For example: the library \fImon\fP contains the
a file with \fIsuffix\fP would be included in the arguments.
.IP \-LIB
This flag tells the peephole optimizer
-.RF em_opt 6
+em_opt(6)
to add information about the visibility of the names used
to each output module.
This is needed by
assembler/linkers when these modules are to be inserted
in libraries.
-
+.
+.sp 1
.IP \-{xxx}
The string starting after \`{\' and terminated by a \`}\' is passed
as an option string to the Pascal compiler and supersedes corresponding
The changed options are recorded in the "e.out" header.
These flags \-\- and \-+ are passed to the assembler for this purpose.
So, \-\-t and \-+pfce invert the defaults.
-
+.
+.sp 1
.IP \-R\fIprogram=xxx\fP
Replace the \fIprogram\fP by the pathname \fIxxx\fP.
The program names referred to later in this manual are allowed here.
.PP
All arguments without a suffix or with an unrecognized suffix
are passed to the loaders, as for flags.
-
+.
.SH PREPROCESSOR
All C source programs are run through the preprocessor
before they are fed to the compiler proper.
EM_SSIZE:size of shorts (C):EM_LSIZE:size of longs (C+Pascal)
EM_FSIZE:size of floats (C):EM_DSIZE:size of doubles (C+Pascal)
.TE
-.sp 1
+.PP
The name of the \fImachine\fP or something like it when
the machine name is numeric is also defined (as 1).
As the ANSI C rules forbid this, in ANSI C, underscores are prepended to
these names.
.PP
The default directories searched for include files differ for each machine.
-
+.
.SH COMPILING B
-
-B programs have special needs when compiled with the ACK. B modules have to be
+B programs have special needs when compiled with the ACK.
+B modules have to be
initialised before use, to convert pointer addresses to word addresses; this is
done automatically when compiling a single B source file to an executable, but
must be done manually when using separate compilation.
-
.PP
To do this, compile your B modules with the \fI-B\fP option as usual, and then
use the
.B abmodules
program to scan the object files and emit a C file which performs the
-initialisation. Then compile this as well into an object file, and link the
-whole lot together. The result will be a runnable executable.
-
+initialisation.
+Then compile this as well into an object file, and link the
+whole lot together.
+The result will be a runnable executable.
.PP
-Beware --- referring to an uninitialised module will cause your program to
+Beware \(em referring to an uninitialised module will cause your program to
crash!
-
.PP
The default initialiser in the B standard library looks for a module called
\fBmain\fP.
-
.PP
For example:
-
.nf
.sp
ack -c -mpc86 thismodule.b -Bthismodule
ack -c -mpc86 binit.c
ack -mpc86 -o pc86.exe thismodule.o thatmodule.o theothermodule.o binit.o
.fi
-
+.
.SH PROGRAMS
\fIAck\fP uses one or more programs in each phase of the
transformation.
\&.o:cv:a.out:Conversion from Ack object to machine object
.TE
.in -2
-
+.
.SH "ENVIRONMENT VARIABLES"
.IP ACKDIR
If set, this environment variable overrides ack's idea of its home
.IP ACKFE
If set, this environment variable tells ack where to get the front-end
description file.
+.
.SH "SEE ALSO"
-.PD 0
em_opt(6), em_ass(6), em_cg(6), ack.out(5)
.IP [1]
A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
Stevenson, \fIDescription of a machine architecture for use with
block structured languages\fP, Informatica rapport IR-81.
+.PD 0
.IP [2]
K. Jensen and N. Wirth,
\fIPASCAL, User manual and report\fP Springer Verlag.
.IP [11]
C.J.H. Jacobs, \fIThe ACK Modula-2 Compiler\fP.
.PD
+.
.SH DIAGNOSTICS
-.PD
The diagnostics are intended to be self\-explanatory.
+.
.SH BUGS
Not all warning messages are superseded by \fB\-w\fP.
-.br
+.PP
Argument assembly files are not preprocessed when fed into the
universal assembler/loader.
.SH AUTHOR
-.TH ABMODULES 1
+.TH ABMODULES 1 2017-01-18
.SH NAME
abmodules \- find B modules
-
.SH SYNOPSIS
abmodules [ \-o outputfile.c ] [ file ... ]
-
.SH DESCRIPTION
.I abmodules
finds B modules in a set of ack.out(5) format object files, and either lists
them or generates a C file which initialises the modules.
.PP
This tool is used for multiple compilation of B programs; B modules must be
-initiaised before use, and this tool generates the initialisation code for
-programs containing an abitrary number of modules. See em_b(6) for details.
+initialised before use, and this tool generates the initialisation code for
+programs containing an abitrary number of modules.
+See em_b(6) for details.
.PP
Options are:
.TP
Write C source to
.I filename
containing a definition of a binit() function which will initalise all modules
-found. If not present, a simple list of module names is written to stdout
-instead.
-
+found.
+If not present, a simple list of module names is written to stdout instead.
.SH SEE ALSO
ack.out(5), em_b(6)
-.TH AELFLOD 1 "$Revision$"
+.TH AELFLOD 1 2017-01-18
.SH NAME
aelflod \- ACK ELF loader
.SH SYNOPSIS
.B aelflod
-[-a\fInumber\fP] [-b] [-h] [-l] [-m\fInumber\fP] [-v] inputfile outputfile
+[\-a\fInumber\fP] [\-b] [\-h] [\-l] [\-m\fInumber\fP] [\-v]
+inputfile outputfile
.SH DESCRIPTION
.I aelflod
converts an absolute ack.out file into a simple binary memory
-.TH ANM 1 "$Revision$"
+.TH ANM 1 2017-01-18
.SH NAME
anm \- print name list
.SH SYNOPSIS
.I Anm
prints the name list (symbol table) of each ack.out(5) format object
.I file
-in the argument list. If an argument is an aal(1) or arch(1) archive,
+in the argument list.
+If an argument is an aal(1) or arch(1) archive,
a listing of each object file in the archive will be produced.
If no
.I file
Each symbol name is preceded by its value, a section indicator
and a type indicator.
A section indicator can be
-.SM
-.B U
+.SB U
(undefined symbol),
-.SM
-.B A
+.SB A
(absolute symbol),
-.SM
-.B C
+.SB C
(common symbol), a section number (section related symbol),
or
-.SM
-.B -
+.SB \-
(other symbol).
A type indicator can be
-.SM
-.B F
+.SB F
(filename),
-.SM
-.B M
+.SB M
(module name),
-.SM
-.B E
+.SB E
(external (global) symbol),
or
-.SM
-.B -
+.SB \-
(local symbol).
The output is sorted alphabetically.
.PP
.TP
.B \-s
Sort in section order.
-.sh FILES
.SH SEE ALSO
ack.out(5)
-.TH ASLOD 1 "$Revision$"
+.TH ASHOW 1 2017-01-18
.SH NAME
ashow \- make the contents of an ACK object file human readable
.SH SYNOPSIS
ashow inputfile inputfile...
.SH DESCRIPTION
.I ashow
-dumps the contents of an ack.out file in human-readable form. It shows
+dumps the contents of an ack.out file in human-readable form.
+It shows
details of all symbols, relocation entries, sections, and other information.
-
.SH "SEE ALSO"
ack.out(5)
-.TH ASIZE 1 "$Revision$"
+.TH ASIZE 1 2017-01-18
.SH NAME
asize \- size of an object file
.SH SYNOPSIS
-.TH ASLOD 1 "$Revision$"
+.TH ASLOD 1 2017-01-18
.SH NAME
aslod \- ACK simple loader
.SH SYNOPSIS
.B aslod
-[-h] [-v] inputfile outputfile
+[\-h] [\-v] inputfile outputfile
.SH DESCRIPTION
.I aslod
converts an absolute ack.out file into a simple binary memory dump.
-.TH ASTRIP 1 "$Revision$"
+.TH ASTRIP 1 2017-01-18
.SH NAME
astrip \- remove symbols and relocation information
.SH SYNOPSIS
This is useful to save space after a program has been
debugged.
.SH FILES
-/tmp/s? temporary file
+.IP /tmp/s? 16n
+temporary file
.SH "SEE ALSO"
ack.out(5)
-.\" $Id$
-.TH AAL 1 "$Revision$"
+.TH AAL 1 2017-01-18
.ad
.SH NAME
aal \- archive and library maintainer
.PP
.I Key
is one character from the set
-.B qdrtx,
+.BR qdrtx ,
optionally concatenated with
one or more of
-.B vlc.
+.BR vlc .
.I Afile
is the archive file.
The
.I afile
is created.
.SH FILES
-/tmp/ar.* temporaries
+.IP /tmp/ar.* 16
+temporaries
.SH "SEE ALSO"
-led(6), arch(5),
+led(6), arch(5)
.SH BUGS
If the same file is mentioned twice in an argument list,
it may be put in the archive twice.
-.TH "ACK.OUT" 5 "$Revision$"
+.TH "ACK.OUT" 5 2017-01-18
.ad
.SH NAME
ack.out\ \-\ ACK-assembler and link editor output
.ta \w'#define x'u +\w'XXXXXXXX'u +\w'XXXXXXXXXXX'u
.PP
In the following discussion, some structures are defined using
-\fBlong\fR and \fBshort\fR as type indicators.
+\fBlong\fR and \fBshort\fR as type indicators.
It is assumed that the size of a short is 2 bytes (chars) and that the
size of a long is 4 bytes.
However, these types
};
.fi
.PP
+.nf
#define HF_LINK 0x0004 /* unresolved references left */
+.fi
.PP
The fields of this structure have the following purpose:
.nr x \w'oh_magic\ \ \ 'u
.br
The next part of an object file contains the sections themselves.
Usually, the LED program places the sections right behind one another in the
-target machine, taking the
-alignment requirements into account. However, the user is allowed to give
-the start addresses of each section. But if the user gave a start address for
+target machine, taking the alignment requirements into account.
+However, the user is allowed to give
+the start addresses of each section.
+But if the user gave a start address for
say section 2, but not for section 3, section 3 will be put
right behind section 2.
.PP
Contains several flags: One of RELO1, RELO2 and RELO4 is set, indicating the
size of the relocatable datum, RELPC is set when the datum is
relocated pc relative, RELBR and RELWR indicate byte and word order of
-the relocatable datum. RELBR and RELWR are needed here. It is not sufficient
+the relocatable datum.
+RELBR and RELWR are needed here.
+It is not sufficient
to have flags for them in the header of the object file, because some
machines (NS 32016) use several of the possible combinations in their
instruction encoding.
.IP or_sect \nxu
-Contains the section number of the referenc\fIing\fR section. This is a number
-that lies between S_MIN and S_MAX. The section indicated with number S_MIN
+Contains the section number of the referenc\fIing\fR section.
+This is a number that lies between S_MIN and S_MAX.
+The section indicated with number S_MIN
is the first section in the sections-section, etc.
.IP or_addr \nxu
Contains the address of the relocatable datum, in the form of an
Usually contains the index of the referenced symbol in the symbol table,
starting at 0.
In this case, the reference is to an undefined external symbol, a common
-symbol, or a section name. The relocatable datum then contains
+symbol, or a section name.
+The relocatable datum then contains
an offset from the indicated symbol or the start of the indicated section.
It may, however, also have the same value as
-the \fIoh_nname\fR field of the header. In this case the relocatable datum
+the \fIoh_nname\fR field of the header.
+In this case the relocatable datum
is an absolute number, and the datum is relocated pc relative.
The relocatable datum must then be relocated with respect to the
base address of its section.
.PP
The members of this structure have the following purpose:
.IP on_foff \nxu
-Contains the offset of the name from the beginning of the file. The name
-extends from the offset to the next null byte.
+Contains the offset of the name from the beginning of the file.
+The name extends from the offset to the next null byte.
.IP on_type \nxu
The S_TYP field of this member contains the section number of the symbol.
Here, this number may be S_ABS for an absolute item, or S_UND, for an
-undefined item. The S_EXT flag is set in this member if the symbol is external.
+undefined item.
+The S_EXT flag is set in this member if the symbol is external.
The S_ETC field has the following flags:
S_SCT is set if the symbol represents a section name,
S_COM is set if the symbol represents a common name,
.IP on_desc \nxu
Currently not used.
.IP on_valu \nxu
-Is not used if the symbol refers to an undefined item. For absolute items
+Is not used if the symbol refers to an undefined item.
+For absolute items
it contains the value, for common names it contains the size, and
for anything else it contains the offset from the beginning of the section.
In a fully linked binary, the beginning of the section is added.
.PP
.B The string area.
.br
-The last part of an object file contains the name list. This is just a
-sequence of null-terminated strings.
+The last part of an object file contains the name list.
+This is just a sequence of null-terminated strings.
.PP
The relocation information, the symbol table, and the name list do not
have to be present, but then of course we do not have a relocatable
.br
The following miscellaneous defines might come in handy when reading
object files:
-.fi
.PP
.nf
/*
-.TH LED 6 "$Revision$"
+.TH LED 6 2017-01-18
.ad
.SH NAME
led \- link editor
and
.I nnnn
apply.
-.TP
+.TP
.B \-o
The
.I name
.I led
output file, instead of
.BR a.out .
-.TP
+.TP
.B \-r
Generate relocation information in the output file
so that it can be the subject of another
.TP
.B \-n
Usually, after linking, a value in the namelist represents an absolute
-address. Sometimes, particularly when using the \fB\-c\fR flag, it may be
+address.
+Sometimes, particularly when using the \fB\-c\fR flag, it may be
useful to have as value the offset with respect to the beginning of the
corresponding section. The \fB\-n\fR flag enables this.
.TP
`Strip' the output, that is, remove the name table
and relocation information to save space (but impair the
usefulness of the debuggers).
-.TP
+.TP
.B \-u
Take the following argument as a symbol and enter
it as undefined in the name table.
This option is useful in resolving 'multiply defined' problems.
.SH FILES
~em/lib.bin/em_led
-a.out output file
+.PD 0
+.IP a.out 24n
+output file
+.PD
.SH "SEE ALSO"
-ack(1)
-arch(1)
-ack.out.h(5)
+ack(1),
+arch(1),
+ack.out.h(5),
uni_ass(6)
-.\" $Id$
-.TH EM_DECODE 6 "$Revision$"
+.TH EM_DECODE 6 2017-01-18
.ad
.SH NAME
-em_decode,em_encode \- compact to readable EM and v.v.
+em_decode, em_encode \- compact to readable EM and v.v.
.SH SYNOPSIS
.B ~em/lib.bin/em_decode
[ inputfile [ outputfile ] ]
-.TH ESIZE I
+.TH ESIZE 1 2017-01-18
.SH NAME
esize \- print info from e.out header
.SH SYNOPSIS
prints information from the
.I e.out
headers of the indicated files, including flags, word and pointer sizes,
-text and data sizes, etc. All values are in decimal.
+text and data sizes, etc.
+All values are in decimal.
.PP
If no parameters are given, the header of
.I e.out
-.\" $Id$
-.TH EM_OPT 6 "$Revision$"
+.TH EM_OPT 6 2017-01-18
.ad
.SH NAME
em_opt \- EM peephole optimizer
.SH SYNOPSIS
.B ~em/lib.bin/em_opt
-[-Ln] [-m[l]<num>] [ argument ]
+[\-Ln] [\-m[l]<num>] [ argument ]
.SH DESCRIPTION
Em_opt reads a compact EM-program, argument or standard input,
and produces another compact EM program on standard output
before running a codegenerator,
it may be left out when interpretation is wanted.
Flags recognized are:
-.IP -L
+.IP \-L
Make a library module.
This means that the output will start with a message giving
the names of all exported entities in this module.
-.IP -n
+.IP \-n
Do not optimize.
No peephole optimizations will be performed,
other functions will be carried out.
-.IP -m<num>
+.IP \-m<num>
Try to replace multiplies with constants by combinations of shifts and adds,
-but no more than <num> of them. Integer overflow detection is lost with this
-option.
-.IP -ml<num>
-Like -m<num>, but also for long multiplies.
+but no more than <num> of them.
+Integer overflow detection is lost with this option.
+.IP \-ml<num>
+Like \-m<num>, but also for long multiplies.
.SH "FILES"
-/tmp/emopt??????, is used when the -L flag is given only.
+/tmp/emopt??????, is used when the \-L flag is given only.
.SH "SEE ALSO"
ack(1)
.PD 0
public / ack.git / commitdiff