From f91bc2804d46b43b6d6aea876c95d6e05664fbe7 Mon Sep 17 00:00:00 2001 From: George Koehler Date: Wed, 18 Jan 2017 23:02:30 -0500 Subject: [PATCH] Tune the installed manual pages. This commit slightly improves the formatting of the manuals. My OpenBSD machine uses mandoc(1) to format manuals. I check the manuals with `mandoc -T lint` and fix most of the warnings. I also make other changes where mandoc didn't warn me. roff(7) says, "Each sentence should terminate at the end of an input line," but we often forgot this rule. I insert some newlines after sentences that had ended mid-line. roff(7) also says that blank lines "are only permitted within literal contexts." I delete blank lines. This removes some extra blank lines from mandoc's output. If I do want a blank line in the output, I call ".sp 1" to make it in man(7). If I want a blank line in the source, but not the output, I put a plain dot "." so roff ignores it. Hyphens used for command-line options, like \-a, should be escaped by a backslash. I insert a few missing backslashes. mandoc warns if the date in .TH doesn't look like a date. Our manuals had a missing date or the RCS keyword "$Revision$". Git doesn't expand RCS keywords. I put in today's date, 2017-01-18. Some manuals used tab characters in filled mode. That doesn't work. I use .nf to turn off filled mode, or I use .IP in man(7) to make the indentation without a tab character. ack(1) defined a macro .SB but never used it, so I delete the definition. I also remove a call to the missing macro .RF. mandoc warns about empty paragraphs. I deleted them. mandoc also warned about these macro pairs in anm(1): .SM .B text The .SM did nothing because the .B text is on a different line. I changed each pair to .SB for small bold text. I make a few other small changes. --- lang/b/compiler/em_b.6 | 47 ++++++++--------------- lang/m2/comp/em_m2.6 | 15 ++++---- lang/pc/comp/em_pc.6 | 22 ++++++----- util/ack/ack.1.X | 87 ++++++++++++++++++++---------------------- util/amisc/abmodules.1 | 14 +++---- util/amisc/aelflod.1 | 5 ++- util/amisc/anm.1 | 30 ++++++--------- util/amisc/ashow.1 | 6 +-- util/amisc/asize.1 | 2 +- util/amisc/aslod.1 | 4 +- util/amisc/astrip.1 | 5 ++- util/arch/aal.1 | 12 +++--- util/led/ack.out.5 | 43 ++++++++++++--------- util/led/led.6 | 22 ++++++----- util/misc/em_decode.6 | 5 +-- util/misc/esize.1 | 5 ++- util/opt/em_opt.6 | 21 +++++----- 17 files changed, 166 insertions(+), 179 deletions(-) diff --git a/lang/b/compiler/em_b.6 b/lang/b/compiler/em_b.6 index e0d1b40fe..f7030f214 100644 --- a/lang/b/compiler/em_b.6 +++ b/lang/b/compiler/em_b.6 @@ -1,68 +1,53 @@ -.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. diff --git a/lang/m2/comp/em_m2.6 b/lang/m2/comp/em_m2.6 index a122a4a30..dfe41a3df 100644 --- a/lang/m2/comp/em_m2.6 +++ b/lang/m2/comp/em_m2.6 @@ -1,10 +1,10 @@ -.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 @@ -15,9 +15,9 @@ into EM code. 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 @@ -65,7 +65,8 @@ make all procedure names global, so that \fIadb\fR(1) understands them. .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). @@ -77,11 +78,11 @@ disable all range checks. 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] diff --git a/lang/pc/comp/em_pc.6 b/lang/pc/comp/em_pc.6 index f544e0536..7ba0de3eb 100644 --- a/lang/pc/comp/em_pc.6 +++ b/lang/pc/comp/em_pc.6 @@ -1,4 +1,4 @@ -.TH EM_PC 6 "$Revision$" +.TH EM_PC 6 2017-01-18 .ad .SH NAME em_pc \- Pascal compiler @@ -45,9 +45,9 @@ and the \fIn\fR parameter for the alignment of that type. 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 @@ -55,26 +55,28 @@ EM ones. .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. diff --git a/util/ack/ack.1.X b/util/ack/ack.1.X index 671aa4e47..8ea920586 100644 --- a/util/ack/ack.1.X +++ b/util/ack/ack.1.X @@ -1,23 +1,12 @@ -.\" $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, @@ -73,10 +62,8 @@ Optimized compact EM assembly code. 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. @@ -106,7 +93,8 @@ Note: \fIack\fP refuses to overwrite argument \fI.e\fP files. 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 @@ -118,7 +106,8 @@ Tell the C-compiler to conform to "Kernighan & Ritchie" C. 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, @@ -136,7 +125,8 @@ preprocessing. 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. @@ -144,13 +134,16 @@ Each time a routine is entered the routine \fBprocentry\fP 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 @@ -239,7 +232,8 @@ for higher levels: as for \-O4. 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 @@ -259,13 +253,14 @@ These flags tell \fIack\fP to include the libraries needed when 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 @@ -293,7 +288,8 @@ the defaults per program. 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. @@ -320,7 +316,7 @@ Sparc, Vax, Intel 80386. .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. @@ -341,40 +337,37 @@ EM_WSIZE:wordsize:EM_PSIZE:pointer size 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 @@ -384,7 +377,7 @@ abmodules -o binit.c thismodule.o thatmodule.o theothermodule.o 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. @@ -421,7 +414,7 @@ input:name:output:description \&.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 @@ -432,13 +425,14 @@ machine it compiles for. .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. @@ -463,12 +457,13 @@ Informatica rapport IR-99. .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 diff --git a/util/amisc/abmodules.1 b/util/amisc/abmodules.1 index 8d34871f0..1eb67d843 100644 --- a/util/amisc/abmodules.1 +++ b/util/amisc/abmodules.1 @@ -1,18 +1,17 @@ -.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 @@ -20,8 +19,7 @@ Options are: 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) diff --git a/util/amisc/aelflod.1 b/util/amisc/aelflod.1 index 808b95429..e6af7ef2e 100644 --- a/util/amisc/aelflod.1 +++ b/util/amisc/aelflod.1 @@ -1,9 +1,10 @@ -.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 diff --git a/util/amisc/anm.1 b/util/amisc/anm.1 index 48cdff814..a76be02cd 100644 --- a/util/amisc/anm.1 +++ b/util/amisc/anm.1 @@ -1,4 +1,4 @@ -.TH ANM 1 "$Revision$" +.TH ANM 1 2017-01-18 .SH NAME anm \- print name list .SH SYNOPSIS @@ -7,7 +7,8 @@ anm [ \-gnoprus ] [ file ... ] .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 @@ -18,32 +19,24 @@ are listed. 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 @@ -69,6 +62,5 @@ Print only undefined symbols. .TP .B \-s Sort in section order. -.sh FILES .SH SEE ALSO ack.out(5) diff --git a/util/amisc/ashow.1 b/util/amisc/ashow.1 index 842c8ea35..1aaac2623 100644 --- a/util/amisc/ashow.1 +++ b/util/amisc/ashow.1 @@ -1,12 +1,12 @@ -.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) diff --git a/util/amisc/asize.1 b/util/amisc/asize.1 index 89454dcaf..36a4d6ada 100644 --- a/util/amisc/asize.1 +++ b/util/amisc/asize.1 @@ -1,4 +1,4 @@ -.TH ASIZE 1 "$Revision$" +.TH ASIZE 1 2017-01-18 .SH NAME asize \- size of an object file .SH SYNOPSIS diff --git a/util/amisc/aslod.1 b/util/amisc/aslod.1 index f81590739..5a1f857a0 100644 --- a/util/amisc/aslod.1 +++ b/util/amisc/aslod.1 @@ -1,9 +1,9 @@ -.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. diff --git a/util/amisc/astrip.1 b/util/amisc/astrip.1 index 2f83bf1ab..1a3fa5433 100644 --- a/util/amisc/astrip.1 +++ b/util/amisc/astrip.1 @@ -1,4 +1,4 @@ -.TH ASTRIP 1 "$Revision$" +.TH ASTRIP 1 2017-01-18 .SH NAME astrip \- remove symbols and relocation information .SH SYNOPSIS @@ -11,6 +11,7 @@ ack.out(5) format object files. 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) diff --git a/util/arch/aal.1 b/util/arch/aal.1 index 93b41191e..7f9af68ed 100644 --- a/util/arch/aal.1 +++ b/util/arch/aal.1 @@ -1,5 +1,4 @@ -.\" $Id$ -.TH AAL 1 "$Revision$" +.TH AAL 1 2017-01-18 .ad .SH NAME aal \- archive and library maintainer @@ -18,10 +17,10 @@ only understands archives made with .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 @@ -82,9 +81,10 @@ The create option supresses the normal message that is produced when .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. diff --git a/util/led/ack.out.5 b/util/led/ack.out.5 index b49b0976b..fa997e8ca 100644 --- a/util/led/ack.out.5 +++ b/util/led/ack.out.5 @@ -1,4 +1,4 @@ -.TH "ACK.OUT" 5 "$Revision$" +.TH "ACK.OUT" 5 2017-01-18 .ad .SH NAME ack.out\ \-\ ACK-assembler and link editor output @@ -14,7 +14,7 @@ further processed on another. .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 @@ -55,7 +55,9 @@ struct outhead { }; .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 @@ -131,9 +133,10 @@ in tact. .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 @@ -194,13 +197,16 @@ The fields of this structure have the following purpose: 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 @@ -209,10 +215,12 @@ offset from the base of the section indicated in the \fIor_sect\fR field. 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. @@ -250,12 +258,13 @@ struct outname { .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, @@ -265,15 +274,16 @@ and S_MOD is set if the symbol refers to an assembler source file item. .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 @@ -283,7 +293,6 @@ object file. .br The following miscellaneous defines might come in handy when reading object files: -.fi .PP .nf /* diff --git a/util/led/led.6 b/util/led/led.6 index c89866efe..8e4b98e69 100644 --- a/util/led/led.6 +++ b/util/led/led.6 @@ -1,4 +1,4 @@ -.TH LED 6 "$Revision$" +.TH LED 6 2017-01-18 .ad .SH NAME led \- link editor @@ -78,7 +78,7 @@ The previous remarks about and .I nnnn apply. -.TP +.TP .B \-o The .I name @@ -88,7 +88,7 @@ is used as the name of the .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 @@ -104,7 +104,8 @@ at load time. This flag disables the \fB\-r\fP flag. .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 @@ -112,7 +113,7 @@ corresponding section. The \fB\-n\fR flag enables this. `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. @@ -129,9 +130,12 @@ chose to link it (which unresolved reference it resolves). 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) diff --git a/util/misc/em_decode.6 b/util/misc/em_decode.6 index 92f7a084d..a21c939eb 100644 --- a/util/misc/em_decode.6 +++ b/util/misc/em_decode.6 @@ -1,8 +1,7 @@ -.\" $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 ] ] diff --git a/util/misc/esize.1 b/util/misc/esize.1 index e62a17028..c05eb42f3 100644 --- a/util/misc/esize.1 +++ b/util/misc/esize.1 @@ -1,4 +1,4 @@ -.TH ESIZE I +.TH ESIZE 1 2017-01-18 .SH NAME esize \- print info from e.out header .SH SYNOPSIS @@ -9,7 +9,8 @@ esize \- print info from e.out header 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 diff --git a/util/opt/em_opt.6 b/util/opt/em_opt.6 index bdb6587d9..267bd9c69 100644 --- a/util/opt/em_opt.6 +++ b/util/opt/em_opt.6 @@ -1,11 +1,10 @@ -.\" $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]] [ argument ] +[\-Ln] [\-m[l]] [ argument ] .SH DESCRIPTION Em_opt reads a compact EM-program, argument or standard input, and produces another compact EM program on standard output @@ -15,22 +14,22 @@ Some other functions are here that make this program mandatory 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 +.IP \-m Try to replace multiplies with constants by combinations of shifts and adds, -but no more than of them. Integer overflow detection is lost with this -option. -.IP -ml -Like -m, but also for long multiplies. +but no more than of them. +Integer overflow detection is lost with this option. +.IP \-ml +Like \-m, 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