Inter-Office Memorandum
To  CedarUsers  Date December 13, 1983
From Russ Atkinson  Location PARC
Subject Lister documentation Organization CSL
Lister Documentation
Lister is a program to produce human readable files from bcd files produced by the Compiler and Binder. Lister registers a variety of commands, each of which produces a different set of information from a given list of bcd files.
Each command takes a list of files as arguments. The default input file extension is bcd. The output file extension is derived from the command name, and is given with the description of each command. There are no switches or options.
Each listing file starts with information about the bcd file being examined. As an example, for the command "bcdList Lister" the output file is Lister.bcdList, which starts with
Lister.bcdList
object: Lister.bcd {4365c935458b}
source: Lister.config {00008a129bc4 (October 24, 1983 7:14 pm)}
creator: {0c0b0003000f}
The version stamps are printed in hexadecimal. In the case of source files, the version stamps are also interpreted as create dates. The creator is the version stamp of the compiler or binder that produced the bcd file.
As a Cedar component, Lister is described by Lister.df. The tool is named Lister.bcd. The registered commands are listed below.
BcdLister
This commands lists the contents of a bcd file, which may contain multiple modules. The extension for the produced file is bcdList. The information produced includes:
Configurations - for bcd files produced by the Binder, this group gives information about the configurations in the bcd file.
Imports - lists the definitions modules that are imported by the bcd file.
Exports - lists the definitions modules that are exported by the bcd file.
Exported variables - lists the variables (if any) that are exported by the bcd file.
Modules - lists the modules that are contained by the bcd file. An example listing follows:
CodeListerImpl [14], file: CodeListerImpl [4], config: Lister [0]
switches: bc-jlns, packageable,
framesize: 75, gfi: 2, ngfi: 2, links: code
code: (self) [base: 52, pages: 13], offset: 24B, length: 13756B, link space
symbols: CodeListerImpl [base: 19, pages: 38+2]
#links: 19, links:
proc[19,11], proc[12,0], proc[13,0], proc[16,23], proc[16,18], proc[1,25], proc[12,12], proc[12,25], proc[1,4], proc[11,6], proc[9,15], proc[11,5], proc[1,22], proc[1,27], proc[1,20], proc[1,17], proc[14,9], proc[13,29], proc[14,13]
#types: 5, offset: 4, indices:
[10], [1], [11], [12], [13]
frame type: 2
#ref lits: 33, offset: 9, indices:
[285], [286], [287], [288], [289], [290], [226], [282], [291], [292], [293], [294], [295], [296], [297], [298], [299], [300], [301], [302], [303], [304], [305], [306], [307], [308], [309], [310], [311], [312], [313], [314], [315]
Files - lists the files (and their version stamps) that are necessary to make the bcd file.
Frame Packs - <not yet documented>
Spaces - <not yet documented>
BodyLister
This commands lists the bodies of a single module bcd file. The extension for the produced file is bodyList. Each body listing entry gives the name of the procedure (if any), the entry point (for procedures), the frame address (for nested procedures), the context index, and the nesting level of the body. An example of the first few entries in CodeListerImpl.bodyList is:
Body: CodeListerImpl, ep: 0, attrs: --n
context: 20, level: 2
Body: DigestFGT, ep: 1, attrs: x--
context: 34, level: 2
Body: AddMyEntry, ep: 6, frame addr: 10, attrs: x--
context: 0, level: 3
Body: (anon)
context: 56, level: 3
Body: (anon)
context: 58, level: 3
Body: AddBodyFGT, ep: 4, frame addr: 26, attrs: x-n
context: 60, level: 3
CodeLister
This commands lists the code of a single module bcd file. The extension for the produced file is codeList. The output shows source statements (provided that the appropriate source is available), followed by the code produced by those source statements. An example procedure from CodeListerImpl is:
GetByte: PROC [pc: CARDINAL] RETURNS [BYTE] = {
Entry point: 14, Frame size: 11
1657B,E 3536B: [167B] LINKB 12B
1660B,E 3540B: [34B] PL1
w: LONG POINTER TO PrincOps.InstWord = codebase + pc/2;
1660B,O 3541B: [65B] LIN1
1661B,E 3542B: [263B] SHIFT
1661B,O 3543B: [56B] LI0
1662B,E 3544B: [10B] LL0
1662B,O 3545B: [114B] RDB 21B
1663B,O 3547B: [264B] DADD
1664B,E 3550B: [162B] SLDB 6B
RETURN [IF pc MOD 2 = 0 THEN w.evenbyte ELSE w.oddbyte];
};
1665B,E 3552B: [11B] LL1
1665B,O 3553B: [57B] LI1
1666B,E 3554B: [260B] AND
1666B,O 3555B: [245B] JZNEB 10B (3565B)
1667B,O 3557B: [21B] LLDB 6B
1670B,O 3561B: [56B] LI0
1671B,E 3562B: [153B] RSTRL 0B
1672B,E 3564B: [204B] J6  (3572B)
1672B,O 3565B: [21B] LLDB 6B
1673B,O 3567B: [56B] LI0
1674B,E 3570B: [153B] RSTRL 1B
1675B,E 3572B: [343B] RET
Instructions: 21, Bytes: 30
ExportsLister
This commands lists the exports of a bcd file, which may contain multiple modules. The extension for the produced file is exportsList. <format not yet documented>
FGTLister
This commands lists the fine grain table of a single module bcd file. The extension for the produced file is fgtList. <format not yet documented>
GlobalFramesLister
This commands lists the global frames of a bcd file, which may contain multiple modules. The extension for the produced file is globalFramesList. <format not yet documented>
RTBcdLister
This commands lists the runtime types information for a bcd file, which may contain multiple modules. The extension for the produced file is rtBcdList. <format not yet documented>
ShortBcdLister
This commands lists the contents of a bcd file, which may contain multiple modules. The extension for the produced file is bcdList. The listing has slightly less information than that produced by BcdLister.
SortedDefsLister
This command takes a list of bcd files from the command line and produces a single output file, Symbols.sort which approximates the source necessary to produce all the top level definitions in the definitions files contained in the set of input files. Binder output and implementation modules are filtered out and ignored. The program cannot exactly reproduce the original source for default field values since information is lost in the compilation process. For large constant values, it simply notes that there is a constant default value. Below is a segment of the listing of all interfaces exported by df files on /cedar/cedar6.0/top:

