From hexdump to gridhexdump in three easy steps!

The program hexdump is useful for those aberrant Unix hacks who find pleasure in dipping their ladle into the binary representation of various files. In its most common usage scenario this program takes a file, specified on the command line, and displays, in a human readable form, the binary data contained within the so specified file.

For example, if I have a file called /usr/home/example which contains only the text

Hello, cruel world!

then the command

% hexdump /usr/home/example

will print out

0000000 4865 6c6c 6f2c 2063 7275 656c 2077 6f72
0000010 6c64 210a                              
0000014

Looks like a mess you say; well it is human readable, you just need to know the secret handshake.

The default format that hexdump displays this binary data in is called the ``two-byte hexadecimal display'' and is what you see above. From the manual for hexdump it ``displas the input offset in hexadecimal, followed by eight, space separated, four column, zero-filled, two-byte quantities of input data, in hexadecimal, per line.'' So the first number 0000000 of the line

0000000 4865 6c6c 6f2c 2063 7275 656c 2077 6f72

indicates that the byte offset of the hexadecimal number 4865 from the beginning of the file is 0000000 bytes. Similarly, the line

0000010 6c64 210a

indicates that the byte offset of the hexadecimal number 6c64 from the beginning of the file is 0000010 bytes, remember this number is in hexadecimal, its 16 in binary.

So, for example, in looking at the original text in /usr/home/example

Hello, cruel world!

along with the output of our hexdump call

0000000 4865 6c6c 6f2c 2063 7275 656c 2077 6f72
0000010 6c64 210a                              
0000014

we can see that the hexadecimal character code for `H' is , the hexadecimal character code for `e' is , the hexadecimal character code for `l' is , ...The final number

0000014

is the total number of bytes in the file. See, after you learn the secret handshake it's not really all that hard.

Now lets move on to make a ``grid enabled'' version of hexdump. The full code for a program which does the trick is as follows

#include <stdio.h>
#include "GAT.h"

int main( int argc, char *argv[] )
{
  int counter;
  char buffer[16];
  GATuint32 offset;
  GATContext context;
  GATuint32 readBytes;  
  GATLocation location;
  GATFileStream fileStream;
  GATObject fileStreamObject;
  
  /* Check command line syntax */
  if( 2 != argc )
  {
     printf("usage: %s file\n", argv[0]);
     
     return 1;
  }
  
  /* Set result to a memory failure */
  result = GAT_MEMORYFAILURE;
  
  /* Create a GATLocation location */
  location = GATLocation_Create( argv[1] );
  
  /* Check GATLocation creation */
  if( NULL != location )
  {
    /* Create GATContext context */
    context = GATContext_Create();
    
    /* Check GATContext creation */
    if( NULL != context )
    {
      /* Create GATFileStream fileStream */
      fileStream  = GATFileStream_Create( context, 
                                          NULL, 
                                          location, 
                                          GATFileStreamMode_Read );
      
      /* Check GATFileStream creation */
      if( NULL != fileStream )
      {
        /* Set offset */
        offset = 0;
        
        /* Cast GATFileStream to GATObject */
        fileStreamObject = GATFileStream_ToGATObject( fileStream );
        
        /* Read in 16 bytes */
        result =GATStreamable( fileStreamObject, (void *) buffer, 16, &readBytes );
        
        /* Loop until a read failure */
        while( GAT_SUCCEEDED( result ) )
        {
          /* Print out offset */
          printf( "%07x ", offset );
          
          /* Print out data */
          for( count = 0; count < readBytes; count++ )
          {
            printf( "%02x", buffer[count] );
            
            if( 0 == ( (count + 1) % 2 ) )
            {
              printf(" ");
            }
          }
          
          /* Print newline character */
          printf( "\n" );
          
          /* Set offset */
          offset = offset + readBytes;
                    
          /* Read in 16 bytes */
          result =GATStreamable( fileStreamObject, (void *) buffer, 16, &readBytes );
        }
        
        /* Destroy GATFileStream */
        GATFileStream_Destroy( &fileStream );
      }
      
      /* Destroy GATContext */
      GATContext_Destroy( &context );
    }
    
    /* Print the total number of bytes */
    if( 0 != offset )
    {
      printf( "%07x\n", offset );
    }
  
    /* Destroy GATLocation */
    GATLocation_Destroy( &location );
  }
  
  /* Check result for success and print error */
  if( GAT_FAILED( result) )
  {
    printf( "An error has occurred\n");
    
    return 1;
  }
    
  return 0;
}

As we have reviewed all the various functions in this program previously, we will not belabor the point by reviewing them again here.