BPE(1)BPE(1)NAMEbpe - examine and patch binary files
SYNOPSISbpe [ -abcdeEhkKLmrwxy ] [ -Bext ] [ -ln ] [ -ooffset ]
[ -sn ] file ...
bpe-H
bpe-v
bpe-V
DESCRIPTIONbpe is a simple, screen-oriented editor for searching and editing ordi‐
nary files in either ASCII or hexadecimal modes (directories can be
searched on many systems but not edited). Files are displayed in n-byte
pages (where n is a function of the terminal/window size) in separate
ASCII and hexadecimal windows and it is possible to switch between the
two windows as required.
The size of files that can be edited is not limited by available mem‐
ory.
Command-Line Options
-a align a searched-for string or a selected address at the
first column of each window - the default is for the display
to be aligned on 16-byte boundaries.
-b create a backup file with the default extension .bak - the
filename must be no longer than the maximum number of charac‐
ters allowed for a directory entry less the characters
required for the extension.
The backup file is created automatically in the current
directory with the user's effective UID, with the GID as
specified in creat(2) and with the same modes and modifica‐
tion-time as the original file. If a file of the same name
already exists the user will be given the option of replacing
it. The backup file is created only on the first access of a
given file in the current bpe session.
A backup file will not be created for a file that is opened
in read-only mode or that is not an ordinary file or if a
lockfile-error is detected.
-Bext specify an extension for backup files instead of the default
- apart from restrictions imposed by the file-system, ext can
be no longer than 15 characters. Note that the -b option or
the B command is still required to actually create a backup
file.
-c set the cursor position on entry to an edit mode to the top,
left-hand corner of the appropriate window - by default the
cursor position is set to the first character of a searched-
for ASCII/hex string after a search operation or to the win‐
dow position representing a selected address after a set-cur‐
rent-address operation (the C command can be used to toggle
cursor-positioning on/off).
-d clear the display before accessing each file in the file list
and when toggling between the help screens - by default, bpe
updates only those parts of the display that need to be
changed. However, this can cause problems with some
curses/terminal combinations that leave "old" data in the
display. Using the -d option will overcome the problem (the D
command can be used to toggle display-clear on/off).
-e disable error-bell for command and file errors.
-E disable error-bell in edit modes and during string/address
data-entry.
-h disable highlighting - by default, bpe uses highlighting in
several areas but some curses/terminal combinations have
trouble with mixed highlighted and non-highlighted charac‐
ters, particularly over slow lines. The -h option will solve
the problem although some of the visual convenience of bpe
will be lost (the H command can be used to toggle highlight‐
ing on/off).
-k disable ESC as escape character - by default, ESC (0x1b) is
one of the characters that can be used to exit edit-mode and
to abort string/address/data entry. This can cause timing
problems, particularly over slow lines, with terminals that
use the escape character in the strings sent by the cursor
keys. If the -k option is used, ESC will no longer be inter‐
preted as an escape character. This option is really of sig‐
nificance only if bpe has been compiled with keypad enabled.
-K disable keypad - this option, which is available only if bpe
has been compiled with keypad enabled, can be useful with
some terminals (check the compile-time defaults with the -V
option). The "vi-style" cursor-movement keys remain available
if the -K option is used (see under Editing below).
-ln set the position of the target line after search and set-cur‐
rent-address operations to line n where n is an integer
between 1 and 15 - the default is for the target line to be
positioned at the top of the windows (i.e. n = 1).
-L disable file-locking - by default a lockfile is created for a
file opened in read/write mode and any other attempt to open
the same file for read/write will result in the file being
opened in read-only mode. The -L option disables normal cre‐
ation of the lockfile although it is still created (but
removed as soon as the file is open) as a check for its prior
existence. This option, which is available only if bpe has
been compiled with file-locking enabled, should be used with
caution!
-m disable message-receive - by default the modes of the user's
tty are left unchanged. The -m option will clear group-write
and world-write access. The original modes are restored on
quitting bpe or when exiting to a shell.
-ooffset specify the start-address of the first page of a file that
will be displayed when a file is first accessed instead of
the default of 0x00 - the offset-address, which should be in
the range from 0x01 to EOF inclusive, can be either octal,
decimal or hexadecimal. An octal address should have a lead‐
ing 0 and a hex address should have a leading 0x. If there is
no leading 0 or 0x it is taken to be a decimal address.
The start-address will be set to 0x00 if offset is outside
the legal range for a given file and, in any case, will have
no effect if a file has already been accessed in the current
bpe session.
-r open all files in read-only mode. A file will be opened in
read-only mode automatically regardless of the use of the -r
option if it does not have write access but is otherwise
accessible or if a lockfile exists for that file (see -L
above).
-sn set the number of lines to be scrolled with the + and - com‐
mands to n where n is an integer greater than 1 - the default
is half the size of the editing window (i.e. 8 lines on a
24-line terminal).
-w force bpe to use a 24-line by 80-column display over-riding
any window-size information obtained at run-time (see Window
Size below).
-x do not disable XON-XOFF flow-control. It is disabled by
default, partly to avoid the possibility of an unintended
CTRL-S seeming to "lock" the terminal. However, flow-control
may be needed with slow terminals (particularly on dial-up
lines) but will be available with the -x option only if it is
the default state.
-y disable display of the file-address represented by the cur‐
sor-position during editing and file-address display during
searching (useful on slow systems and, particularly, with
slow terminals - the Y command can be used to toggle address-
display on/off).
A brief explanation of the command-line options will be displayed if
bpe is called with the -H option. The version number and date will be
displayed with the -v option. If the -V option is used the compile-time
defaults will also be listed.
Environment-Variable Options
Any of the command-line options (other than -H, -v and -V) can also be
placed in the environment variable, BPE, to set user-preferred, run-
time defaults and should take the form, for example, BPE=´abcedeEhkKLm‐
rwxyBext lnsnooffset´ where n is an integer, ext is the required exten‐
sion for any backup files and offset is the address at which file-dis‐
play should start (see -o under Command-Line Options for the format).
Note that, if B or o is given, ext or offset respectively must be fol‐
lowed by a space and the entire argument properly-enclosed in quotes if
it is not the last option on the line. The form given is appropriate
for the Bourne and Korn shells.
Any of the BPE options used without a corresponding command-line option
(or vice-versa) will have the effect listed under Command-Line Options.
However, an option given on the command line that is already set in BPE
will have its action reversed.
As an example, BPE=r will put bpe into read-only mode as a run-time
default but the use of the -r command-line option will then enable
read/write mode.
Four exceptions to this general rule are the -Bext, -ooffset, -ln and
-sn command-line options where the strings ext and offset and the val‐
ues for n will be used in place of anything set in BPE.
Buffers
bpe maintains three main buffers - an edit buffer, a last-write buffer
and an original-data buffer. The size of the buffers is determined by
the number of lines in the editing windows but would be 256 bytes for a
"standard" 24 x 80 terminal.
The edit buffer contains the data that is displayed in the editing win‐
dows.
The last-write buffer reflects any changes that have been written to
disk and is updated at each write. It is used to restore the contents
of the edit buffer to the state that obtained before any modifications
were made after the last write. The last-write buffer's contents will
be the same as that of the original-data buffer if no write has taken
place.
The original-data buffer contains the data read from the disk before
any edit session for that page where a page is defined as any editing-
window-sized segment of the file. The current page is that editing-win‐
dow-sized segment contained within the buffers' boundaries.
Note, therefore, that any movement outside the current-page boundaries,
i.e. moving to another page, will change the buffers' boundaries and,
therefore, their contents.
The start-address of the current page is displayed at the top-right-
hand corner of the screen.
bpe also maintains buffers for each file in the argument list. Various
file-attributes are saved when a file is first accessed which speeds-up
operations during any subsequent access in the current bpe session.
The current-page, marker, last-edited-page, last-set-current-address,
last-successfully-searched-for-string and cursor-offset addresses are
also saved for each file making it possible to return to a file with
all previous settings intact - including any highlighting from a search
operation.
Window Size
The window-size is determined at run time. bpe will attempt to use all
of the available lines (unless the -w option has been used) but the
80-column width is fixed. bpe will abort with an error if the win‐
dow/terminal has fewer than 80 columns or if it has fewer lines than
the minimum set at compile-time (this can be checked with the -V
option) or fewer than 24 lines if the -w option has been used.
This version of bpe does not respond to a SIGWINCH, i.e. the display
cannot be resized dynamically.
Edit-Mode Commands
CTRL-E toggle edit-mode - can be used after entering an edit
mode with either the a or h commands.
CTRL-V escape next edit character - allows the entry of non-
printing ASCII characters in ASCII-edit mode and of sin‐
gle ASCII characters in hex-edit mode.
CTRL-R redraw current screen (see below).
CTRL-X set marker [a to z] to address represented by current
cursor-position.
DEL single-character undo - available only for changes that
have not been written to disk.
ESC or CTRL-C exit edit mode and abort data-entry at any prompt in
command-mode (CTRL-D can also be used - it has been
included to maintain "compatibility" with the first ver‐
sions of bpe).
Command-Mode Commands
N move to next file in arg list.
P move to previous file in arg list.
F display/select-from file list.
A add file to list.
E edit new file.
j jump to file number from arg list.
J jump to file name from arg list.
t or # toggle between two-most-recently-accessed files.
T show names of two-most-recently-accessed files on sta‐
tus-line - the name of the current file will be high‐
lighted.
b or g display first page.
e or G display last page.
n or SPACE display next page.
p display previous page.
CTRL-J scroll forward 1 line.
+ scroll forward 8 lines (the number of lines to be
scrolled with the + and - commands can be set with the
-sn option).
CTRL-K scroll back 1 line.
- scroll back 8 lines.
s set current address.
m set marker [a to z] to the current file address.
M set marker [a to z] to specific address.
k clear markers.
X display marker, current-page, last-edit-page, set-
address, string-search and offset addresses. Note that
any legal bpe command can be entered at the address-
screen prompt although user-confirmation is required
before quitting bpe directly from the prompt.
` or ´ goto address represented by marker [a to z]
@ goto last set-current-address
o goto offset address entered on the command line.
x goto start-address of last-edited page.
f or / find ASCII string (from current address)
l locate hex bytes (from current address)
L goto address of last successfully-searched-for string.
a edit in ASCII window.
h edit in hex window.
C toggle cursor-positioning on/off
u undo all changes to the window-buffer that have not been
written to disk.
U undo changes after the window-buffer has been written to
disk - this facility is available only if the current
file address has not been changed.
w write modified window-buffer to disk.
CTRL-E edit last command-mode entry at the file-name, search-
string and address prompts (see under Command Editing
below).
c clear status-line
D toggle display-clear on/off
H toggle highlighting on/off - any highlighting already in
the display will be removed when highlighting is turned
off. Turning highlighting on will restore any highlight‐
ing that would have been in the display had highlighting
not been off or that had been there before highlighting
was turned off with the exception of any string-search
highlighting that had been removed with the r command.
r remove highlighting - any highlighting from a search or
edit will be removed but, in the latter case, the win‐
dow-buffer contents will not be changed. Highlighting
will not be turned-off. This command will have no effect
if highlighting is off.
d display highlighting - restore any highlighting that has
been removed with the r command. The d command can also
be used to restore highlighting to a searched-for-string
that was removed by entering an edit mode as long as
there are no unwritten window-buffer-modifications
present in the display and the string itself has not
been edited. Once again, this command will have no
effect if highlighting is turned-off.
R or CTRL-R redraw current screen - useful for removing mailer mes‐
sages and the like. The CTRL-R form can be used from
within the edit modes and during data entry at any
prompt.
Y toggle address-display on/off
B create a backup of the current file (even if it has been
opened in read-only mode) regardless of whether the -b
command-line option has been used. A backup can be cre‐
ated only of an ordinary file.
W write (part-of) the current file to a new file.
O show status of address-display, cursor-positioning, dis‐
play-clear and highlighting options.
S show file information and window-buffer, file-mod,
backup, lockfile and string-search status.
V show version number.
q quit bpe.
Q unconditional quit.
! shell-escape (no arguments accepted) - runs shell set in
the SHELL environment variable or defaults to /bin/sh if
SHELL is not set. CTRL-Z can also be used to initiate a
shell-escape on systems on which job-control is not
available or has been disabled.
? display help screens - the help screens will, where
appropriate, reflect compile and run-time defaults. As
with the X command, any legal bpe command can be entered
at the help-screen prompts although user-confirmation is
required before quitting bpe directly from help.
Command Editing
Simple line-editing is available when entering string/address data at
an appropriate prompt. CTRL-H (or left-arrow key if keypad is enabled)
will move backwards and CTRL-L (or right-arrow key) will move forwards
through an already-entered string. DEL will delete the single character
before the cursor or at the cursor if at the beginning of the string.
Insert mode is always on and any legal character will be inserted
before the cursor.
Entering CTRL-E will retrieve any string entered previously at that
prompt and make it available for editing. A string for a particular
prompt is carried across from file to file.
A maximum of 63 characters can be entered at any prompt at which com‐
mand editing is available. Data-entry can be aborted by entering ESC,
CTRL-C or CTRL-D.
Selecting Files
Move through the files in the argument list with the N, P, F, j, J and
t commands.
The N and P commands will move to the next and previous files in the
argument list respectively.
The F command will display a numbered list of the files with the name
of the current file highlighted (or marked with square brackets if
highlighting is turned off) - select the required file by number. Enter
the number of the current file or RETURN on its own to continue editing
the current file. Note that the length of the file name (or path name)
in the display is limited to 19 characters - only the last 18 charac‐
ters are displayed, with a leading > to indicate that truncation has
taken place, if the name is longer than the 19-character limit (only
the last 16 are displayed for the current file if highlighting is
turned off). Note, too, that the same truncation from the left is used
when necessary for the file-name display at the top-left of the screen
and, when appropriate, on the status-line.
The j command will prompt for a number from the file list - enter the
number of the current file or RETURN on its own to continue editing the
current file. Use of this command assumes that the user has already
viewed that list and, thus, knows the number. It provides a quick
method of switching between files without having to display the full
list each time. If there are only two files in the list, the j command
will toggle between them.
The J command will prompt for a name from the file list - note that the
only names that can be used are those which were present on the com‐
mand-line when bpe was called or which were added with the A or E com‐
mands. Once again, if there are only two files in the list, the J com‐
mand will toggle between them.
The t or # commands will toggle between the two most-recently-accessed
files from the file list. The names of the two files, with that of the
current file highlighted (or marked with square brackets if highlight‐
ing is turned off), can be shown on the status-line with the T command.
The commands will have no effect until at least two files have been
accessed.
The A or E commands can be used to access files not already in the file
list. Both commands will prompt for a file name and add the name to the
file list. The E command will also change the current file to the new
file. Note that there can be no more than 60 files in the list.
Moving Through a File
Any of the file-position commands can be used to move through a file.
The s command will prompt for a legal address which can be either
octal, decimal or hexadecimal. An octal address should have a leading 0
and a hex address should have a leading 0x. If there is no leading 0 or
0x it is taken to be a decimal address. Note that bpe defines the first
byte of a file as being at address 0x00 which may cause minor confusion
when using addresses given by some other utilities that insist that the
first byte is at 0x01.
Several "shorthand" codes can also be used at the prompt.
A legal marker [a to z] that has already been set to an address can be
entered in response instead of an actual address, a B or E will give
the address of the beginning or the end of the file respectively, a C
will give the start-address of the current page, a G will give the
start-address of the last page, an L will give the address of the last
successfully-search-for string, an O will give the offset address
entered on the command line, an X will give the start-address of the
last-edited page, an S will give the address entered for the last set-
address operation and entering just a RETURN will give the last address
entered at that prompt (this action is duplicated by the @ command).
The last-address string can be retrieved for editing with CTRL-E but
the addresses represented by previously-entered "shorthand" codes are
not available.
A set-current-address operation can be aborted during address-entry (as
can any data-entry at a prompt) by entering ESC, CTRL-C or CTRL-D.
Markers can be used to store addresses to enable rapid movement through
a file.
Set a marker with the m command followed by a valid marker-identifier
[a to z] at the prompt. The selected marker will be set to the start-
address of the current page.
Set a marker to a specific address with the M command followed, as
before, by a valid marker-identifier [a to z] at the marker prompt and
then a legal address or "shorthand" code (see above) at the address
prompt.
A marker can be set from within an edit mode to the address represented
by the current cursor position with CTRL-X
All markers can be cleared with the k command.
Move to the address represented by a marker with the ´ command followed
by a valid marker-identifier [a to z] at the prompt.
Move to the address of the last successfully-searched-for string, be it
hex or ASCII, with the L command (see under Searching). The string will
be highlighted in both windows if it has not been modified since the
search.
Move to the start-address of the last page that was edited with the x
command.
The current-page, marker, last-edited-page, last-set-current-address
and last-successfully-searched-for-string addresses are saved for each
file but are not carried across from file to file.
Editing
Enter edit mode with a for ASCII or h for hex editing.
Unless the -c option has been used, the cursor will be placed at the
start of a searched-for string or at the window-position representing a
selected address. If the -c option has been used or if the editing ses‐
sion does not follow a search or set-current-address operation the cur‐
sor will be placed in the upper, left-hand corner of the appropriate
window.
Use the "vi-style" cursor-movement keys - CTRL-J (down), CTRL-K (up),
CTRL-H (left), CTRL-L (right) and CTRL-^ (home) - to place the cursor
on the byte to be changed (the arrow-keys can also be used if bpe was
appropriately-compiled and there is a valid termcap/terminfo entry).
Enter a printing ASCII character, i.e. from 0x20 to 0x7e (32 to 126)
inclusive, or a two-digit hex value depending on the mode. Prefixing
each character with CTRL-V allows characters outside the printing-ASCII
range to be entered in ASCII-edit mode or single characters to be
entered in hex-edit mode.
Note that non-printing ASCII characters will be represented in the
ASCII window by the . (0x2e) character.
Any changes will be highlighted and will be reflected in both windows.
However, any "changes" that correspond to the last-write buffer con‐
tents will not be highlighted.
Any single ASCII character or hexadecimal digit can be returned to its
former value with DEL (0x7f).
Exit edit mode by with ESC or CTRL-C and write the modified window-buf‐
fer to disk with w.
A warning will be given if an attempt is made to move to another page,
to scroll the display, to edit another file or to quit the program if
the modified edit buffer has not been written to disk. The edit buffer
can be returned to its state after the last write with the u command.
The Q command can be used to quit bpe unconditionally after a user-con‐
firmation check even if buffer-modifications exist that have not been
written to disk.
If the modified edit buffer has been written to disk the changes can
still be undone with the U command if the current file address, i.e.
the current page, has not been changed since the write. Any changes
made to the edit buffer after the last write to disk of that buffer
will also be undone by the U command. Only the page represented by the
edit buffer will be affected - any changes to other pages previously
written to disk will not be undone.
The file-modification time will be restored on exit with the q command
or when moving to another file with any of the file-selection commands
if all changes written to disk have been undone using the U command.
The display can be refreshed to remove any highlighting without alter‐
ing the buffer contents with the r command.
Searching
Search for hex data with the l command and a string of hex digits - a
leading x or 0 or a trailing h is not required but a leading 0 will be
added if an odd number of characters is entered. The search can be
aborted during string-entry by entering ESC, CTRL-C or CTRL-D.
To search again for the same string, enter the l command and press
RETURN - if the starting address has not been adjusted the search will
start one character past the location of the last occurrence found. The
last-searched-for-string can be edited after entering CTRL-E and is
carried across from file to file.
Search for an ASCII string with the f or / command. Enter a string at
the prompt followed by RETURN - once again, the previous pattern is
used if no pattern is specified. Searching is case-sensitive and pro‐
ceeds as with a hex-data search.
Searching is forward from the current file address which remains
unchanged if the string is not found. Search operations do not wrap
around after end-of-file.
Following a successful search, the display is adjusted to put the first
byte of the string in the line at the top of the screen unless the -ln
option has been used.
The string will be highlighted in both windows unless the -h option has
been used. Any highlighting of the searched-for string will be retained
following a partial-screen scroll as long as all of the string is still
in the windows but it will be removed if another search is made. It
will also be removed when entering an edit mode to avoid confusion with
the highlighting of modified data. The S command can be used to check
if any highlighting is the result of a string-search.
It is possible to return to the file-address of the last successfully-
searched-for string (which is saved for each file) with the L command
(see under Moving Through a File).
Backups and Copies
For obvious reasons, it is suggested that a backup copy should be made
before patching any file for which the source is not available. Backups
can be made automatically with the -b command-line option or manually
with the B command (see above).
The current file, or any part of the current file, can also be written
to a new file with the W command.
The user will be prompted for a filename and, as before, previously-
entered strings can be used by entering just RETURN or by entering
CTRL-E for editing. If a file of the same name already exists the user
will be given the option of replacing it, appending to it or quitting.
The user will then be prompted for the current-file addresses for the
segment of the file that is to be written to the new file. Enter a
legal address at each prompt (see under Moving Through a File for the
format). Note that, if the current page is included in the address-
range, any buffer-modifications that have not been written to disk will
not be written to the new file.
The new file will be created with the user's effective UID and GID and
default permissions.
Status
The S command will show the following information on the status-line.
[ordinary file] the file being examined or patched is an ordinary
file.
[directory] the file being examined is a directory - it will
have been opened in read-only mode even if the -r
option has not been used.
[file-error] the file does not exist, it is a zero-byte file,
its permissions do not allow access or it is a spe‐
cial file.
[read/write] the file has been opened for reading and writing
(normal default).
[read-only] the file has been opened in read-only mode because
the -r option has been used or the file is a direc‐
tory or a file-error or lockfile-error has been
detected.
[lockfile] a lockfile has been created for the file being
edited - any attempt by another user to edit the
same file will result in it being opened in read-
only mode.
[nolockfile] no lockfile has been created either because the
file has been opened in read-only mode or because
the -L option has been used.
[lockfile exists] a lockfile for the file being edited has been cre‐
ated by another user - as a result, the file will
have been opened in read-only mode.
[lockfile-error] an error was detected when attempting to create,
read, write-to or delete the lockfile.
[nobackup] no backup file has been created.
[backup] a backup file has been created either by use of the
-b option or the B command.
[backup-error] an error was detected when attempting to create a
backup file.
[nomod] no modifications have been made to the edit buffer
or written to disk.
[buffermod] modifications have been made to the edit buffer
that have not been written to disk.
[filemod] modifications have been written to disk.
[search] any highlighting in the edit windows is the result
of a successful search.
ENVIRONMENT VARIABLESbpe checks the BPE environment variable for any default run-time
options, the SHELL environment variable for the default shell if the
shell escape is used and, of course, the TERM environment variable.
DIAGNOSTICS
Self explanatory. Error messages are highlighted on the status line
unless the -h option has been used - information messages are not high‐
lighted.
Program-termination is not forced on any lseek(2), read(2) or write(2)
error but the user should take any subsequent actions with care. The Q
command will quit the program and avoid further disk accesses apart
from any associated with the file close.
However, program-termination is forced on any close(2) error or on
other than a permission-related error when resetting the file-modifica‐
tion time (if appropriate) and the last error message is retained on
the display.
RETURN VALUEbpe returns 1 on error, otherwise zero.
FILES
/tmp/BPE..filename
SEE ALSOdd(1), dump(1), od(1)AUTHOR
v1.1 written by Andreas Pleschutznig, Teichhofweg 2, 8044 Graz, Austria
(andy@mssx.uucp)
Contributions by maart@cs.vu.nl
v1.2 features added by Bill Davidsen, Box 8 KW-C206, Schenectady, NY
12345
v1.3 features added by andy@mssx.uucp, davidsen@crdos1.uucp and
jon@joblab and integrated by davidsen@crdos1.uucp
v1.[1-3] bug-fixes, v1.4[0-8] and v2.00.nn rewrites/features-added and
man page written by Ralphe Neill (ran@dgs.monash.edu.au)
BUGS
This version of bpe does not respond to a SIGWINCH signal.
The help, marker/address and file-list screens assume a 24-line by
80-column display and are not adjusted if the display has fewer than 24
lines.
The maximum number of characters that can be entered at any prompt
where command editing is allowed is limited to 63.
Initial write-accessibility checks use the access(2) system-call - this
could lead to problems in some circumstances.
The naming convention used for lockfiles could lead to ambiguities with
similarly-named files. The first n - 4 characters of the filename are
used for part of the lockfile name where n is the maximum number of
characters allowed for a filename. The -L option can be used to over‐
come the problem, should it arise, but it should be used with caution
(see under Command-Line Options above).
Lockfile-operation cannot be relied on when editing files under NFS.
Some versions of curses(3X) do not check the TERMCAP or TERMINFO envi‐
ronment variables making it impossible to use "custom" terminal defini‐
tions.
This version of bpe cannot be used with special files.
LOCAL MANUAL November 09 1998 BPE(1)