Background

Sometimes you have a binary file (such as an executable), and you want to figure out what's in the file, but there's no convenient way to view it. One way to view binary files is using a hex dump utility.

In a sense, all files are "binary". Files still store information as bytes. However, in ASCII files, those bytes were probably created using a text editor, and can be read using a text editor or some UNIX utility like more or less. Viewing an executable doesn't display well in a text editor.

A hex dump utility displays each byte as a two hexadecimal digit value. It usually gives you some idea of how many bytes have been displayed as well.

The class cluster already has a hex dump utility called "xxd". To try it, type:

xxd -g 1 <filename>

where <filename> can be any file.

Specifications

Write a program that will display the contents of a file using hex digits.

Here are the specifications:

The program may take the following command line switches.

• -p This prints out a "plain" result. That means 16 hex pairs per line (unless otherwise specified---16 is the default value). There is no argument to this switch. Here's an example:

  00 00 00 00 00 00 01 00 2E 64 79 6E 73 79 6D 00
  00 00 00 00 00 00 04 00 2E 72 65 6C 2E 64 79 6E
  
  Total bytes: 32
  

• -a This prints out the addresses on the left, and prints 16 hex pairs per line (by default). The address on the left is 7 hex digits, and increments by 16 (in hex).

  0000000: 83 01 10 00 AB 47 F0 35 00 40 00 00 00 00 00 00
  0000010: 90 00 00 00 50 00 07 30 0B 01 0B 03 0A 00 00 00
  
  Total bytes: 32
  

  You should print the addresses to 7 hex digits. You can assume that the total number of bytes in a file will never exceed FFFFFFF (which is the largest 7 digit hex calue).

