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: / / / [/ ] The forward-slash (/) is the traditional field-separation character. But for flexibility, any character immediately following is used as the field-separation character for the rest of the command. 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 and 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. 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. is a regex(3) regular expression defining the pattern to be detected. 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 (described below). sepa- rate lines will not include a terminating newline. The string "|0" indicates the entire output of , including any newlines. 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 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 and 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 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)