BSRX(1) BSRX(1)
BSRX
bsrx - binary search, replace, and execute.
SYNOPSIS
bsrx [-dEilnvVw] [-e command] [-f command-file] [-F config-program]
[-t idle-timeout] [-D debug-level] [-T tee-file] [-O out-file] [-L log-
file] [-X exit-cmd] [-- {auxiliary command}]
DESCRIPTION
Bsrx can be used to search and modify binary data. In its simplest
form, bsrx can be used as a type of binary sed(1) (but please note that
bsrx is not designed to be a drop-in replacement for sed(1)). Sed(1)
has many complex features which are not replicated in bsrx).
Bsrx uses regex(3) to search for patterns in binary data. Upon a suc-
cessful match, bsrx can be configured to run an optional pipe-command
to use the matched data, to place output from the pipe-command back
into the data, or to simply replace matches with substitute data.
With an auxiliary command to handle network I/O, bsrx can be used as a
bidirectional filter. In this way bsrx can also be used as a frontend
filter for an inetd(8) service.
Bsrx operates by internally expanding each byte into a 4-character
ASCII string representing that byte's hex value (eg. after expansion a
zero-value byte would look like " x00". The ASCII string for "Hello"
would expand to " x48 x65 x6c x6c x6f", etc). Once expanded, the data
can be searched using routines from the regex(3) library. After all
manipulations have been completed and just before being written out for
the final time, the expanded data is translated back to raw data bytes.
OPTIONS
-V Be verbose about operations.
-D debugging_level
Set the debugging level (max: 15). This option implies "-V".
-v Be verbose about data processing.
-d Print debugging messages. This option implies "-v".
-l Use syslog(3) instead of printing to stderr for output resulting
from the verbose ("-v") or debugging ("-d") options.
-n No substitutions. Just search, log and/or execute.
-w Wait. Initially suspend substitutions. Just search, match, log
and/or execute. Substitutions will be enabled by a resume com-
mand.
-t timeout
Set the maximum number of seconds to wait for input from either
the local or the remote side. The default is no timeout (ie.
wait forever).
-e command
A single command. See COMMANDS below for available commands.
-f command_file
A configuration file containing a list of commands. See COM-
MANDS below for available commands. Empty lines and lines
beginning with "#" are ignored.
-F command_program
A configuration program where the output is a list of commands.
For example, this could be the output from a preprocessor like
cpp(1) or m4(1). As in "-f", empty lines and lines beginning
with "#" are ignored.
-T tee_file
Copy expanded but unmodified data to this file.
-O output_file
Copy expanded and modified data to this file.
-E With either "-T" or "-O" options, assume printable text is
EBCDIC .
-L log_file
Write operational and/or error messages to this file.
-X exit_cmd
Command to be run on final exit.
-i Inetd mode. This option implies "-l". Both stdin and stdout
are connected to the client. In this mode, bsrx can act as a
wrapper. Bsrx filters data between the network and the local
server. The local server is a child of bsrx as an auxiliary
program in the same manner as a TCP wrapper (see tcpd(8)).
-- aux_prog aux_arg1 aux_arg2 ...
Launch an auxiliary command to handle bidirectional traffic.
The "--" prevents getopt(3) from processing any further command-
line arguments. The remaining command-line arguments make up
the auxiliary command which is to be launched by bsrx as a child
process (this feature uses execvp(3) so aux_prog does not have
to be a full pathname if the auxiliary program can be expected
to be in the user's PATH). For example, the following two
usages are identical in that they both result in the launch of a
child process to make a TCP connection to "hostname" on "port":
bsrx -- socat STDIO tcp4:hostname:port
bsrx -- nc hostname port
COMMANDS
A bsrx command has the following form:
<cmd> / <reg-exp> / <subst> / <options> [/ <pipe>]
The forward-slash (/) is the traditional field-separation character.
But for flexibility, any character immediately following <cmd> is used
as the field-separation character for the rest of the command.
<cmd> is one of the following single characters:
S Sent. Command applies only to binary data traveling from
the "client" (ie. from the "front").
R Received. Command applies only to binary data traveling
"back" from the "server".
B Both. Command applies to binary data traveling in either
direction.
s Simple. Similar to sed(1). Command applies only to data
traveling from stdin to stdout. Both the <reg-expr> and
<subst> patterns are assumed to be text-only (ie. they
don't include any hex-value representations). Not suit-
able for interactive use. Useful for testing or working
with files.
<options>
can be any of the following:
d print debugging messages during this command.
v be verbose during this command.
n no substitutions during this command.
x stop all processing if pipe exits with 0. data will con-
tinue to be relayed.
Q stop all processing. data will continue to be relayed.
g continue processing after the first match.
r resume making substitutions. this is the counterpart to
"w" and "-w".
w suspend substitutions. continue to match, log and/or
execute.
A convert text strings to, and from, ASCII (this is
default).
E convert text strings to, and from, EBCDIC.
'[' a [',' b ] ']'
set processing bounds. define offset(s) with respect to
the entire stream.
'(' a [',' b ] ')'
set processing bounds. define offset(s) with respect to
the current buffer.
<reg-exp>
is a regex(3) regular expression defining the pattern to be
detected.
<subst>
is the pattern to be substituted in the event of a match.
Unlike sed(1), an ampersand(&) has no special meaning. The
following strings have a special meaning (where "N" is a digit):
\N the string is replaced by the corresponding sub-match
(much like sed(1)). The string "\0" indicates the entire
matched pattern.
|N the string is replaced with the correspondingly numbered
line of output from the <pipe> (described below). sepa-
rate lines will not include a terminating newline. The
string "|0" indicates the entire output of <pipe>,
including any newlines.
<pipe>
is an optional pipe-command to be run in event of a match. The
following strings have a special meaning (where "N" is a digit):
\N same as in <subst> above.
$N as with "\N" but the (sub-)match is translated to text in
accordance with the "A" or "E" option.
#N the string is replaced by the the stream offset of the
corresponding sub-match.
^N the string is replaced by the the buffer offset of the
corresponding sub-match.
For convenience, in both the <reg-expr> and <subst> fields, single
quotes(') can be used to enclose text strings. Such strings are then
expanded internally. This means string contents do not have to be
expanded manually. Note that single-quoting does not apply with the
"s" command: in that case both fields are treated as entirely text-
only.
EXAMPLES
replace all occurrences of "hiho" on stdin with "hello there".
write result to stdout:
bsrx -e 's/hiho/hello there/g'
same as previous example but using the "S" command:
bsrx -e "S/'hiho'/'hello there'/g"
same as previous example but manually expand 'hiho':
bsrx -e "S/ x68 x69 x68 x6f/'hello there'/g"
insert line#1 from pipe with any 'hi' or 'ho':
bsrx -e "S/('hi'|'ho')/'|1hello '/g/echo well,/"
with input "hiho hi ho." the output should be:
well,hello well,hello well,hello well,hello .
telnet to MVS but change the "USERID" prompt string to "Login ":
bsrx -e "R/ x11(( x..){4})'USERID'/ x11\1'Login '/E/" -- socat STDIO tcp4:MVS:23
a regular expression to match 2 or more ASCII alphanumerics:
(( x3[0-9]| x[46][1-9a-f]| x[57][0-9a]){2,})
a regular expression to match 2 or more EBCDIC alphanumerics:
(( x[89cdf][1-9]| x[ae][2-9]| xf0){2,})
SEE ALSO
nc(1), socat(1), cpp(1), m4(1), socketpair(2), exec(3), getopt(3), sys-
log(3), inetd(8), tcpd(8)
HISTORY
Written by Paul Kern <pak {AT} cns.utoronto.ca> to have a configurable
way of modifying tn3270 streams.
CAVEAT
Bsrx should not be considered a drop-in replacement for sed(1). This
is why the name of this program is NOT bsed.
Feb 10 2006 BSRX(1)