• If neither -p nor -a are present, then print addresses and ASCII. This is the default behavior of "xxd", the hexdump on the class cluster. We will call this the STANDARD OPTION.

  If you run "xxd", you will see that, on the side, there are characters that are printed out.

  0000060: 80 80 00 40 01 00 00 00 2e 64 79 6e 61 6d 69 63  ...@.....dynamic
  0000070: 70 04 00 20 01 00 00 00 70 04 00 20 01 00 00 00  p.. ....p.. ....
  

  There are 16 characters at the end of each line. Each character matches up with the byte on that line. If the byte has an ASCII code for a non-printable character (or is something like newline or tab), it's printed as a dot. If the ASCII code for the byte is a digit, a letter, or printable symbols like $, %, ^, etc., then the character associated with the ASCII code is printed. For example, if a byte had the value 61 (in hex), this would print out as lowercase 'a' (since the ASCII code for 'a' is 61, in hex).

  If the ASCII code for a blank space appears, print a blank space on the right (there's an example of that above).

  This feature is useful to recognize any ASCII text that might appear in a binary file. Many times, a binary file contains quite a few printable ASCII characters, and it's useful to see it that way, in addition to hex values. In the example above, you see the word "dynamic" in the binary file. Other times (as in 'p' shown above), the byte value just happens to coincide with the ASCII code for a letter, though it is typically just coincidence that it prints a letter.

• -i <filename> This takes input from the file name <filename>. You may assume the file exists in the directory, though you can print the following error if it doesn't.

  hexdump error: File <filename> does not exist
  

  where <filename> is replaced by the name of the actual file.

  If this option does NOT exist, assume that the input file comes in via input redirection. BE ABLE TO HANDLE INPUT REDIRECTION, as this shall be the main way we test your code!

• -o <filename> If this output exists, it should write the output to this file. If the filename does NOT contain a .dump extension, then add a .dump extension. For example, if the user specifies -o foo, the output file should be foo.dump. However, if the user specifies -o foo.dump, the output file should still be foo.dump, not foo.dump.dump.

  If there is no -o option, then assume the output is sent to STANDARD OUTPUT. In general, we will test WITHOUT the -o option except in a limited number of test cases.

  Unknown extensions should be ignored (as if they don't exist).

Some more information

• You should print up to 16 hex pairs on each line, separated by a space. Here's an example:

  00 00 00 00 00 00 01 00 2E 64 79 6E 73 79 6D 00
  00 00 00 00 00 00 04 00 2E 72 65 6C 2E 64 79 6E
  

  You should print letters 'A'...'F' in uppercase, should they appear.

• If the number of bytes is not divisible by 16, then the last line should contain only the bytes within the file. For example:

  00 00 00 00 00 00 01 00 2E 64 79 6E 73 79 6D 00
  2E 72 65 6C 2E 64 79 6E
  

  Only the last line may contain fewer than 16 entries (and it should, provided the number of bytes is not evenly divisible by 16).

• After the last line, print a blank line, and then the total number of bytes (in base 10).

  00 00 00 00 00 00 01 00 2E 64 79 6E 73 79 6D 00
  2E 72 65 6C 2E 64 79 6E
  
  Total bytes: 24
  

Write a standalone function with the following prototype:

void byteToHex( char byte, char * hexArray ) ;

This prototype should appear in a header file called byteToHex.h.

Although this is a C-like function, it can still be implemented using a C++ compiler.

The implementation of this function should appear in a file called byteToHex.c (if you implement it in C), or byteToHex.cpp (if you implement it in C++). Be very careful how you name the file. Naming it incorrectly may cause you to lose points.

In the implementation, you can assume that you will passed a character, and an array of at least 3 elements (in the parameter hexArray).

The implementation should fill out the information so that hexArray[0] contains the high byte (most significant byte) written as a ASCII character representing the hex digit, and hexArray[1] contains the low byte.

For example, suppose you determine that the byte contains 1E. Then, hexArray[0] = '1' and hexArray[1] = 'E'. hexArray[2] = '\0', which is the NULL character. This makes hexArray store a valid C string.

You MUST use byteToHex in your code to do the conversion.

Note: a character is 8 bits, thus the function must determine the high 4 bits and the low 4 bits and convert it to hexadecimal (as a character).

You should write a file called hexdump.c or hexdump.cpp. This should contain main(). In this file, you should call byteToHex to do your conversion.

You should have a makefile. If the following is typed

make

an executable called "hexdump" should be created that behaves as described in the earlier parts of the specifications.

The executable must be NAMED exactly "hexdump" (not "hexDump", "HEXDUMP", "xxd", "myHedDump"), all in lowercase (without the double quotes);

Here are some restrictions and assumptions you can make.

• If you wish to add additional functions/classes, add them in two additional files: hexdumpHelp.h and hexdumpHelp.cpp.
• Do not add additional functions/classes to byteToHex.h or byteToHex.cpp. There's only one function header and one function in the two files, respectively.
• You can also add helper functions in hexdump.c or hexdump.cpp. Prototypes for the functions should be placed at the top of the file. If you want to use classes, they should appear in hexdumpHelp.h and hexdumpHelp.cpp. You can use more than one class, if you want.
• This part of the project is worth 80 points. You can earn up to 40 more points in extra credit (for a total of 120 points).
• This part of the project should be implemented in C or C++.

Extra Credit/Extensions

This is extra credit. You get no extra credit if your hexdump can't print addresses on the left and ASCII tranlations on the right (see STANDARD OPTION described above).

• Allow the user to type in a command line switch, as in:

  hexdump -w <num> -i <filename> 
  

  You should allow the user to type in -w followed by a space, followed by a positive number, which will determine how many hex pairs are printed per row (the default value is 16). You must update the addresses correctly to compensate for the number of hex pairs per row.

  This command line switch can appear before or after the filename (if the filename exists).

  This will be worth about 15 points extra credit (out of 100).

  In order to receive credit for this, you must print out the addresses and the text information on the right (i.e., standard OPTION).

  Here is an example, where -w 7 is used (7 hex pairs per line.

  0000000: 11 11 11 11 11 11 11  .......
  0000007: 11 11 11 11 11 11 11  .......
  000000E: 11 11 08 08 08 08 08  .......
  0000015: 08 08 08 08 08 08 08  .......
  000001C: 08 08 08 08 48 65 6C  ....Hel
  0000023: 6C 6F 20 57 6F 72 6C  lo Worl
  000002A: 64 0A                 d.
  
  Total bytes: 44
  

  In particular, notice the addresses on the left increase by 7 (in hexadecimal).

• Write the program in C. The makefile should use cc to compile the code. No C++ constructs should be used.

  This will be worth 10 points.

• Add an option, -W, that will allow you to read in hex pairs stored in an input file, via input redirection.

  hexdump -W < <filename> 
  

  A typical input file would look like:

  00 00 00 00 00 00 01 00 2E 64 79 6E 73 79 6D 00
  00 00 00 00 00 00 04 00 2E 72 65 6C 2E 64 79 6E
  

  You may only assume the hex pairs are separated by one or more blank spaces or newlines. You MAY NOT assume that there are exactly sixteen hex pairs per line. There may be any number of hex pairs per line (including 0).

  Basically, with this -W option, your program will output a byte for each hex pair. Each byte will have the binary pattern given by the hex pair. Thus, if the hex pair is 2E, your program will output a byte 0010 1110 (which is output as a single char).

  This output can be output redirected to a result file.

  If you run hexdump -p -i <filename> on the result file, it will produce a result that mimics the input file.

  00 00 00 00 00 00 01 00 2E 64 79 6E 73 79 6D 00
  00 00 00 00 00 00 04 00 2E 72 65 6C 2E 64 79 6E
  
  Total bytes: 32
  

  In this case, there will be 16 hex pairs per line, because that's what your hexdump program normally does.

  This is basically "hexWrite". It takes an ASCII representation of a file, and generates a binary version of that.

  This will be worth 20 points of extra credit.

  You may assume no other command line options are used when you use -W (thus, no -p, no -i, etc).

• The maximum amount of "extra credit" is 40 points, for the "hexdump" program.

Getting Prepared

While you can do this project without learning how to read from a binary file, I suggest you do so. Find a book on C programming (or C++ programming), go to the index and look up either files or binary files. You may also wish to search on the web. One goal of the project is to learn how to read and write to a binary file (although in this case, you don't have to write to a file).

Also, you need to read about command line arguments. Again, a decent book on C/C++ should provide this information. To get practice with command line arguments, I would suggest writing a very simple C/C++ program which prints out argc (the number of arguments), as well as the contents of the array in argv. Recall that argv stores strings using C-style strings, not using C++-style strings.

You may want to see if C++ or C has built-in printing options for hexadecimal values. However, more than likely, it will do so in lowercase ('a' through 'f'), instead of uppercase.

If this is so, you should convert it to uppercase. Here's a hint to convert it to uppercase: try to figure out how to write the output to a string instead of the screen (hint: try sprintf in C and ostringstream in C++). Once it's in a string, you can convert the character to uppercase (for example, using the toupper() function).

You may advise other students where to look for this information, if you want, but it's strongly suggested that they do the reading on their own. You should not be passing along code to other students. However, you may point them to webpages that exist in the general public domain. You should not provide code on the Web or other means.

Goals

These are the lessons to learn from this part of the project:

• How to handle command line arguments.
• How to read/write binary files.
• How to convert a character to two hex digits (written as C-style strings).
• How to look up documentation in a book or on the Web.
• To refresh yourself in C, should you do this in C.

As you learn new things, it's best to test them out in a small setting. For example, rather than get command line arguments to work in the context of a project, write a simple program that prints out the command line arguments so you see it in action.

Furthermore, try to learn the material you read as well as you can. I realize all you need to do is look it up enough to get it done, but by learning to play with other features, even though the project doesn't require it, you'll learn it much better, and hopefully recall it in the future.

You may consult other students about the features in the C/C++ language, but you should not be showing your code to other students nor should they be showing it to you. The goal is to learn, NOT to copy from another student, just so you can turn in your project.

See the class syllabus for policies concerning email Last Modified: Fri Feb 14 09:13:38 EST 2003

Web Accessibility