.\" -- vax? headers .\" .TH NAME CHAPTER "Origin" "Public Domain" .\" .DA dd month yyyy .\" -- sun choices (4th & 5th args are optional) .\" .TH NAME CHAPTER "Month dd yyyy" "Origin" .\" .TH NAME CHAPTER "Month dd yyyy" "Origin" "Type" .TH BSRX 1 "Feb 10 2006" .SH BSRX bsrx \- binary search, replace, and execute. .SH SYNOPSIS .B 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}] .SH DESCRIPTION .B Bsrx can be used to search and modify binary data. In its simplest form, .B bsrx can be used as a type of binary .I sed(1) (but please note that .B bsrx is not designed to be a drop-in replacement for .I sed(1)). .I Sed(1) has many complex features which are not replicated in .B bsrx). .B Bsrx uses .I regex(3) to search for patterns in binary data. Upon a successful match, .B 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, .B bsrx can be used as a bidirectional filter. In this way .B bsrx can also be used as a frontend filter for an .I inetd(8) service. .B 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 .I 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. .SH OPTIONS .IP -V Be verbose about operations. .IP "-D debugging_level" Set the debugging level (max: 15). This option implies "-V". .IP -v Be verbose about data processing. .IP -d Print debugging messages. This option implies "-v". .IP -l Use .I syslog(3) instead of printing to stderr for output resulting from the verbose ("-v") or debugging ("-d") options. .IP -n No substitutions. Just search, log and/or execute. .IP -w Wait. Initially suspend substitutions. Just search, match, log and/or execute. Substitutions will be enabled by a .I resume command. .IP "-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). .IP "-e command" A single command. See .I COMMANDS below for available commands. .IP "-f command_file" A configuration file containing a list of commands. See .I COMMANDS below for available commands. Empty lines and lines beginning with "#" are ignored. .IP "-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 .I cpp(1) or .I m4(1). As in "-f", empty lines and lines beginning with "#" are ignored. .IP "-T tee_file" Copy expanded but .I unmodified data to this file. .IP "-O output_file" Copy expanded and .I modified data to this file. .IP -E With either "-T" or "-O" options, assume printable text is EBCDIC . .IP "-L log_file" Write operational and/or error messages to this file. .IP "-X exit_cmd" Command to be run on final exit. .IP -i Inetd mode. This option implies "-l". Both stdin and stdout are connected to the client. In this mode, .B bsrx can act as a wrapper. .B Bsrx filters data between the network and the local server. The local server is a child of .B bsrx as an auxiliary program in the same manner as a TCP wrapper (see .I tcpd(8)). .IP "-- aux_prog aux_arg1 aux_arg2 ..." Launch an auxiliary command to handle bidirectional traffic. The "--" prevents .I 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 .B bsrx as a child process (this feature uses .I execvp(3) so .I 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": .RS bsrx -- socat STDIO tcp4:hostname:port .RE .RS bsrx -- nc hostname port .RE .SH COMMANDS A .B bsrx command has the following form: .IP " / / / [/ ]" .PP 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. .IP is one of the following single characters: .RS .IP S Sent. Command applies only to binary data traveling from the "client" (ie. from the "front"). .IP R Received. Command applies only to binary data traveling "back" from the "server". .IP B Both. Command applies to binary data traveling in either direction. .IP s Simple. Similar to .I 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 suitable for interactive use. Useful for testing or working with files. .RE .IP can be any of the following: .RS .IP d print debugging messages during this command. .IP v be verbose during this command. .IP n no substitutions during this command. .IP x stop all processing if pipe exits with 0. data will continue to be relayed. .IP Q stop all processing. data will continue to be relayed. .IP g continue processing after the first match. .IP r resume making substitutions. this is the counterpart to "w" and "-w". .IP w suspend substitutions. continue to match, log and/or execute. .IP A convert text strings to, and from, ASCII (this is default). .IP E convert text strings to, and from, EBCDIC. .IP "'[' a [',' b ] ']'" set processing bounds. define offset(s) with respect to the entire stream. .IP "'(' a [',' b ] ')'" set processing bounds. define offset(s) with respect to the current buffer. .RE .IP is a .I regex(3) regular expression defining the pattern to be detected. .IP is the pattern to be substituted in the event of a match. Unlike .I sed(1), an ampersand(&) has no special meaning. The following strings have a special meaning (where "N" is a digit): .RS .IP "\\\\N" the string is replaced by the corresponding sub-match (much like .I sed(1)). The string "\\0" indicates the entire matched pattern. .IP "|N" the string is replaced with the correspondingly numbered line of output from the (described below). separate lines will not include a terminating newline. The string "|0" indicates the entire output of , including any newlines. .RE .IP "\ \ \ " 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): .RS .IP "\\\\N" same as in above. .IP "$N" as with "\\N" but the (sub-)match is translated to text in accordance with the "A" or "E" option. .IP "#N" the string is replaced by the the stream offset of the corresponding sub-match. .IP "^N" the string is replaced by the the buffer offset of the corresponding sub-match. .RE .PP 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. .SH EXAMPLES .PP replace all occurrences of "hiho" on stdin with "hello there". .br write result to stdout: .RS bsrx -e 's/hiho/hello there/g' .RE .PP same as previous example but using the "S" command: .RS bsrx -e "S/'hiho'/'hello there'/g" .RE .PP same as previous example but manually expand 'hiho': .RS bsrx -e "S/ x68 x69 x68 x6f/'hello there'/g" .RE .PP insert line#1 from pipe with any 'hi' or 'ho': .RS bsrx -e "S/('hi'|'ho')/'|1hello '/g/echo well,/" .RE with input "hiho hi ho." the output should be: .RS well,hello well,hello well,hello well,hello . .RE .PP telnet to MVS but change the "USERID" prompt string to "Login ": .RS bsrx\ -e\ "R/\ x11((\ x..){4})'USERID'/\ x11\\1'Login\ '/E/"\ --\ socat\ STDIO\ tcp4:MVS:23 .RE .PP a regular expression to match 2 or more ASCII alphanumerics: .RS (( x3[0-9]| x[46][1-9a-f]| x[57][0-9a]){2,}) .RE .PP a regular expression to match 2 or more EBCDIC alphanumerics: .RS (( x[89cdf][1-9]| x[ae][2-9]| xf0){2,}) .RE .SH SEE ALSO nc(1), socat(1), cpp(1), m4(1), socketpair(2), exec(3), getopt(3), syslog(3), inetd(8), tcpd(8) .\" .SH DIAGNOSTICS .\" This section appears ONLY if there is something unobvious and important about .\" the diagnostics or the general behavior in case of error. .SH HISTORY .PP Written by Paul Kern to have a configurable way of modifying tn3270 streams. .SH CAVEAT .B Bsrx should not be considered a drop-in replacement for .I sed(1). This is why the name of this program is NOT bsed.