ExportInterface: --RPCLupine--PROC [user: RPC.Principal,
password: RPC.EncryptionKey, interface: RPC.InterfaceName,
dispatcher: Dispatcher, stubProtocol: RPC.VersionRange,
localOnly: BOOLEAN ← FALSE] RETURNS [interfaceInstance: ExportHandle];
Exports: --AMModel--PROC [context: Context] RETURNS [
LIST OF PartialInterfaceInstance];
EXPRecord: --BcdDefs--TYPE = RECORD[name: NameRecord, size: [0..255],
port: Portable, namedInstance: BOOL, typeExported: BOOL, file: FTIndex,
links: ARRAY [0..0) OF Link];
ExpSingleMax: --Ieee--INTEGER = 127;
ExpSingleMin: --Ieee--INTEGER = -126;
exptype: --BcdDefs--Table.Selector = 6;
Ext: --Ieee--TYPE = RECORD[det: Details, exp: INTEGER, frac: LongNumber];
Extended: --Real--TYPE = RECORD[type: NumberType, sign: BOOL, exp: INTEGER,
frac: LONG CARDINAL];
ExtendFileHeader: --FileInternal--PROC [file: File.Handle,
newRunPages: CARDINAL, newPropertyPages: CARDINAL];
The current implementation of this command writes a plain-text file with two spaces for each indentation level. The Tioga exec command ReadIndent properly converts this into levels. It produces an outer level node for each initial letter of the alphabet (that has any identifier beginning with it) so clipping to top level allows faster positioning within the file. The fonts-and-faces formatting above was done by the Tioga MesaFormatting command (control-M).
SortedSymbolLister
This command takes a list of bcd files from the command line and produces a single output file, Symbols.sort which approximates the source necessary to produce all the top level definitions in the compiler output files contained in the set of input files. Binder output is filtered out and ignored. It works much like SortedDefsLister, except that top level declarations in program modules are included as well.
SymbolLister
This commands lists the bodies of a single module bcd file. The extension for the produced file is symbolList. <format not yet documented>
UnboundLister
This commands lists the unbound exports for a bcd file, which may contain multiple modules. The output goes to the command output stream, rather than to a file. This command is useful to determine if there are exported files with some of their entries unbound.
UsingLister
This command generates a DIRECTORY clause for a single module bcd file. The extension for the produced file is usingList. The results may not be entirely correct, yet should be quite close (unfortunately, the information in the bcd file may be ambiguous). The intention is for people to develop modules without using USING clauses, then to use this command to generate those clauses. Where there are extra names or missing names in the clauses the compiler will generate sufficient messages to allow repair of the USING clauses in (typically) a single pass.