CSSE2310/CSSE7231 — Semester 1, 2023 Assignment 3

Introduction

The goal of this assignment is to demonstrate your skills and ability in fundamental process management and

communication concepts, and to further develop your C programming skills with a moderately complex program.

You are to create a program called testuqwordiply that creates and manages communicating collections of processes that test a uqwordiply program (from assignment one) according to a job specification file that lists tests to be run.  For various test cases, your program will run both a test version of uqwordiply and the assignment one solution (available as demo-uqwordiply) and compare their standard outputs, standard errors and exit statuses and report the results.  You will be provided with (and must use) a program named uqcmp that will compare the input arriving on two file descriptors. The assignment will also test your ability to code to a programming style guide and to use a revision control system appropriately.

CSSE7231 students will, in addition, write their own version of uqcmp.

Student Conduct

This is an individual assignment. You should feel free to discuss general aspects of C programming and the assignment specification with fellow students, including on the discussion forum. In general, questions like “How should the program behave if (this happens)?”  would be safe, if they are seeking clarification on the specification.

You must not actively help (or seek help from) other students or other people with the actual design, structure and/or coding of your assignment solution. It is cheating to look at another student’s assignment code and it is cheating to allow your code to be seen or shared in printed or electronic form by others . All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if you share your code with a friend, even inadvertently, then both of you are in trouble.  Do not post your code to a public place such as the course discussion forum or a public code repository.  (Code in private posts to the discussion forum is permitted.) You must assume that some students in the course may have very long extensions so do not post your code to any public repository until at least three months after the result release date for the course (or check with the course coordinator if you wish to post it sooner). Do not allow others to access your computer – you must keep your code secure. Never leave your work unattended.

You must follow the following code referencing rules for all code committed to your  SVN repository

(not just the version that you submit):

Uploading or otherwise providing the assignment specification or part of it to a third party including online tutorial and contract cheating websites is considered misconduct.  The university is aware of these sites and many cooperate with us in misconduct investigations.

The teaching staff will conduct interviews with a subset of students about their submissions, for the purposes of establishing genuine authorship.  If you write your own code, you have nothing to fear from this process.  If you legitimately use code from other sources (following the usage/referencing requirements in the table above) then you are expected to understand that code.  If you are not able to adequately explain the design of your solution and/or adequately explain your submitted code (and/or earlier versions in your repository) and/or be able to make simple modifications to it as requested at the interview, then your assignment mark will be scaled down based on the level of understanding you are able to demonstrate and/or your submission may be subject to a misconduct investigation where your interview responses form part of the evidence.  Failure to attend a scheduled interview will result in zero marks for the assignment.  The use of referenced code in your submission (particularly from artificial intelligence tools) is likely to increase the probability of your selection for an interview.

In short - Don’t risk it!  If you’re having trouble, seek help early from a member of the teaching staff. Don’t be tempted to copy another student’s code or to use an online cheating service.   Don’t help another

CSSE2310/7231 student with their code no matter how desperate they may be and no matter how close your relationship. You should read and understand the statements on student misconduct in the course profile and on the school website: https://www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism.

Specification – testuqwordiply

testuqwordiply reads a set of test jobs from a file whose name is provided as a command line argument.  (The format of this file is specified below.) For each of these test jobs, testuqwordiply will run both a program to be tested (whose name is given on the command line, e.g. your solution to assignment one) and demo-uqwordiply and compare their outputs (stdout and stderr) and their exit statuses. If the stdout, stderr and exit statuses match, then the test passes, otherwise it fails.  The comparison of the programs’ outputs will require the use of a provided comparison program called uqcmp which reads input on file descriptors 3 and 4 (e.g. piped from stdout from each of the programs) and reports whether that data is the same or different.

Figure 1 illustrates the processes and pipes to be created by  testuqwordiply for each test job.   Four processes will be created (labelled A, B, C and D in Figure 1): an instance of the program being tested (A), an instance of demo-uqwordiply (B) and two instances of uqcmp – one for comparing the standard outputs of the two programs (C) and one for comparing the standard errors (D). This will require the creation of four pipes (labelled 1, 2, 3 and 4 in Figure 1). The standard input for the two programs being tested will come from a file whose name is specified in the job file – this contains sample user input for that test.

Full details of the required behaviour are provided below.

Figure 1: Processes (A to D) and pipes (1 to 4) to be created by testuqwordiply for each test job.

Command Line Arguments 64

testuqwordiply has two mandatory arguments – the name of the program being tested, and the name of a      65

job specification file that specifies the tests to be run.  There are two optional arguments which may appear in      66

either order if both are present (but must appear before the mandatory arguments).                                                          67

Usage of the program and the meaning of the arguments are as follows:                                                                    68

./testuqwordiply  [--quiet]  [--parallel] testprogram jobfile 69

shown), otherwise it should be output to testuqwordiply’s stdout and stderr respectively.  This option      71

does not change testuqwordiply’s output – it will still send output to stdout and stderr as described      72

in this specification. This behaviour is described in more detail below. 73

●   parallel – if present, the test jobs are to be run in parallel, otherwise they should be run sequentially      74

(one after the other). This behaviour is explained in more detail below.                                                                75

● testprogram – must be present and is the name of the program being tested against demo-uqwordiply.     76

The name can be a relative or absolute pathname or otherwise (if it doesn’t contain a slash ‘/’) is expected      77

to be found on the user’s PATH. The argument may not begin with --.  (If a program’s name begins with      78

-- then the path to the program must be given, e.g.  ./--prog.)                                                                            79

