Programming Assignment 4 (PA4) - myxd Milestone Due: Final Due:

Transcription

1 Programming Assignment 4 (PA4) - myxd Milestone Due: Final Due: Wednesday, March 11:59 pm Wednesday, March 11:59pm Assignment Overview The purpose of this programming assignment is further practice file I/O and command line arguments. In this assignment you are writing a program that will read in a binary file and output to stdout the bytes of the file in either hex, octal, or ASCII values. This will behave similar to the `od` command-line utility. Grading README: 10 points - See README File section Compiling: 5 points - Using our Makefile; no warnings. If what you turn in does not compile with the given Makefile, you will receive 0 points for this assignment. NO EXCEPTIONS! Style: 10 points - See Style Requirements here Correctness: 75 points Milestone (15 points) - To be distributed across the Milestone functions (see below) Make sure you have all files tracked in Git. Extra Credit: 2 points - View Extra Credit section for more information. Wrong Language: You will lose 10 points for each module in the wrong language, C vs. Assembly or vice versa. NOTE: If what you turn in does not compile with given Makefile, you will receive 0 points for this assignment. Getting Started Follow these steps to acquire the starter files and prepare your Git repository. Gathering Starter Files: The first step is to gather all the appropriate files for this assignment. Connect to pi-cluster via ssh. $ ssh cs30xyz@pi-cluster.ucsd.edu Create and enter the pa4 working directory. $ mkdir ~/pa4 $ cd ~/pa4 Copy the starter files from the public directory. $ cp -r ~/../public/pa4starterfiles/* ~/pa4/ Starter files provided: pa4.h test.h pa4strings.h testevaluateargs.c Makefile NOTE: It is your responsibility to read through all the constants defined in pa4.h and pa4strings.h and determine where to use them. If you finish the assignment and you have unused constants in these files, you are probably missing some component of the assignment and/or have magic numbers.

2 Preparing Git Repository: You are required to use Git with this and all future programming assignments. Refer to the PA0 writeup for how to set up your local git repository. Sample Output A sample stripped executable provided for you to try and compare your output against is available in the public directory. Note that you cannot copy it to your own directory; you can only run it using the following command (where you will also pass in the command line arguments): $ ~/../public/pa4test NOTE: 1. If there is a discrepancy between the sample output in this document and the pa4test output, follow the pa4test output. 2. The output of your program MUST match exactly as it appears in the pa4test output. You need to pay attention to everything in the output, from the order of the error messages to the small things like extra newlines at the end (or beginning, or middle, or everywhere)! 3. For this assignment, we are not giving you very in depth example outputs, you are responsible for trying out all of the flags, learning what they do and what error messages are printed. It is important that you fully understand how the program works. The --help flag is your friend. Below are some brief example outputs of this program. This output isn t comprehensive! Make sure you experiment with the public executable to further understand the program behavior (try things like files with no permissions, all the different flags, all the different flag combinations, etc). Bolded text is what you type in the terminal. 1. Command-line Parsing Errors 1.1. Too many arguments (extra operand)../myxd infile extrafile Error: Incorrect number of positional arguments../myxd [-h] [-x -o -c -s] [-l -b] [-r range] [-u outfile] INFILE 1.2. More than one option from -xocs../myxd -x -c infile Error: Only one of -x, -c, -o, -s may be specified../myxd [-h] [-x -o -c -s] [-l -b] [-r range] [-u outfile] INFILE 1.3. Missing required argument to an option../myxd -x infile -r./myxd: option requires an argument -- 'r'./myxd [-h] [-x -o -c -s] [-l -b] [-r range] [-u outfile] INFILE

3 1.4. Range is not in valid format../myxd -x -r 10 infile Error: Incorrect format for range../myxd [-h] [-x -o -c -s] [-l -b] [-r range] [-u outfile] INFILE 2. Other Errors 2.1. The file does not exist../myxd nofile nofile: No such file or directory 2.2. The end value of range is larger than the file size../myxd -r 10:400 smallfile Error: Invalid range. Start and end must be > 0, end > start./myxd [-h] [-x -o -c -s] [-l -b] [-r range] [-u outfile] INFILE 3. Valid Output 3.1. Correct output from a file of size 100 bytes../myxd infile : e213 af76 a72e d3c b966 c098 09bf : fcc e2 df a af35 b : 63b2 999a 1060 bec5 8f6f d865 fb74 e8bb : 6d28 6eff 93d6 526d ed3c 16ad 9e18 62af : cb1b e120 d5a0 9bad c005 90e4 fd66 150d : 6ca1 28ff d3e5 49d1 7c09 6ff4 a3f2 b9ac : f Proper use of undump, first run the program as normal, then run undump on that file../myxd infile > hexout./myxd -u result hexout diff infile result 3.3. Correct output using a range../myxd --range 0x3B:100 infile b: d6c3 2d18 53b5 f402 c9b e8fe 369c b: 14c6 2aeb f52d 3b82 54c be 261f b: 6ba c0 dfc6 ba Detailed Overview The function prototypes for the various C and Assembly functions are as follows.

4 C routines: int main( int argc, char * argv[] ); int evaluateargs( int argc, char * argv[], char ** infile, char ** outfile, char ** rangestr, OutType * type, int * convert ); int parserange( char * rangestr, char * infile, long * start, long * end ); void printbytes( FILE * fp, OutType type, long endaddr, int convertflag ); void printstrings( FILE * fp, long endaddr ); void undump( FILE * infile, FILE * outfile, int convertflag ); Assembly routines: void convertorder( unsigned char * toconvert ); long parselong( char * str, int * errorflag ); For the Milestone, you will need to complete: convertorder.s evaluateargs.c parselong.s parserange.c C Functions to be Written Listed below are the modules to be written in C. main.c int main( int argc, char * argv[] ); This will be the main entry point of your program. It will be responsible for parsing command line arguments, opening all required files, and then calling the appropriate functions. First parse the arguments by calling evaluateargs(). If the help flag was entered, return EXIT_SUCCESS right away. After you have parsed all of the arguments without any error, it is time to start doing some file operations. First, you should open the infile for reading. Next, you need to get the size of the file, just like how you did in PA3. If the range option was entered, call parserange() to get the range information. If it is valid, use fseek() (see man -s3 fseek) to move the file pointer to the starting value the user entered. If the range was not valid, print a short usage and return EXIT_FAILURE. If the range option was not selected, make sure you know what the starting and ending location in the file are going to be. Next, if the user selected the undump option, you need to open the outfile for writing and then call undump(). If the user did not select undump, you need to call either printstrings() or printbytes() depending on the option the user selected. At the end, make sure you close all opened files. Reasons for error: Error in evaluateargs return EXIT_FAILURE right away Error in parserange print out the short usage, and return EXIT_FAILURE right away

5 Error opening file use perror() to print out the appropriate error message and return EXIT_FAILURE right away Return Value: EXIT_SUCCESS during normal execution, EXIT_FAILURE in case of error. evaluateargs.c int evaluateargs( int argc, char * argv[], char ** infile, char ** outfile, char ** rangestr, OutType * type, int * convert ); This function will parse the command line arguments. This will be similar to what you did in PA3, but this time we are using getopt_long() (see man -s3 getopt_long) which allows us to have long options like -- help. Look at the example in the man page for getopt_long(), it will be very helpful. Note that you will have to create an array of struct option, we recommend that this is done outside of any loops (also, as a hint, pass in NULL for all of the flag members of the struct, we are not using this functionality in this program). For the long and short options, make sure you are using the constants defined in pa4.h. Each flag specifies something specific for the program, see the long usage string in pa4strings.h for more information as to what each option does. Several of the parameters to this function (infile, outfile, rangestr, type, and convert) are all pointers so that you can access these variables defined back in main. There are a few errors that can be found while parsing the arguments, you should check for all of these errors, in this exact order to ensure your output matches that of the sample executable. Remember that all error messages should be printed to stderr. While parsing the arguments: 1. If the help flag is given at any point, then you should print the long usage message to stdout and return If you encounter an unknown flag, getopt_long() will automatically print out an error message. You should also print the short usage message to stderr, and return If a flag has a required argument and one is not supplied, getopt_long() will print out the error message for you. You still need to print out short usage to stderr and return There are some flags that are mutually exclusive, so remember to keep track of the flags that are used. After parsing the arguments: 1. Check if the user entered more than one format flag (-xocs), if so, this is an error. Print out the correct error message and return Check if the user entered more than one endian flag (-bl), if so, this is an error. Print out the correct error message and return Now, check if there are any additional arguments. Remember that a filename is a required argument, but this will not be parsed by getopt_long() as it is not a flag. Keep this in mind while performing this check. Reasons for error: An unknown flag is encountered A flag s argument is not supplied More than one format flag is supplied

6 More than one endian flag is supplied Additional arguments are supplied For all of these errors, make sure to print the appropriate error message as described above and return -1. Return Value: -1 if error, 0 if no error, 1 if help flag was entered. parserange.c int parserange( char * rangestr, char * infile, long * start, long * end ); This function will help you parse the range string that was provided as an argument to the -r flag. A valid rangestr is formatted as "start:end" (man -s3 strtok). Convert the values to longs (parselong) and store them in the appropriate output parameters. Make sure you check that the start and end values are both within the range of the size of the file. Get the size of the infile like you did in PA3. Also make sure start and end are >= 0, and start < end. Reasons for error: Range string is not formatted correctly print ERR_RANGE_FMT and return -1 start is not valid (couldn t be converted to a long or the value itself is not a valid starting position) print ERR_RANGE_INV and return -1 end is not valid (couldn t be converted to a long or the value itself is not a valid ending position) print ERR_RANGE_INV and return -1 Return Value: 0 if success, -1 if error. printbytes.c void printbytes( FILE * fp, OutType type, long endaddr, int convertflag ); This function will be responsible for reading data from the file pointer up to (but not including) endaddr bytes into the file, and will output the bytes from the file according to the specified OutType. If convertflag is set (value is non-zero) then this function will change the endianness of the input 4 bytes at a time before printing out the bytes (use convertorder()). Start by determining how many total bytes you are going to read from the file (you should use endaddr and ftell() (see man -s3 ftell) to calculate this). Remember that the starting position in the file was moved in main() if a range was set, so this is why you must use ftell(). After calculating this value, you are going to loop through the file until you have read in the total number of bytes you just calculated. In your loop, you need to first print out the address in the file that we are reading from (for proper formatting, see the sample output for how this should look). However, this only needs to be done when we are either at the first iteration (nothing has been printed yet) or we have printed BYTES_PER_LINE bytes in a single line (if you reach BYTES_PER_LINE bytes printed, you will need to print a newline before the address to properly format the output). Also, notice that this address is printed in hex if the OutType is HEX or ASCII, and octal if OutType is OCTAL (there are strings in pa4strings.h to help you out with printing this properly). Think about how you get the current address in the file (hint: you just did this).

7 Now, read from the file in BYTE_BUFFER_SIZE number of byte increments (for each call to fread() you should only be reading BYTE_BUFFER_SIZE number of bytes). You need to be careful about the case when the number of bytes remaining for you to print is less than BYTE_BUFFER_SIZE. fread() may still return that it read BYTE_BUFFER_SIZE number of bytes, but your "end of file" is determined by endaddr, so you will need to keep track of the number of bytes you have read in total and compare this to the number of bytes you expect to read overall (as calculated earlier). In other words, don't just use the return value from fread() or BYTE_BUFFER_SIZE when printing out, you may need to adjust this value. If convertflag is set, that means you need to call convertorder() to properly change the endianness of the bytes. Otherwise, keep the bytes the way they were read. Note: You ll need to pad the buffer with zeros before calling convertorder() if the number of bytes you ve read in is less than BYTE_BUFFER_SIZE. Finally, it is time to print out the bytes. The way the bytes are printed is determined by OutType. You should print out one byte at a time using the format strings in pa4strings.h. There is one specific case here, if your OutType is ASCII, then you need to check if the character is printable (see man -s3 isprint for some help here). If the character is not printable, then print out the byte in hex. If you have printed out GROUP_SIZE number of bytes, then you need to print a space to properly format the output. If you have not read and printed all of the bytes yet, you will need to repeat this loop again. After everything has been read and printed, print one final newline for formatting reasons. printstrings.c void printstrings( FILE * fp, long endaddr ); This function will print out all valid sequences of characters in the file. A sequence of characters is considered valid if it only consists of printable characters (as determined by isprint()) terminated by a null-character. Like printbytes(), this function will also only read from the file until it reaches endaddr bytes into the file (exclusive). Be careful to not use any bytes past this amount. We will use fread() to read data in blocks of size STR_BUFFER_SIZE bytes. It must be noted that this function should be able to print strings longer than STR_BUFFER_SIZE. This means that strings can stretch across multiple calls to fread(). This will require dynamic memory allocation, more on this later. After reading from the file, you must loop through the bytes in the buffer. Our goal now is to try and construct strings; there are three main cases inside of this loop: 1. If the current byte is a printable character, then save its index as the "starting" index of the string and keep track of the string that is currently being created. 2. If the current byte is not printable and is not a null-character, but you already have a string being created, then reset the string that s currently being created. 3. If the byte is not printable, but is a null-character, and you already have a string being created, then print the string. There are two cases within this: a. The string you need to print out is entirely from within your current buffer (the current call to fread()). Here, you need to allocate enough space for the string using calloc(), then use strncpy() to copy the string into your memory making sure that is it properly null terminated.

8 After this is done, print out the string to stdout, free the memory you allocated and reset your logic so that a string is no longer being created. b. Some portion of your string is coming from a previous buffer which you have currently saved in memory (more on this later). You are going to need to realloc() the current memory to make room for the final string. Then, use strncpy() to copy the string into the memory you just allocated, making sure to not overwrite the previous characters in the string and that it is properly null terminated. Now, print out the string, free the memory you allocated and reset your logic so that a string is no longer being created. At this point, after going through all of the bytes in the buffer, there are two cases: 1. You are not currently building a string, this will come from whatever logic you were using above. If this is the case, you do not need to do anything, just read from the file again if there are more bytes to read. 2. You are currently building a string. In this case you are going to need to allocate memory for the bytes that will contribute to the string, then use strncpy() to copy over the characters that you need from the buffer. There is one thing you need to be careful of here, the currently created string could be coming from a previous buffer (yes, that would be a long string, but it is possible). So, you should be using realloc() to allocate the memory here and like above, making sure you are not overwriting the previous characters. Make sure your logic transfers over to the next iteration that you are building a string, and read from the file again if there are more bytes to read. A few notes for this function: You will need to keep track of multiple indices, be diligent and careful with these, use good variable names so that you really know what index should be used. When you are done with any memory you allocated, be sure to free it. Reasons for error: Memory allocation failed use perror() to print out the error message, free any previously allocated memory, and return from the function immediately undump.c void undump( FILE * infile, FILE * outfile, int convertflag ); This function is responsible for taking a previously created hex dump from our program and converting it back into the original file format. Unlike printstrings() and printbyte(), range is not a valid option, so you will be converting the entire file. You will be relying on fscanf() (see man -s3 fscanf) for reading in the file, with a buffer of BYTE_BUFFER_SIZE. There is a new complication with reading this file now, because the output of our program includes file offsets in addition to the hex data. For each line of the file, you first need to discard the offset. Use fscanf() and STR_SCANF_OFF to accomplish this. Now that you have removed the offset, you will now read in the actual hex data using fscanf() and STR_SCANF. Note that STR_SCANF will only read in two bytes at a time; this is important because BYTE_BUFFER_SIZE is larger than two bytes, thus you will need to call fscanf() more than once to fill your buffer completely. After you have the data in the buffer, if convertflag has been set, you will need to call convertorder() to change the endianness of the bytes.

9 Finally, use fwrite() to write the buffer to the outfile. Complete this process again until you have read all of the infile. Assembly Functions to be Written Listed below are the modules to be written in Assembly. convertorder.s void convertorder( unsigned char * toconvert ); This function will convert the endianness of the byte sequence pointed to by the argument. It can be assumed that the byte sequence that toconvert points to will always be 4 bytes long. To accomplish this, you should swap the first byte (index 0) with the last byte (index 3), and swap the second byte (index 1) with the third byte (index 2). parselong.s long parselong( char * str, int * errorflag ); This function will parse the char * str as a long and set the int that errorflag points to if there is an error. You will use strtol as part of this parsing. Remember that, as part of calling strtol, you will need to make a local variable to act as your endptr. Also as part of calling strtol, you will need to set errno to 0. If you call the function errno_location, you can obtain the address of errno so that you can set it to 0. If there is an error while parsing the long, you should print out ERR_NOT_INT to stderr and set the int that errorflag points to to 1. In order to pass stderr as an argument to fprintf, remember to first load the address of stderr using =stderr and then use that address to load the value of stderr into a register. Remember to return the long that was parsed. Note that you will need to redefine ERR_NOT_INT in this assembly file since it is defined in a.h file (which you can t access from within an assembly file). Reasons for error: Error converting to long print ERR_NOT_INT and set the int that errorflag points to to 1 Return Value: The long value that was parsed from str. Unit Testing You are provided with only one basic unit test file for the Milestone function, testevaluateargs(). This file only has minimal test cases and is only meant to give you an idea of how to write your own unit test files. You must write unit test files for each of the Milestone functions, as well as add several of your own thorough test cases to all of the unit test files. You need to add as many unit tests as necessary to cover all possible use cases of each function. You will lose points if you don t do this! You are responsible for making sure you thoroughly test your functions. Make sure you think about boundary cases, special cases, general cases, extreme limits, error cases, etc. as appropriate for each function. The Makefile includes the rules for compiling these tests. Keep in mind that your unit tests will not build until all required files for that specific unit test have been written. These test files are not being collected for the Milestone and will

10 only be collected for the final turnin (however, they should already be written by the time you turn in the Milestone because you should be using them to test your Milestone functions). Unit tests you need to complete: testconvertorder.c testevaluateargs.c testparselong.c testparserange.c To compile: $ make testevaluateargs To run: $./testevaluateargs (Replace testevaluateargs with the appropriate file names to compile and run the other unit tests) README File Your README file for this and all assignments should contain: High level description of what your program does. How to compile it (be more specific than: just typing make --i.e., what directory should you be in?, where should the source files be?, etc.). How to run it (give an example). An example of normal output and where that normal output goes (stdout or a file or???). An example of abnormal/error output and where that error output goes (stderr usually). How you tested your program (what test values you used to test normal and error states) and showing your tests covered all parts of your code (test coverage). (Be more specific than diff ing your output with the solution output--i.e., what are some specific test cases you tried?, what different types of cases did you test?, etc.) Anything else that you would want/need to communicate with someone who has not read the assignment write-up but may want to compile and run your program. Answers to questions (if there are any). Questions to Answer in the README 1. [Vim] How do you increment the next number under or to the right of the cursor? 2. [Vim] What is the command to turn a lowercase character into an uppercase character and vice versa? 3. [Unix] From the command line, how can you find all instances of the word bar in the file foo.txt, with line numbers? 4. [Vim] What is the command to repeat the previously executed command? 5. [AI] How do you maintain your integrity even when you're stressed, pressured, or tired? Extra Credit There are 2 points total for extra credit on this assignment. Early turnin: [2 Points] 48 hours before regular due date and time [1 Point] 24 hours before regular due date and time (it s one or the other, not both) Milestone Turn-in Instructions Milestone Turn-in - due Wednesday night, March 11:59 pm [15 points of Correctness Section] Before final and complete turnin of your assignment, you are required to turnin several modules for the Milestone check. Each module must pass all of our unit tests in order to receive full credit.

11 Files required for the Milestone: convertorder.s evaluateargs.c parselong.s parserange.c A working Makefile with all the appropriate targets and any required header files must be turned in as well. All Makefile test cases for the milestone functions must compile successfully via the commands make test***. You do not need to turn in your README with the milestone. In order for your files to be graded for the Milestone Check, you must use the milestone specific turnin script. $ ~/../public/bin/cse30_pa4milestone_turnin To verify your turn-in: $ ~/../public/bin/cse30verify pa4milestone Final Turn-in Instructions Final Turn-in - due Wednesday night, March 11:59 pm Once you have checked your output, compiled, executed your code, finished your README file (see above), and double-checked your style, you are ready to turn it in. Use the following names *exactly* otherwise our Makefile will not find your files. Files required for the Final Turn-in: convertorder.s parselong.s evaluateargs.c main.c parserange.c printbytes.c printstrings.c undump.c pa4.h pa4strings.h test.h Makefile testconvertorder.c testevaluateargs.c testparselong.c testparserange.c README How to Turn in an Assignment Before turning in, run make clean and then make to double check for any compiler errors/warnings. Then use the following turnin script from the raspberry pi to submit your full assignment before the due date as follows: $ ~/../public/bin/cse30turnin pa4 To verify your turn-in: $ ~/../public/bin/cse30verify pa4 Up until the due date, you can re-submit your assignment via the scripts above. It is your responsibility to check that your code was turned in successfully using the cse30verify command. If there is an issue turning in your code, you might not get a grade for the assignment! Note, if you turned in the assignment early for extra credit and then turned it in again later (after the extra credit cutoff), you will no longer receive early turn-in credit. Failure to follow the procedures outlined here will result in your assignment not being collected properly and will result in a loss of points. Late assignments WILL NOT be accepted. If there is anything in these procedures which needs clarifying, please feel free to ask any tutor, the instructor, or post on the Piazza Discussion Board.