BE displays most of the non-obvious keys you may press on the 2nd line of its status area, at the top of the screen.
BE works by presenting lists to the user. These can be lists of data fields, lists of array elements etc.. A user action can result in a new list being displayed on top of the previous one. Effectively, there is a 'stack' of lists, where you always get to see the topmost one. The level of nesting is always on display at the top right hand corner of the screen.
In this text, ~X is shorthand for Shift+X, ^X is shorthand for Ctrl+X, and @X is shorthand for Alt+X.
Although OS/2, Windows, NetWare, AIX, Linux and DOS machines are able to
support Alt keys, not all UNIXes are.
In fact Alt key support for UNIX can vary depending upon terminal types.
Therefore UNIX versions of BE provides a 'feature' whereby Esc
quickly followed by a key is equivelent to pressing Alt and the key
together.
Many of the keystrokes listed were chosen so as to match the default key bindings of Andys Source Code Folding Editor. In fact, much of the style of the user-interface style is borrowed from AE.
Although not displayed, the arrow keys, such as Up, Down, PgUp, PgDn, Home, End, Left and Right all work in the obvious ways, traversing the list on display. The Wordstar 'cursor diamond' keys ^E, ^X, ^R, ^C, ^W, ^Z, ^S and ^D also work.
As you move around the current list, your line number and total number
of lines in the list are shown on the top right of the screen in the form
line/totallines.
The user can discard the current list, and go back to the previous one by pressing Esc.
q or @X (ie: Alt+X) exits the program. If you have made any changes, you will be prompted as to whether BE should write them out to disk. @W can write out any unsaved changes.
p allows you to 'print' the list on display to a file.
You can specify the filename, and whether to append to or overwrite any
existing file of that name.
^P is a short hand way of saying append to the same file as
last time.
If you haven't specified a file yet with p, the default is
be.log.
Non-printable (but displayable) characters get converted to '.' dots.
f or / or F9 allows you to do a find over the list on display. This only searches as much as the user could see if he were to manually page up and down through the list. The find command is case sensitive. n or F10 can be used to repeat the last find. If a find is taking a long time, it may be interrupted using Ctrl+Break on OS/2, Windows or DOS. Elsewhere, the Esc key may be used. The \ key will reverse the direction of the find, ready for when you next use the 'repeat the last find' function.
i allows you to generate a new list, which only has lines which include a pattern you specify. This new list pops-up on top of the current one. For example, if you have an array of trace-point events, you can easily generate a list of just trace-points from one module. Similarly, x allows you generate a display which excludes lines which match the pattern.
S can be used to generate a new list which is the same as the
current list, except the lines are sorted.
You are prompted for a 'sort after' pattern, and as to whether the result is
to be sorted in ascending or descending order.
You are also prompted whether to do textual unsigned-numeric or signed-numeric
comparison.
Anything on each line, upto and including the 'sort after' pattern is ignored
for the purpose of the sort.
With textual comparison, the strings are compared, with numeric comparison,
the strings are expected to start with an optional sign, a decimal, or
0x preceeded hex value, and these are compared.
N takes a textual snapshot of the current list. As the result is just text, you'll find that all you can do is view the data. This feature can be useful if you are using BE to view changing live data.
The find, include and exclude commands normally do a straight case sensitive
textual comparison.
The editor can be toggled in and out of Extended Regular Expression mode (as in
UNIX egrep), using the @R key.
When set into this mode, future finds, includes and excludes all work with
extended regular expressions.
eg: include (fred|bill)[0-9]+ will include all lines with
'fred' or 'bill', followed by one or more digits.
Similarly, @I can be used to toggle in and out of case sensitive search mode.
The Extended Regular Expression mode case sensitivity mode also affects
the sort command.
The sort command and the use of Extended Regular Expression mode go
naturally hand in hand, because you often want to be able to sort upon
the Nth field of each line.
It is trivial to write an ERE like ,[^,]*, which
matches the first pair of commas (so the sort can be done on the third field),
or 0x[0-9a-f]+ which matches the first hex number.
The Extended Regular Expression mode and case sensitivity mode also affects the 'power address slide' patterns, and tag/untag all matching commands, as explained later.
The r key causes a refresh. BE re-fetches all the data on display. The R key is a slightly more aggressive form of refresh. If a memory extension providing data to BE was caching data, this type of refresh causes it to drop its cache. Sometimes BE is used with an extension to watch live real-time data, and continual refresh is desired. By pressing the periodic update key, @U, you can put BE into a mode whereby it refreshes at regular intervals. The interval is user-selectable. You exit this mode using Ctrl+Break on OS/2, Windows or DOS. Elsewhere, Esc may be used.
Tags may be placed or removed within the list on display by pressing the @T key. You may quickly move backwards or forwards between tags by pressing ^Home or ^End (or @Home or @End. Tags appear as little 'T's on the right hand side of the line. Placing or removing tags in one session or list has no effect on any others.
T and U may be used to tag or untag all lines matching a given pattern or extended regular expression.
If when you use the include or exclude keypresses, you don't specify a pattern or regular expression to match, all lines with a tag are considered to match.
The ! key may be used to execute an operating system command.
This capability can be disabled by the -r command line flag.
@V can be used to bring up a view of a regular text file. There is no text editing capability. As special cases, F1 trys to bring up the help file, and F2 trys to bring up the configuration file.
If @V is used on a directory, then BE will display a list of the files in the directory. If you press Enter whilst on one of these, then it will display the file, or open a list of the subdirectory.
BE doesn't just maintain a single stack of lists. In fact it maintains 10 parallel stacks, or 'sessions'. You can jump between them using the @0, @1, ... @9 keys. This allows you to be looking at several places within your data at once, and to be able to easily hop between them. The current session number is the second from last number on display on the top right corner of the screen. It is initially 1.
@C copies the stack of lists from the previous session onto the current session. Typically you use this when you've found something interesting, and you'd like to leave the current session showing the interesting data, and yet you'd also like to continue investigations around that area.
Given there are 10 sessions, each with any amount of nesting, it can be easy to get lost, so the @K allows you to generate a summary of where you are in each session.
@Z may be used to pop off all the lists in the current session, and effectively reset the nesting level to 1.
@F1 to @F4 inclusive may be used to change the colour
scheme to scheme 0 to 3, as initially specified by the -c
command line argument, or as initially defaulting to 0.
The keys A,O,L,I toggle the display of addresses, offsets,
lengths and array indices.
@A, @E, @B, @O, @D and @H may be used to set the display
mode of the array indices to ASCII, EBCDIC, binary, octal, decimal or hex.
Also, @Y toggles the display of addresses between raw hex, and symbol
table entry and offset.
The @J command toggles the display of symbolic code addresses
which have the lj attribute between the short and long forms.
By default, at startup, BE choses only to show array indices, the
array index mode is hex, addresses are not shown symbolic, and long
jumps are shown in their short form.
The -v command line flag can also be used to change the
startup display flags.
The | (pipe-bar) key toggles the display of pipe bars between
flags in a mapping.
This is typically only used when a mapping has been cleverly defined to do
something like RISC instruction set disassembly, to tidy up the display.
The & (ampersand) key toggles the display of pointer
values.
Normally they are shown, but quite a bit of screen clutter can sometimes be
removed by not showing them.
Pressing @ will cause BE to prompt for a structure definition name, and then an address. It will then pop-up a new list, decoding the memory at the given address as if it were of the specified structure type. When being prompted for the definition name, you can actually type a definition name followed by a numeric expression, in order to display an array of that many elements, each of which is a definition of the given type.
The C allows you to disassemble from a given address,
assuming a disassembler extension
has been supplied to BE via the -C command line argument.
D can be used to pass user-options through to the disassembler.
Initially, if a symbol table is supplied to BE, disassembly stops when the addresses symbols (as in symbol+offset) change. ie: BE stops disassembling more than one function. Although one compiled C function typically has one label, hand written assembler tends to have many labels within one function, so the Y key can toggle between stopping on label changes and ignoring them.
The @F key pops up a list of the memory sections BE is editing. There is one for each file (or memory extension invokation) currently being edited. Against each, BE says whether it has any unsaved changes.
The editor holds a list of 12 'address slide' patterns, and these may be displayed by pressing @M. These are used when the 'power address slide' feature is used. You can set one of the 12 patterns by using the ~F1 to ~F12 keys. To disable one, you specify a new pattern as a empty string.
The editor holds an 'address slide' delta value. Initially this delta value is 4, but it may be changed using the # key. When using #, dot '.' may be used in the numeric expression, and its current value is the current delta value. This delta value is used by the manual 'address slide' feature using the < and > keys, and also the 'power address slide' feature.
If you press ?, BE will prompt for an numeric expression, which it
will then evaluate.
You can then choose to see the result in binary, octal, decimal, hex or
symbolic forms, signed or unsigned.
It will set the variable _last to the result of the evaluation,
so you can refer to it in future expressions.
$ is similar, except it will prompt for a variable name first. It will set the variable to the result of evaluating the expression. If the variable is already set, its value is changed. If the expression is empty, the variable is unset.
When you use the ^L key, you are prompted for a count and a keystroke. BE presses the keystroke on the current line, and then steps down a line. It does this once for each of the count of lines you specified. The count value can be 0 or blank, meaning upto the end of the list on display. This keypress, step down and repeat loop, will stop if the keypress is not 'understood' by the line it is pressed on. This means that only keypresses which operate on a given line are sensible for using with ^L. It will also stop if the end of the list is reached.
^K toggles the keep-going-on-error flag. This flag is initially false, causing ^L to stop if a line doesn't understand the keystroke. However, when true, ^L simply advances to the next line.
@G can be used to go to the Nth line on display. 0 means the first line, a blank line number, or a very large number means the very last line.
Normally BE will only show at most 4096 lines of data, ie: elements of an array or elements of a linked-list. ^ can be used to change this number to anywhere in the range 256 to 65536. Use with caution, BE can get much slower when dealing with longer lists. Building longer lists takes 'order length squared' time. This is why BE starts with such a conservative list length limit.
In addition, normally BE only allows expansion of nested fields to 8
levels, using the + key and open keyword.
The % key can be used to change this number to anywhere between 1
and 64.
Use with caution, BE can get excruiatingly slow when dealing with very
deep expansions.
Doing deeper expansions can result in exponentially longer display times.
This is why BE starts with such a conservative depth expansion limit.
^U and ^V can be used to cycle the memory sections around one way or the other. When you have multiple files/memory sections covering the same address range, this controls which one a memory reference will hit first.
At any given time you may be displaying some data from some start address, as indicated on the title at the top of the screen.
The . key can be used to change the current address, and the , key can be used to add to the current address.
The editor provides a feature known as 'address sliding'.
You can use the ( and ) keys to step (slide) the address backwards or forwards by 1.
You can also use the < and > keys to step (slide) the address backwards or forwards by a particular delta (as setup by the # key, described above).
The 'power address slide' feature is the combination of regular 'address sliding' with a pattern match capability. You set up the power address slide patterns and then press [ or ] (for a backwards or forwards search). You then state whether one, all, or all-in-order of the patterns must match, and how to refresh the screen as the search proceeds. You're also prompted for an address to stop at. BE then slides through memory, checking to see whether the patterns can be matched with the screen, and if so it stops.
A 'power address slide' may be interrupted via Ctrl+Break (OS/2, Windows or DOS), or Esc (elsewhere).
There are a few main uses of address sliding :-
DD
definition in the default initialisation file.
You set the delta value to be a page worth of data, and then use
the < and > keys to page up and down.
The justification for the default delta of 4 is that many structures within processor memory spaces or within files are 4 byte aligned.
The @ command described earlier works a little better when you are viewing data, because a dot used in the numeric address expression is taken to mean the current address (as shown on the title).
Similarly, the C command described earlier works a little better when you are viewing data, because a dot used in the numeric address expression is taken to mean the current address (as shown on the title).
Often you may find yourself looking at a definition that is actually a member of a larger definition. If you know the offset of the smaller definiton in the larger definition, you can subtract this from the current address and display the larger parent definition. This can be awkward, so the @P key will pop-up a list of all possible parent definitions, with an entry for every time the smaller definition appears in another definition.
g/l is displayed if you are allowed to change the memory interpretation mode to big or little endian.
s/u is displayed if you are allowed to change the signed display mode to signed or unsigned.
A subset of the keys a/e/b/o/d/h/k/y/m may be displayed if you are allowed to change the viewing mode to ASCII, EBCDIC, binary, octal, decimal, hex, decode seconds since epoch, symbolic or via a mapping table.
z is displayed if you are allowed to toggle the 'stop displaying when a nul terminator is found' attribute.
The t will decode the current field as if it were raw ASCII text, and will break it up into lines upon CR, LF, CR-LF pair, or NUL boundarys. The new line-by-line list pops-up on top the current list.
If the datum is a code address (marked with the code
attribute in the initialisation file), then c can disassemble
the code at that address.
+/- is displayed to indicate that the level of detail of display may be increased or decreased. Level 0 means display the data type only. Level 1 means display the first level of data. Levels 2 and above mean display additional levels of detail.
Increasing the level of display can make BE open up an array,
and enumerate the elements.
eg: 3 n32 to [123,123,456].
Increasing the level of display can also make BE open up a
definition, and display the fields.
eg: VAR to {"name",123}.
This is capable of opening up the datastructure pointed to by a pointer, providing the pointer may be fetched and followed.
Some examples :-
| level 0 (=type) | level 1 | level 2 | level 3 |
|---|---|---|---|
n32 |
7 |
7 |
7 |
3 n32 |
3 n32 |
[8,9,10] |
[8,9,10] |
VAR |
VAR |
{"a",1} |
{"a",1} |
2 VAR |
2 VAR |
[VAR,VAR] |
[{"b",2},{"c",3}] |
n16 ptr VAR |
22->VAR |
22->{"d",4} |
22->{"d",4} |
2 n8 ptr VAR |
2 n8 ptr VAR |
[33->VAR,44->VAR] |
[33->{"e",5},44->{"f",6}] |
Enter is displayed if you can press enter to either show the contents of the sub-definition, or to follow a pointer and show the definition there. This results in a new list of fields or array elements being popped-up. The Esc key brings you back to where you are now.
There is a shorthand of the above @ command.
If you are on a numeric field, and you know this is an absolute pointer
to a structure definition,
you can use the follow pointer key *.
BE will then prompt for the definition name.
This shortcut ignores any pointer information that may be deduce-able
from the value on display, so even if you are looking at a relative
pointer which is aligned, BE will decode a definition at an absolute
address.
Another handy command is P. If you press this when on a numeric field, it allows you set or change what datatype the value points to. This is great for when you've forgot to put something in the BE initialisation file.
The editor provides the @L key, which makes the job of following long linked lists especially easy. If you looking at the members of a definition, and are on a member which is in fact a pointer to the same type of definition, then you can use the @L (show list) key. You will be presented with the elements in the linked list (at least the first 4096 by default), and at the end the reason the link following ended. This reason can be that there are too many to show at once, 'can't fetch value', 'can't follow null pointer', or the list has 'looped back' to an element shown earlier. If your list is really long, you can always go to the last linked list element on display, select it, and then use the @L key again to get the next 4096 elements!
The = key may be used to edit the current field on display.
If the current field is a numeric value, then you can type a new expression, according to the rules for numbers and expressions used when parsing the initialisation file. Dot '.' evaluates to the fields current numeric value. Examples include :-
1 1+2 addr "symbol" sizeof RGBTRIPLE map FF_ "FF_Split" | 0x20
If the current field is displayed via a mapping table, then the M key can be used to bring up a list of the maplets, and whether each of them can be decoded from the numeric value. The current fields value can be edited from this new list. Esc quits the maplet list.
If the current field is a buffer, then either ASCII data or raw hex bytes may be supplied :-
"a string within quotes" @1234FF00
If the zterm attribute is applicable to the current field,
then after the data is stored, a NUL terminator is appended.
The @S key toggles the suppress attribute of the current datum. This affects how the current structure shall be displayed, when displayed in short. The @N key unconditionally sets the suppress attribute of the current datum. Only non-suppressed fields are shown in the one line summary.
The v key can be used to disable (or re-enable) a fields validity check. Validity checks can act as a form of 'suppression' when viewing definitions 'one to a line'. This keystroke can help cancel that effect (if desired). The V key allows you to set/change the validity check on a field.
w can be used to set the field width. Normally fields are shown is as many characters as are necessary. This corresponds to a field width value of 0. When non-0, fields are padded or truncated to the indicated width.
Del and Ins can be used to copy and paste between the current datum and a memory clipboard or file. To use the memory clipboard, simply specify a blank filename when prompted. Only smallish blocks of data (<=4MB) can be copied or pasted. The amount of data transferred is always the minimum of the datum size, the clipboard size and 4MB.
The external edit key, E, works by prompting you for an
editor command.
It then saves away the current datum into a temporary file and invokes
the editor on it.
Afterwards, the file contents are re-read.
At most 4MB can be processed in this way.
This might be useful if a file contained a chunk of free-flow text, and
you wished to perform some complicated editing on it, involving inserting
and deleting - you could externally edit that chunk using a text editor.
Or, sometimes when editing binary data, you might like to see it in a
typical hex dump and edit raw hex - you can externally edit with a
normal hex editor.
This command doesn't work if BE is running in restricted mode,
ie: has been invoked with the -r command line argument.
Z will zero the current datum. Only datums of 4MB or smaller can be zeroed.
Each possible maplet in the mapping is displayed in the list. Each maplet has a mask and value, and the maplet is deemed to match if :-
value & maplet.mask = maplet.value
In this case a 1 is displayed next to it, otherwise
a 0 is shown.
If you press 0 then the value is anded with the complement of the mask.
If you press 1 then the value is anded with the complement of the mask, and then the value is or-ed in.
Although this may seem strange, the net effect is that when maps are being used for enumerations, 1 will change the value from whatever it was before to the new desired value.
When the mapping is used for decoding bitfields, 1 will turn on a bit and 0 will turn it off.
Examples of enumeration and bitfield style mappings :-
map ENUMERATION
{
"first value" 1
"second value" 2
"third value" 3
}
map BITFIELD
{
"lowest bit" 0x01 : 0x01
"next bit" 0x02 : 0x02
"high bit" 0x80 : 0x80
}
The @S and @N keys toggle or set the maplet suppress attribute. Suppressed maplets are ignored when converting numbers to textual display.
If the current line of code references another routine or code code address, c can be used to pop up another list of the referenced routine.
Similarly, if data is referenced, and the address is easily determinable by the disassembler, the * can be used to follow a pointer and display a structure at that address.
W can be used to write back any unsaved changes on the current memory section. This isn't normally necessary, as when you leave BE using q or @X, you are prompted as to whether you wish to save any unsaved changes on a memory section by memory section basis.
o can be used to pass an user supplied option string to the memory extension peice of code providing the memory section. The memory extension is given the memory section instance and the option string. It can parse the option string in any way it sees fit. If there is a syntax error, or other problem, it can fail the options command with an error message to say why. If a memory section is provided from a file, this command will fail (files have no options). This user-exit mechanism might be used to allow you to tell a memory extension to change how much caching it can do.
These are shown in the list brought up by the @M key, as described earlier.
It is a list of 12 entries, each of which may be disabled, a pattern or an Extended Regular Expression.
You can set one of the entries using the = key. This is the same as using ~F1 to ~F12.