● jobfile – must be present (after the program name) and is the name of the file containing details of the     80 tests to be run (referred to in the remainder of this document as the job specification file).  More details     81 on the format of this file are given below. The argument may not begin with --.  (If a file’s name begins     82

with -- then the path to the file must be given, e.g.  ./--jobfile.)                                                                      83

Prior to doing anything else, your testuqwordiply program must check the validity of the command line      84

arguments. If the program receives an invalid command line then it must print the message:                                     85

Usage:  testuqwordiply  [--quiet]  [--parallel]  testprogram  jobfile                                                             86

Invalid command lines include (but may not be limited to) any of the following:                                                     88

●  arguments that begin with   that are not either --quiet or --parallel2 89

● either the --quiet or --parallel argument is specified more than once                                                           90

● the program name and/or the job file name are not specified on the command line                                          91

●  an unexpected argument is present                                                                                                                         92

Checking whether the program name and/or the file name are valid is not part of usage checking.                     93

Job Specification File 94

If the command line arguments are valid then testuqwordiply reads the job specification file listed on the      95

command line.  The whole file must be read and checked prior to any test jobs being run.                                                96

If testuqwordiply is unable to open the job specification file for reading then it must print the following      97

message to stderr (with a following newline) and exit with an exit status of 3:                                                            98

testuqwordiply: Unable  to  open  job  file  "filename "                                                                                        99

where filename is replaced by the name of the file (as given on the command line). (The double quotes around    100 the filename must be present in the output message.)                                                                                                   101

File Format                                                                                                                                                          102

The job specification file provided to testuqwordiply is a text file, with one line per job. The file may contain    103 any number of lines.                                                                                                                                                         104 If testuqwordiply is able to open the job specification file for reading, then it should read and check all of    105 the test jobs in the file before starting any tests.                                                                                                           106 Lines in the job file beginning with the  ‘#’  (hash) character are comments3,  and are to be ignored by    107

testuqwordiply.  Similarly, empty lines (i.e.  with no characters before the newline) are to be ignored.                     108

All other lines are to be interpreted as job specifications, split over 2 separate fields delimited by the comma     109

(‘ , ’) character as follows:                                                                                                                                                         110

input-file-name,[arg1  arg2  . . .]                                                                                                                             111

The input-file-name field is the name of a file to be used as the standard input to the the test program    112 and to demo-uqwordiply for that test. It may be an absolute pathname or relative to the current directory. It    113 must not be an empty field.                                                                                                                                             114

The second field is a space separated list of command line arguments to be provided to the test program     115

and to demo-uqwordiply when the test is run.  This field may be empty.  Arguments that contain spaces may    116 be enclosed by double quotes.  Leading spaces and extra separating spaces are ignored.  (A helper function is    117 provided to make processing this field easier, see the split_space_not_quote() function described on page    118 10.)                                                                                                                                                                                     119 Note that individual job specifications are independent – a given test job will always be run in the same way    120 independent of any other test jobs described in the file.                                                                                               121

The comma character has special meaning in job specification files and will only appear in job lines as a     122

separator.  You do not need to consider, nor will we test for, job specification files that contain the comma    123 character as part of a file name or an argument.  See the split_line() function described on page 10 for an    124 easy way to split the comma-delimited job specifications.                                                                                             125

Checking the Jobs                                                                                                                                               126

Each job listed in the job specification file must be checked in turn. If a job line is not syntactically valid then     127

testuqwordiply must print the following message to stderr  (with a following newline) and exit with an exit     128

status of 4:                                                                                                                                                                                  129

testuqwordiply:  syntax  error  on  line linenum of  "filename "                                                                       130

where linenum is replaced by the line number in the job specification file (where lines are counted from 1), and    131 filename is replaced by the name of the job specification file (as given on the command line).  (The double    132 quotes around the filename must be present in the output message.) No further job lines are checked.                   133  A syntactically valid line will contain exactly one comma with at least one character before the comma (i.e.    134 a non-empty input filename).                                                                                                                                           135

If the line is syntactically valid but the input file specified on the job line is unable to be opened for reading,     136

then testuqwordiply must print the following message to stderr (with a following newline) and exit with an     137

exit status of 5:                                                                                                                                                                          138

testuqwordiply:  unable  to  open  file  " inputfile "  specified  on  line linenum of  "filename "            139

where inputfile is replaced by the name of the file specified on the job line (all characters before the comma),     140

linenum is replaced by the line number in the job specification file  (where lines are counted from  1), and    141 3 “beginning with” means the # character is in the leftmost position on the line – there are no preceding spaces or other characters

filename is replaced by the name of the job specification file (as given on the command line).  (The double    142 quotes around both filenames must be present in the output message.)                                                                      143

If these checks are passed (the line is syntactically valid and the input file can be opened for reading) then     144

testuqwordiply can move on to the next line in the job file.                                                                                                      145

If testuqwordiply reaches the end of the file and doesn’t find any job specifications (i.e. the file is empty or    146 only contains blank lines and/or comments) then testuqwordiply must print the following message to stderr    147 (with a following newline) and exit with an exit status of 6:                                                                                        148

testuqwordiply:  no  jobs  found  in  "filename "                                                                                                     149

where filename is replaced by the name of the job specification file  (as given on the command line).   (The     150

double quotes around the filename must be present in the output message.)                                                              151 The following are examples of valid jobfiles4 containing explanatory comments: