binsnip Files

README: information about the binsnip utility
---------
PTHOEM LINUX UTILS (c) 2008-2015 Peter Thoemmes
Weinbergstrasse 3a, D-54441 Ockfen/Germany

binsnip is made to snip out chunks from a binary input stream or from a binary
file. It looks after a byte-sequence given by parameter '-seq <sequence>' and
moves the byte-cursor by 'offset' bytes from the beginning of the sequence
('-offs <offset>'). Then it gathers (or removes, in case '-remove' was
specified) the bytes in a BYTE WINDOW of 'length' number of bytes ('-len
<length>') and writes them to stdout. If a new sequence is specified by
'-new_seq <sequence>' binsnip works in REPLACE mode, as shown below.

USAGE:

    $ ./binsnip -seq XX:XX:XX:... [-remove|-new_seq] [OPTIONS]

 GENERAL OPTIONS...

    -?                     help
    -exec <command>        execute <command> immediately

    <filename>             input file to this filter (default: stdin)

    -seq XX:XX:XX:...      byte sequence to look for; the bytes need to be
                            provided as HEX codes XX, but optionally as
                            string: -seq string:ABC...
    -seq_mask MM:MM:MM:... bit mask to just enable dedicated bits of the
                            byte sequence supplied by -seq; the bytes need
                            to be provided as HEX codes MM
                            !The length must be the same as the length of
                            the byte sequence supplied by -seq!

 GATHER MODE (default) and REMOVE MODE (-remove):

    Gather/remove the bytes in the BYTE WINDOW defined by -offs and -len.

    -offs <offset>         BYTE WINDOW offset (default: 0)
    -len <length>          BYTE WINDOW size (default: length of sequence)
    -remove                remove the BYTE WINDOW (default: gather)

    Example:

        +----+----|----+----+----+----+----+----+----+----+----|----+
        | 11 | 22 | ## | ## | ## | 65 | 66 | 34 | 56 | ## | ## | 99 |
        +----+----|----+----+----+----+----+----+----+----+----|----+
                  |<-------------| sequence (-seq 65:66:34:56) |
                  | offset (-offs -3)                          |
                  |<------------------------------------------>|
                                BYTE WINDOW (-len 9)

        Result in GATHER MODE:
            |----+----+----+----+----+----+----+----+----|
            | ## | ## | ## | 65 | 66 | 34 | 56 | ## | ## |
            |----+----+----+----+----+----+----+----+----|

        Result in REMOVE MODE:
            +----+----|----+
            | 11 | 22 | 99 |
            +----+----|----+

 REPLACE MODE (-new_seq):

    Remove the bytes in the BYTE WINDOW defined by -offs and the length
    of the new sequence and replace them by the new sequence.

    -offs <offset>         BYTE WINDOW offset (default: 0)
    -new_seq YY:YY:YY:...  new sequence replacing the BYTE WINDOW; the
                            bytes need to be provided as HEX codes YY, but
                            optionally as string: -new_seq string:ABC...
                            !This parameter disables GATHER and REMOVE mode!
    -regard_mask           just replace the bits masked by -seq_mask

    Example:

        +----+----|----+----+----+----+----+----+----+----+----|----+
        | 11 | 22 | ## | ## | ## | 65 | 66 | 34 | 56 | ## | ## | 99 |
        +----+----|----+----+----+----+----+----+----+----+----|----+
                  |<-------------| sequence (-seq 65:66:34:56) |
                  | offset (-offs -3)                          |
                  |<------------------------------------------>|
                                    BYTE WINDOW
                        (-new_seq 47:65:12:33:44:98:77:55:31 )

        Result:
            +----+----|----+----+----+----+----+----+----+----+----|----+
            | 11 | 22 | 47 | 65 | 12 | 33 | 44 | 98 | 77 | 55 | 31 | 99 |
            +----+----|----+----+----+----+----+----+----+----+----|----+

 EXAMPLES:

  GATHERING 64 bit data words starting with 'HEX 49 6E 70 74':

   $ binsnip infile -seq 49:6E:70:74 -len 8

  REMOVING 'HEX 49 6E 70 74':

   $ binsnip infile -seq 49:6E:70:74 -remove > outfile

  GATHERING the sequence 'HEX 49 6E 70 74' plus the 2 bytes before:

   $ binsnip infile -seq 49:6E:70:74 -offs -2 -len 6 > outfile

  REMOVING the 3 bytes behind the sequence 'HEX 49 6E':

   $ binsnip infile -seq 49:6E -offs +2 -len 3 -remove > outfile

  REPLACING 'HEX 49 6E 70 74' by 'HEX 31 31 31 31':

   $ binsnip infile -seq 49:6E:70:74 -new_seq 31:31:31:31 > outfile

  GATHERING MPEG-2 packets with PID 18 (12h) (TS PID filter in include mode):

   $ ... | binsnip -seq 47:00:12 -seq_mask FF:1F:FF -len 188

  EXCLUDING MPEG-2 packets with PID 18 (12h) (TS PID filter in exclude mode):

   $ ... | binsnip -seq 47:00:12 -seq_mask FF:1F:FF -len 188 -remove

  REPLACING PID 18 in MPEG-2 packets by PID 1800 (708h) (TS PID remapper):

   $ binsnip ts -seq 47:00:12 -seq_mask FF:1F:FF -new_seq 47:07:08 -regard_mask

I wish you a lot of success with this utility,
Peter