dm fgrep

'dm fgrep' performs a grep-like search operation on block-based disk images. The significant difference between using 'dm fgrep' and the plain 'grep' command is that 'dm fgrep' searches while accounting for the block-based disk geometry and any track/sector links. In other words, 'dm fgrep' will match byte sequences logically across blocks in a link chain even though the sequence might actually be split when viewing the disk image as a single stream of bytes.

Consider a search for "foobar" on a disk image where "foo" appears at the end of 17.0, where "bar" appears at the start of 17.10 (i.e. immediately after the two-byte link), and where 17.0 links to 17.10; 'dm fgrep' will successfully find this string while plain grep would not.

Search Patterns

A byte sequence pattern can be expressed as a tagged serialized hexadecimal string, as implicit PETSCII, or as explicit ASCII.

tagged serialized hexadecimal

By "tagged serialized hexadecimal" we mean simply an ASCII representation of bytes encoded as hexadecimal values that starts with a '$' - see the link above for more details. Depending on the shell, you may be able to escape the '$' with, e.g., a '\' or some other character. As a final resort, the cli option "-h/--pattern-hex" can be used to force dm to interpret the pattern as hex even if it doesn't start with '$'.

dm fgrep "$41,$42,$43" disk.d64  # pattern evaluates to $414243
dm fgrep -h 414243 disk.d64      # pattern evaluates to $414243

implicit PETSCII

By "implicit PETSCII" we mean PETSCII which is implied from interpreting an ASCII representation as though the current CBM case mode is lower/upper. For example:

dm fgrep "abc" disk.d64  # pattern evaluates to $414243
dm fgrep "ABC" disk.d64  # pattern evaluates to $c1c2c3

explicit ASCII

By "explicit ASCII" we mean the pattern is taken literally as an ASCII string, which in the context of CBM containers can be useful for searching GEOS related media, for example.

pattern options

In addition to "-h/--pattern-hex" to declare a serialized hex pattern, you can use "-p/--pattern-petscii" and "-a/--pattern-ascii" to declare that a pattern should be interpreted as PETSCII or ASCII. The default when none of the three pattern declaration options is provided is to check for a leading '$' and interpret as serialized hex if found, or as PETSCII otherwise.

There is nothing inherent in dm that necessitates using quotes around your pattern - space characters in your pattern would obviously require quotes. Depending on the pattern and your command shell, you may need to use quotes when using certain other characters including '$' as already noted above.

Example output

The output format when matches are found mimics output from the unix grep command. Here are some example results from searching a disk image:

> dm fgrep abc disk.d64
disk.d64:1,4     
disk.d64:2,2-2,3 

> dm fgrep "$313233" -b dsk_*.d64 disk.d64
dsk_1.d64:1,1:00
dsk_1.d64:1,3:02
dsk_2.d64:1,3:46
dsk_2.d64:1,3:f8
disk.d64:2,1:f9-2,2

Output format consists of the filename of the OS-native file where a match was located, followed by the track,sector of the match. When a partial match is found at the end of a sector, which is then completed by following a valid chain to the next linked sector, dm will output the match as a pair of track,sector notations as shown in the second match in the first example above (the match spans track 2, sector 2 and track 2, sector 3).

When using the cli option "-b/--byte-offset', the byte offset of the start of the match is included in output. The second set of results shows where the offset is displayed, either after the track,sector notation, or after the first track,sector and before the second.

Several other cli options are available to control output and which are similar to and influenced by unix fgrep; you can see all options with 'dm fgrep --help'.