.\" hey, Emacs:   -*- nroff -*-
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
.\" 
.\" Please update the above date whenever this man page is modified.
.\" 
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins (default)
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.TH "BBE" "1" "2006-11-02" "" ""
.SH "NAME"
bbe \- binary block editor
.SH "SYNOPSIS"
.B bbe
.RI [ options ]...

.SH "DESCRIPTION"
\fBbbe\fP is a sed\-like editor for binary files. It performs binary transformations on the blocks of input stream.
.SH "OPTIONS"
\fBbbe\fP accepts the following options:
.TP 
.BR  \-b ", " \-\-block=\fIBLOCK\fP
Block definition. 
.TP 
.BR  \-e ", " \-\-expression=\fICOMMAND\fR
Add the COMMAND to the commands to be executed.
.TP 
.BR  \-f ", " \-\-file=\fIscript\-file\fP
Add the contents of script\-file to commands.
.TP 
.BR  \-o ", " \-\-output=\fIname\fP
Write output to \fIname\fP instead of standard output.
.TP 
.BR  \-s ", " \-\-suppress
Suppress normal output, print only block contents.
.TP 
.BR  \-? ", " \-\-help
List all available options and their meanings.
.TP 
.BR  \-V ", " \-\-version
Show version of program.
.BR 
.PP 
\fIBLOCK\fP can be defined as:
.TP 
N:M
Where \fIN\fR'th byte starts a \fIM\fR bytes long block (first byte is 0).
.TP 
:M
Block length in input stream is \fIM\fR.
.TP 
/start/:M
String \fIstart\fP starts \fIM\fR bytes long block.
.TP 
/start/:/stop/
String \fIstart\fP starts the block and block ends at string \fIstop\fR.
.TP 
/start/:
String \fIstart\fR starts the block and block will end at next occurrence of \fIstart\fR. Only the first \fIstart\fR is included to the block.
.TP 
:/stop/
Block starts at the beginning of input stream (or at the end of previous block) and ends at the next occurrence of \fIstop\fR. String \fIstop\fR will be included to the block.
.PP 
Special value '$' of \fIM\fR means the end of stream. 
.PP 
Default value for block is 0:$, meaning the whole input stream.
.PP 
Both \fIstart\fR and \fIstop\fR strings are included in block. Nonprintable characters can be escaped as
.TP 
\ennn
decimal 
.TP 
\exnn
hexadecimal
.TP 
\e0nnn
octal
.PP 
Character '\e' can be escaped as '\e\e'. Escape codes '\ea','\eb','\et','\en','\ev','\ef','\er' and '\e;' can also be used.
.PP 
Length (\fIN\fR and \fIM\fR) can be defined as a decimal (n), a hexadecimal (xn) or an octal (0n) value.
.SH "COMMAND SYNOPSIS"
\fBbbe\fR has two type of commands: block and byte commands, both are always related to current block. That means that the input stream outside of the blocks remains untouched. 
.SS Block commands
.TP 
D [\fIn\fR]
Delete the \fIn\fR'th block. Without \fIn\fR, all found blocks are deleted from the output stream.
.TP 
I \fIstring\fR
Insert the string \fIstring\fR before the block.
.TP 
A \fIstring\fR
Append the string \fIstring\fR at the end of block.
.TP 
J \fIn\fR
Skip \fIn\fR blocks, before executing commands after this command.
.TP 
L \fIn\fR
Leave all blocks unmodified starting from block number \fIn\fR. Affects only commands after this command.
.TP 
N
Before printing a block, the file name in which the block starts is printed.
.TP 
F \fIf\fR
Before printing a block, the input stream offset at the beginning of the block is printed.
\fIf\fR can be H, D or O for Hexadecimal, Decimal or Octal format of offset.
.TP 
B \fIf\fR
Before printing a block, the block number is printed (first block == 1)
\fIf\fR can be H, D or O for Hexadecimal, Decimal or Octal format of block number.
.TP 
> \fIfile\fR
Before printing a block, the contents of file \fIfile\fR are printed.
.TP 
< \fIfile\fR
After printing a block, the contents of file \fIfile\fR are printed.
.SS Byte commands
\fIn\fR in byte commands is the offset from the beginning of current block (starts from zero).
.TP 
r \fIn\fR \fIstring\fR
Replace bytes starting at position \fIn\fR with string \fIstring\fR.
.TP 
i \fIn\fR \fIstring\fR
Insert \fIstring\fR starting at position \fIn\fR.
.TP 
p \fIformat\fR
The contents of block is printed in format defined by \fIformat\fR. \fIformat\fR
can have any of the formats H, D, O, A and B for Hexadecimal, Decimal, Octal, Ascii and Binary.
.TP 
s/\fIsearch\fR/\fIreplace\fR/
Replace all occurrences of \fIsearch\fR with \fIreplace\fR.
.TP 
y/\fIsource\fR/\fIdest\fR/
Translate bytes in \fIsource\fR to the corresponding bytes in \fIdest\fR. \fISource\fR and \fIdest\fR must be the same length.
.TP 
d \fIn\fR \fIm\fR|*
Delete \fIm\fR bytes starting from the offset \fIn\fR. If * is defined instead of \fIm\fR, then all bytes starting from \fIn\fR are deleted.
.TP 
c \fIfrom\fR \fIto\fR
Convert bytes from format \fIfrom\fR to \fIto\fR. Currently supported formats are: 
.IP 
BCD
Binary coded decimal
.IP 
ASC
Ascii
.TP 
j \fIn\fR
Commands after the j\-command are ignored for first \fIn\fR bytes of the block.
.TP 
l \fIn\fR
Commands after the l\-command are ignored from \fIn\fR'th byte of the block.
.TP 
w \fIfile\fR
Write bytes from the current block to file \fIfile\fR. Commands before w\-command have what will be written. %B or %nB in  \fIfile\fR will be replaced by current block number. n in %nB is field length,
leading zero in n causes the block number to be left padded with zeroes.
.TP 
& \fIc\fR
Performs binary \fBand\fR with \fIc\fR.
.TP 
| \fIc\fR
Performs binary \fBor\fR with \fIc\fR.
.TP 
^ \fIc\fR
Performs binary \fBxor\fR with \fIc\fR.
.TP 
~
Performs binary negation.
.TP 
u \fIn\fR \fIc\fR
All bytes from start of the block to offset \fIn\fR are replaced by \fIc\fR.
.TP 
f \fIn\fR \fIc\fR
All bytes starting from offset \fIn\fR to end of the block are replaced by \fIc\fR.
.TP 
x
Exchange the contents of nibbles (half an octet) of bytes.
.PP 
Nonvisible characters in strings can be escaped same way as in block definition strings. Character '/' in s and y commands can be any visible character.
.PP 
Note that the D, A, I, F, B, c, s, i, y, p, <, > and d commands cause the length of input and output streams to be different.

.SH "EXAMPLES"
.TP 
bbe \-e "s/c:\e\etemp\e\edata1.txt/c:\e\etemp\e\edata2.txt/" file1
all occurrences of "c:\etemp\edata1.txt" in file file1 are changed to "c:\etemp\edata2.txt"
.TP 
bbe \-b 0420:16 \-e "r 4 \ex12\ex4a" file1
Two bytes starting at fifth byte of a 16 byte long block starting at offset 0420 (octal) in file1 are changed to hexadecimal values 12 and 4a.
.TP 
bbe \-b :16 \-e "A \ex0a" file1
Newline is added after every block, block length is 16.

.SH "SEE ALSO"
.BR sed (1).

.SH "AUTHOR"
Timo Savinen <tjsa@iki.fi >