CSSE2310 Weighting: 15% Solution

1
The goal of this assignment is to demonstrate your skills and ability in fundamental process management and 2
communication concepts, and to further develop your C programming skills with a moderately complex program. 3
You are to create a program called testuqwordiply that creates and manages communicating collections 4
of processes that test a uqwordiply program (from assignment one) according to a job specification file that 5
lists tests to be run. For various test cases, your program will run both a test version of uqwordiply and the 6
assignment one solution (available as demo-uqwordiply) and compare their standard outputs, standard errors 7
and exit statuses and report the results. You will be provided with (and must use) a program named uqcmp 8
that will compare the input arriving on two file descriptors. The assignment will also test your ability to code 9
to a programming style guide and to use a revision control system appropriately. 10
CSSE7231 students will, in addition, write their own version of uqcmp. 11
Student Conduct 12
the assignment specification with fellow students, including on the discussion forum. In general, questions like 14
“How should the program behave if hthis happensi?” would be safe, if they are seeking clarification on the 15
specification. 16
You must not actively help (or seek help from) other students or other people with the actual design, structure 17
and/or coding of your assignment solution. It is cheating to look at another student’s assignment code 18
and it is cheating to allow your code to be seen or shared in printed or electronic form by others. 19
collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if 21
you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your 22
code to a public place such as the course discussion forum or a public code repository. (Code in private posts 23
extensions so do not post your code to any public repository until at least three months after the result release 25
access your computer – you must keep your code secure. Never leave your work unattended. 27
You must follow the following code referencing rules for all code committed to your SVN repository 28
(not just the version that you submit): 29
Introduction
Code Origin Usage/Referencing
Code provided to you in writing this semester by

Code you have personally written this semester for

Code you have personally written in a previous enrolment

in this course or in another ITEE course and where that code has not been shared or published.
Code (in any programming language) that you have taken inspiration from but have not copied .
Code Origin Usage/Referencing
ASCII text file (named toolHistory.txt) is included in your repository and with your submission that describes in detail how the tool was used. If such code is used without appropriate referencing and without inclusion of the toolHistory.txt file then this will be considered misconduct.

30
many cooperate with us in misconduct investigations. 32
The teaching staff will conduct interviews with a subset of students about their submissions, for the purposes 33
of establishing genuine authorship. If you write your own code, you have nothing to fear from this process. If 34
you legitimately use code from other sources (following the usage/referencing requirements in the table above) 35
then you are expected to understand that code. If you are not able to adequately explain the design of your 36
solution and/or adequately explain your submitted code (and/or earlier versions in your repository) and/or 37
be able to make simple modifications to it as requested at the interview, then your assignment mark will be 38
subject to a misconduct investigation where your interview responses form part of the evidence. Failure to 40
submission (particularly from artificial intelligence tools) is likely to increase the probability of your selection 42
for an interview. 43
In short - Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. 44
Don’t be tempted to copy another student’s code or to use an online cheating service. Don’t help another 45
relationship. You should read and understand the statements on student misconduct in the course profile and 47
48
Specification – testuqwordiply 49
testuqwordiply reads a set of test jobs from a file whose name is provided as a command line argument. (The 50
format of this file is specified below.) For each of these test jobs, testuqwordiply will run both a program to be 51
tested (whose name is given on the command line, e.g. your solution to assignment one) and demo-uqwordiply 52
and compare their outputs (stdout and stderr) and their exit statuses. If the stdout, stderr and exit statuses 53
match, then the test passes, otherwise it fails. The comparison of the programs’ outputs will require the use 54
of a provided comparison program called uqcmp which reads input on file descriptors 3 and 4 (e.g. piped from 55
stdout from each of the programs) and reports whether that data is the same or different. 56
Figure 1 illustrates the processes and pipes to be created by testuqwordiply for each test job. Four 57
processes will be created (labelled A, B, C and D in Figure 1): an instance of the program being tested (A), an 58
instance of demo-uqwordiply (B) and two instances of uqcmp – one for comparing the standard outputs of the 59
two programs (C) and one for comparing the standard errors (D). This will require the creation of four pipes 60
(labelled 1, 2, 3 and 4 in Figure 1). The standard input for the two programs being tested will come from a file 61
whose name is specified in the job file – this contains sample user input for that test. 62
Full details of the required behaviour are provided below. 63
Uploading or otherwise providing the assignment specification or part of it to a third party including online

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
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
• --quiet – if present, the output (stdout and stderr) of the uqcmp processes is to be suppressed (i.e. not 70
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
-- 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
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
to standard error (with a following newline) and exit with an exit status of 2. 87
• arguments that begin with -- that are not either --quiet or --parallel 89
• either the --quiet or --parallel argument is specified more than once 90
• either the --quiet or --parallel argument appears after a mandatory argument 91
• the program name and/or the job file name are not specified on the command line 92
• an unexpected argument is present 93
Checking whether the program name and/or the file name are valid is not part of usage checking. 94

Job Specification File 95
If the command line arguments are valid then testuqwordiply reads the job specification file listed on the 96
command line. The whole file must be read and checked prior to any test jobs being run. 97
If testuqwordiply is unable to open the job specification file for reading then it must print the following 98
message to stderr (with a following newline) and exit with an exit status of 3: 99
testuqwordiply: Unable to open job file "filename" 100
where filename is replaced by the name of the file (as given on the command line). (The double quotes around 101
the filename must be present in the output message.) 102
File Format 103
any number of lines. 105
If testuqwordiply is able to open the job specification file for reading, then it should read and check all of 106
the test jobs in the file before starting any tests. 107
Lines in the job file beginning with the ‘#’ (hash) character are comments , and are to be ignored by 108
testuqwordiply. Similarly, empty lines (i.e. with no characters before the newline) are to be ignored. 109
All other lines are to be interpreted as job specifications, split over 2 separate fields delimited by the comma 110
(‘,’) character as follows: 111
input-file-name,[arg1 arg2 ...] 112
The input-file-name field is the name of a file to be used as the standard input to the the test program 113
must not be an empty field. 115
The second field is a space separated list of command line arguments to be provided to the test program 116
be enclosed by double quotes. Leading spaces and extra separating spaces are ignored. (A helper function is 118
provided to make processing this field easier, see the split_space_not_quote() function described on page 119
10.) 120
Note that individual job specifications are independent – a given test job will always be run in the same way 121
independent of any other test jobs described in the file. 122
The comma character has special meaning in job specification files and will only appear in job lines as a 123
separator. You do not need to consider, nor will we test for, job specification files that contain the comma 124
character as part of a file name or an argument. See the split_line() function described on page 10 for an 125
easy way to split the comma-delimited job specifications. 126
Checking the Jobs 127
Each job listed in the job specification file must be checked in turn. If a job line is not syntactically valid then 128
testuqwordiply must print the following message to stderr (with a following newline) and exit with an exit 129
status of 4: 130
testuqwordiply: syntax error on line linenum of "filename" 131
where linenum is replaced by the line number in the job specification file (where lines are counted from 1), and 132
filename is replaced by the name of the job specification file (as given on the command line). (The double 133
quotes around the filename must be present in the output message.) No further job lines are checked. 134
A syntactically valid line will contain exactly one comma with at least one character before the comma (i.e. 135
a non-empty input filename). 136
If the line is syntactically valid but the input file specified on the job line is unable to be opened for reading, 137
then testuqwordiply must print the following message to stderr (with a following newline) and exit with an 138
exit status of 5: 139
testuqwordiply: unable to open file "inputfile" specified on line linenum of "filename" 140
where inputfile is replaced by the name of the file specified on the job line (all characters before the comma), 141
linenum is replaced by the line number in the job specification file (where lines are counted from 1), and 142

filename 143
quotes around both filenames must be present in the output message.) 144
If these checks are passed (the line is syntactically valid and the input file can be opened for reading) then 145
testuqwordiply can move on to the next line in the job file. 146
If testuqwordiply reaches the end of the file and doesn’t find any job specifications (i.e. the file is empty or 147
only contains blank lines and/or comments) then testuqwordiply must print the following message to stderr 148
(with a following newline) and exit with an exit status of 6: 149
testuqwordiply: no jobs found in "filename" 150
where filename is replaced by the name of the job specification file (as given on the command line). (The 151
double quotes around the filename must be present in the output message.)
The following are examples of valid jobfiles containing explanatory comments: 152
is replaced by the name of the job specification file (as given on the command line). (The double
# Run a single test with no command line arguments and an immediate EOF on stdin
/dev/null,
# Run two tests - specifying the starter word in both cases testfiles/cab,--start cab input-file,--start PRO
# Run four tests - with various combinations of starter word and dictionary # Also illustrates use of double quotes and additional spaces in arguments input.1,--start art --dictionary testfiles/common-words 2.in,--dictionary "testfiles/simple dictionary" "--start" ion
3.in, --start xyz --dictionary /dev/null
# Blank line on the line above will be ignored
2.in,--dictionary /usr/share/dict/words --start def
Running Test Jobs and Reporting Results 153
If all of the test jobs in the job specification file are valid then testuqwordiply must run the jobs, either in 154
sequence (one after the other) or in parallel (if the --parallel argument is provided on the command line). 155
The behaviour of these two different modes is described below. 156
Running Test Jobs Sequentially 157
If testuqwordiply is running jobs sequentially, then it must perform the following sequence of operations: 158
For each job (in the order specified in the job specification file): 159
• Start the job (as described below in Running One Test Job) 160
• Sleep for 2 seconds 161
• Send a SIGKILL signal to all processes that make up that job. (It is likely they are already dead, but 162
testuqwordiply does not need to check this prior to attempting to send a signal.) 163
• Report the result of the job (as described below in Reporting the Result of One Test Job). 164
When one job is complete, the next job can be started. 165
Running Test Jobs In Parallel 166
If testuqwordiply is running jobs in parallel, then it must perform the following sequence of operations: 167
• Start all of the jobs specified in the job specification file (each individual job should be started as described 168
below in Running One Test Job) 169
• Sleep for 2 seconds 170
171
testuqwordiply does not need to check this prior to attempting to send a signal.) 172
• Iterate over each job (in the order specified in the job specification file) and report the result of the job 173
(as described below in Reporting the Result of One Test Job). 174
Running One Test Job 175
Just before running a test job, testuqwordiply must output and flush the following to standard output (followed 176
by a newline): 177
Starting job T 178
where T is replaced by the job number (1 to N, where N is the number of jobs in the job specification file). 179
For each individual test job, testuqwordiply must create four pipes and four processes as shown in Figure 1. 180
The four processes are: 181
• an instance of the program being tested (as specified on the command line). Standard input for this 182
process must come from the input file specified in the job. Standard output and standard error must be 183
sent to file descriptor 3 of two instances of uqcmp (see description of uqcmp instances below). 184
• an instance of demo-uqwordiply – which will must be found in the user’s PATH i.e. do not assume a 185
particular location for demo-uqwordiply. Standard input for this process must come from the input file 186
specified in the job. Standard output and standard error must be sent to file descriptor 4 of the two 187
instances of uqcmp. This is the expected output from the test program. 188
• an instance of uqcmp which compares standard outputs – which will receive the standard output of the 189
program being tested on file descriptor 3 and the standard output of demo-uqwordiply on file descriptor 190
4. uqcmp must be started with one command line argument: “Job T stdout” where T is replaced by the 191
job number. uqcmp must be found in the user’s PATH – do not assume a particular location for uqcmp. 192
• an instance of uqcmp which compares standard errors – which will receive the standard error of the 193
program being tested on file descriptor 3 and the standard error of demo-uqwordiply on file descriptor 194
4. uqcmp must be started with one command line argument: “Job T stderr” where T is replaced by the 195
job number. uqcmp must be found in the user’s PATH – do not assume a particular location for uqcmp. 196
If the --quiet option is provided on the testuqwordiply command line then the standard output and 197
standard error of the uqcmp instances must be redirected to /dev/null. If --quiet is not specified, then the 198
uqcmp instances must inherit standard output and standard error from testuqwordiply – i.e. send standard 199
output and standard error to wherever testuqwordiply’s standard output and standard error are being sent. 200
Reporting the Result of One Test Job 201
uqcmp will exit with an exit status of 0 if the data received on file descriptor 3 matches that received on file 202
descriptor 4, otherwise it will exit with a non-zero exit status. Full details on the behaviour of the uqcmp 203
program are given below. 204
If any of the programs were unable to be executed (demo-uqwordiply, uqcmp or the program under test) 205
then testuqwordiply must print and flush the following to standard output (followed by a newline): 206
Job T: Unable to execute test 207
where T is replaced by the job number. This counts as a test failure. (If one test job fails then all test jobs are 208
likely to fail. A possible scenario is where one of the programs is not found in the user’s PATH.) 209
If the four programs run, then for one individual test (say job number T), testuqwordiply must report the 210
following – in this given order. (In all of the messages below, T is replaced by the job number. All messages 211
are sent to testuqwordiply’s standard output and are terminated by a single newline , and must be flushed at 212
the time of printing.) 213
• If the standard outputs of the two programs match (as determined by the exit status of that uqcmp 214
instance), then testuqwordiply must print the following: 215
Job T: Stdout matches 216
If the standard outputs do not match, then testuqwordiply must print the following: 217
Job T: Stdout differs 218
• Send a SIGKILL signal to all processes that make up all jobs. (It is likely they are already dead, but
uqcmp 219
then testuqwordiply must print the following: 220
Job T: Stderr matches 221
If the standard errors do not match, then testuqwordiply must print the following: 222
Job T: Stderr differs 223
• If both processes exit normally with the same exit status, then testuqwordiply must print the following: 224
Job T: Exit status matches 225
otherwise it must print: 226
Job T: Exit status differs 227
Reporting the Overall Result 228
A test passes if the standard output, standard error and exit statuses of the program being tested and 229
demo-uqwordiply all match each other. 230
For both sequential and parallel modes of operation, when all test jobs have been run and finished, then 231
testuqwordiply must output the following message to stdout (followed by a newline): 232
testuqwordiply: M out of N tests passed 233
where M is replaced by the number of tests that passed, and N is replaced by the number of tests that have been 234
see below). 236
If all tests that have been run passed then testuqwordiply must exit with exit status 0 (indicating success), 237
otherwise it must exit with exit status 1 (indicating failure). 238
Interrupting the Tests 239
If testuqwordiply receives a SIGINT (as usually sent by pressing Ctrl-C) then it should complete the test job(s) 240
in progress (including any sleeps), not commence any more test jobs, and report the overall result (as described 241
above) based on the tests that have been run. 242
In practical terms, this will only make a difference in sequential mode – tests that haven’t been started will 243
not be run. In parallel mode, all tests are started immediately, so all tests should be run to completion if a 244
SIGINT is received. 245
Specification – uqcmp 246
This section details the expected operation of uqcmp. Only CSSE7231 students are required to implement 247
uqcmp, but this section is useful to all students so as to understand how uqcmp behaves. The UQ provided version 248
of uqcmp will be used in testing testuqwordiply. uqcmp programs implemented by CSSE7231 students will be 249
tested independently of testuqwordiply. 250
uqcmp will read from file descriptors 3 and 4, compare the data read from both file descriptors, and determine 251
whether it is the same. The data read from file descriptor 4 is considered to be the “expected” (i.e. “correct”) 252
data, and is being compared with that received from file descriptor 3. 253
uqcmp Command Line Arguments 254
uqcmp takes one optional command line argument – a prefix that is to be emitted with messages that are output 255
(see below). 256
If more than one command line argument is provided, then uqcmp is to output the following message to 257
standard error (with a following newline) and then exit with exit status 1: 258
Usage: uqcmp [prefix] 259
If no prefix is specified on the command line then the prefix “uqcmp” is to be used (without the quotes). 260
uqcmp Operation 261
If file descriptor 3 is not open for reading, then uqcmp must output the following message to standard error 262
(with a following newline) and then exit with status 2: 263
• If the standard errors of the two programs match (as determined by the exit status of that instance),

uqcmp: fd 3 is not open 264
If file descriptor 3 is open for reading and file descriptor 4 is not open for reading, then uqcmp must output 265
the following message to standard error (with a following newline) and then exit with status 2: 266
uqcmp: fd 4 is not open 267
If both file descriptors are open for reading, then uqcmp will print a message (with a following newline) and 268
exit as described below. The text PREFIX is to be replaced by the prefix specified on the command line (or 269
uqcmp if no prefix is specified on the command line). 270
• If identical data is received from both file descriptors 3 and 4 (from commencement to EOF) then uqcmp 271
must print the following to stdout: 272
PREFIX: OK 273
and exit with status 0. 274
• If no data is received on file descriptor 3 but data is received on file descriptor 4 then uqcmp must print 275
the following to stderr: 276
PREFIX: Expected data but received nothing 277
and exit with status 3. 278
• If data is received on file descriptor 3 but no data is received on file descriptor 4 then uqcmp must print 279
the following to stderr: 280
PREFIX: Received data but expected nothing 281
and exit with status 4. 282
• If data is received on both file descriptors 3 and 4 but this data does not match then uqcmp must print 283
the following to stderr: 284
PREFIX: Received data does not match expected data 285
and exit with status 5. 286
desired. 289
uqcmp ignores its standard input. 290
Testing uqcmp 291
You can test uqcmp at the command line by getting the shell to redirect files or standard input to file descriptors 292
3 and/or 4, e.g. 293
./uqcmp 3<&1 4</dev/null 294
will redirect file descriptor 3 from standard input and file descriptor 4 from /dev/null. 295
Other Functionality – uqcmp and testuqwordiply 296
It is not expected that uqcmp has any special signal handling capability. 297
It is expected that testuqwordiply frees all dynamically allocated memory before exiting. (This requirement 298
does not apply to child processes of testuqwordiply.) 299
It is expected that child processes created by testuqwordiply do not inherit unnecessary open file de- 300
scriptors. The standard input for uqcmp processes is ignored but it is not considered an unnecessary open file 301
descriptor if it is open. 302
Example testuqwordiply Output 303
In this section we give examples of expected testuqwordiply output for some given job specification files and 304
command lines. Note that two programs that call get_wordiply_starter_word() at about the same time will 305
receive the same starter word – the random number generator in this program is seeded by the current time (in 306
seconds). 307
Note that these examples, like provided test-cases, are not exhaustive. You need to implement the program 308
specification as it is written, and not just code for these few examples. 309
Example One 310
Consider a job specification file as follows (named job1): 311
# One job - no command line args, immediate EOF on stdin
/dev/null,
1
2
In the following runs of testuqwordiply, assume that ./uqwordiply is a fully functional program. 312
$ ./testuqwordiply ./uqwordiply job1
Starting job 1
Job 1 stdout: OK
Job 1 stderr: OK
Job 1: Stdout matches
Job 1: Stderr matches Job 1: Exit status matches
testuqwordiply: 1 out of 1 tests passed $ ./testuqwordiply --quiet ./uqwordiply job1
Starting job 1
Job 1: Stdout matches
Job 1: Stderr matches Job 1: Exit status matches testuqwordiply: 1 out of 1 tests passed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Note that in the first run of testuqwordiply, the first two lines of output (lines 3 and 4 in the listing) 313
are the standard output from the two instances of uqcmp. (These could be printed in either order.) The 314
remaining lines are printed about two seconds later – and will always be in the order shown. In the second run 315
of testuqwordiply, the output of uqcmp is suppressed by using the --quiet command line argument. 316
Example Two 317
In the following example, assume that ./buggy-uqwordiply works correctly except that it exits with a segmen- 318
tation fault when given an empty dictionary. The job specification file job2 has the following contents: 319
1
./7.era.in, --start ERA
.lay.in,--start LAY --dictionary /dev/null
.in, --dictionary /usr/share/dict/words --start top
2 7
3 6.1
Assume that 7.lay.in, 7.era.in and 6.1.in are valid input files in the current directory (matching those 320
provided in the assignment one test files found in /local/courses/csse2310/resources/a1/testfiles.public 321
on moss). 322
$ time ./testuqwordiply --quiet ./buggy-uqwordiply job2
Starting job 1
Job 1: Stdout matches
Job 1: Stderr matches
Job 1: Exit status matches
Starting job 2
Job 2: Stdout differs
Job 2: Stderr matches
Job 2: Exit status differs
Starting job 3
Job 3: Stdout matches
Job 3: Stderr matches Job 3: Exit status matches
testuqwordiply: 2 out of 3 tests passed
real 0m6.004s user 0m0.165s sys 0m0.014s
$ time ./testuqwordiply --parallel ./buggy-uqwordiply job2
Starting job 1
1
2
3
4
5
6
7
8
9 10
11
12
13
14
15
16
17
18
19
20
Starting job 2
Starting job 3
Job 2 stdout: Expected data but received nothing
Job 2 stderr: OK
Job 1 stderr: OK
Job 1 stdout: OK
Job 3 stderr: OK
Job 3 stdout: OK
Job 1: Stdout matches
Job 1: Stderr matches
Job 1: Exit status matches
Job 2: Stdout differs
Job 2: Stderr matches
Job 2: Exit status differs
Job 3: Stdout matches
Job 3: Stderr matches Job 3: Exit status matches testuqwordiply: 2 out of 3 tests passed
real 0m2.003s user 0m0.165s sys 0m0.012s
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
time 323
how much time is taken to run the program. You can see in the first run (sequential mode) that the three tests 324
take about six seconds total to run. In the second run (parallel mode), the three tests take about two seconds 325
total to run. 326
In this second run, the output lines from uqcmp (lines 23 to 28 inclusive) could have been printed in any 327
Provided Library: libcsse2310a3 329
pages on moss for more details on these library functions. 331
char* read_line(FILE *stream); 332
The function attempts to read a line of text from the specified stream, allocating memory for it, and returning 333
the buffer. 334
char **split_line(char* line, char delimiter); 335
This function will split a line into substrings based on a given delimiter character. 336
char** split_space_not_quote(char *input, int *numTokens); 337
This function takes an input string and tokenises it according to spaces, but will treat text within double quotes 338
as a single token. 339
To use the library, you will need to add #include <csse2310a3.h> to your code and use the compiler flag 340
-I/local/courses/csse2310/include when compiling your code so that the compiler can find the include 341
file. You will also need to link with the library containing this function. To do this, use the compiler arguments 342
-L/local/courses/csse2310/lib -lcsse2310a3. 343
Style 344
Your program must follow version 2.3.0 of the CSSE2310/CSSE7231 C programming style guide available on 345
the course Blackboard site. 346
Hints 347
6 and 7. These provide the necessary background for this assignment. 349
The lines shown in green (and the blank line prior to these) are the output of the utility which reports
350
3. You can examine the file descriptors associated with a process by running ls -l /proc/PID/fd where 351
PID is the process ID of the process. 352
4. If you implement the test interruption functionality, consider the use of nanosleep() to allow resumption 353
of interrupted sleeps. 354
5. uqcmp (CSSE7231): You can determine if a file descriptor is open for reading by trying to use it in a 355
function that will report an error if it is not open for reading, e.g. fdopen(), dup(), fcntl(), read(), 356
etc. 357
6. Remember that the pipe() system call will typically return the two lowest free file descriptors – which 358
might be 3 and 4 for your first call to pipe(). If you have code something like dup2(fd,3); close(fd); 359
then this will NOT do what you expect if fd is 3. Calling dup2(3,3) will do nothing and a subsequent 360
close(3) will close file descriptor 3. 361
Suggested Approach 362
It is suggested that you write your program using the following steps. Test your program at each stage and 363
commit to your SVN repository frequently. Note that the specification text above is the definitive description 364
of the expected program behaviour. The list below does not cover all required functionality but will get you 365
started. 366
1. Write a program to parse the expected command line arguments and handle usage errors. 367
2. Write code to read and parse the job specification file and save it to a data structure (and output error 368
messages if problems are found). 369
3. Write code that correctly starts the four processes associated with one job (with the necessary command 370
line arguments). 371
4. Add code to redirect the standard input of the program under test and testuqwordiply demo-uqwordiply. 372
5. Add code to create the four pipes and connect them as required to the four processes. 373
Forbidden Functions 374
You must not use any of the following C functions/statements/directives. If you do so, you will get zero (0) 375
• goto 377
• #pragma 378
• longjmp() and equivalent functions 379
• system() or popen() 380
• mkfifo() or mkfifoat() 381
Submission 382
Your submission must include all source and any other required files (in particular you must submit a Makefile). 383
Do not submit compiled files (e.g. .o files and compiled programs). 384
Your programs testuqwordiply and uqcmp (CSSE7231 only) must build on moss.labs.eait.uq.edu.au 385
and in the Gradescope test environment with the command: 386
make 387
Your program must be compiled with gcc with at least the following options: 388
-pedantic -Wall -std=gnu99 389
2. While not mandatory, the provided library functions will make your life a lot easier – use them!
390
than .c and .h files as part of the build process – such files will be removed before building your program. 391
CSSE7231 only – the default target of your Makefile must cause both programs to be built . 392
for functionality (see below). Any code without academic merit will be removed from your program before 394
Your program must not invoke other programs or use non-standard headers/libraries other than those 396
explicity described in this specification. 397
Your assignment submission must be committed to your subversion repository under 398
https://source.eait.uq.edu.au/svn/csse2310-sem1-sXXXXXXX/trunk/a3 399
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 400
will not be considered in marking – they will not be checked out of your repository. 402
You must ensure that all files needed to compile and use your assignment (including a Makefile) are com- 403
mitted and within the trunk/a3 directory in your repository (and not within a subdirectory or some other part 404
of your repository) and not just sitting in your working directory. Do not commit compiled files or binaries. 405
You are strongly encouraged to check out a clean copy for testing purposes. 406
To submit your assignment, you must run the command 407
2310createzip a3 408
on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 409
available in the Assessment area on the CSSE2310/7231 Blackboard site) . The zip file will be named 410
sXXXXXXX_csse2310_a3_timestamp.zip 411
where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 412
the time that the zip file was created. 413
The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 414
ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your 415
part of this process in order to check out your submission from your repository. You will be asked to confirm 417
references in your code. 418
You must not create the zip file using some other mechanism and you must not modify the zip file prior 419
is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 421
creation of your submission zip file. 422
for details. 425
Note that Gradescope will run the test suite immediately after you submit. When complete you will be 426
able to see the results of the “public” tests. 427
are asked to attend an interview about your assignment and you do not attend or are unable to adequately 430
respond to questions – see the Student conduct section above. 431
Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), and 433
your zip file has been generated correctly and has not been modified prior to submission, then you will earn 434
436
for that feature, even if you claim to have implemented it. For example, if your program can never create 438
a child process then we can not test pipe communication between the processes of that job, or your ability 439
to send it a termination signal. Memory-freeing tests require correct functionality also – a program that frees 440
with that test. Note that some tests will have an approximate expected completion time of 2 seconds or some 444
code without academic merit). 447
CSSE7231): 449
3. testuqwordiply is able to run the required four processes for one test job (described 452
in a single line job specification file). File descriptors need not be setup correctly. 453
4. testuqwordiply constructs the necessary pipes and stdin redirections for the four 455
processes in one test job (described in a single line job specification file). Multiple 456
5. testuqwordiply correctly implements testing of one job (including reporting results and 458
6. testuqwordiply correctly implements sequential testing of multiple jobs (including 460
7. testuqwordiply correct implements parallel testing of multiple jobs (including 462
10. testuqwordiply correctly closes unnecessary file descriptors in child processes 466
(It is possible some tests above will require closing some file descriptors to ensure success, 467
tially and in parallel must be working to fully test more advanced functionality such as checking for unnecessary 471
file descriptors being closed and for memory to be freed. 472

Style Marking 478
Style marking is based on the number of style guide violations, i.e. the number of violations of version 2.3 of 479
You should pay particular attention to commenting so that others can understand your code. The marker’s 482
decision with respect to commenting violations is final – it is the marker who has to understand your code. To 483
more than your functionality mark – this prevents the submission of well styled programs which don’t meet at 485
least a minimum level of required functionality. 486
You are encouraged to use the style.sh tool installed on moss to style check your code before submission. 487
This does not check all style requirements, but it will determine your automated style mark (see below). Other 488
elements of the style guide are checked by humans. 489
All .c and .h files in your submission will be subject to style marking. This applies whether they are 490
compiled/linked into your executable or not . 491
.c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). 494
(Automated style marking can only be undertaken on code that compiles. The provided style.sh script checks 495
this for you.) 496
If your code does compile then your automated style mark will be determined as follows: Let 497
• W be the total number of distinct compilation warnings recorded when your .c files are individually built 498
(using the correct compiler arguments) 499
• A be the total number of style violations detected by style.sh when it is run over each of your .c and 500
.h files individually . 501
Your automated style mark S will be 502
S = 5 − (W + A) 503
penalised incorrectly then please bring this to the attention of the course coordinator and your mark can be 506
errors not picked up when you run style.sh on moss. This will not be considered a marking error – it is your 508
responsibility to ensure that all of your code follows the style guide, even if styling errors are not detected in 509
some runs of style.sh. You can check the result of Gradescope style marking soon after your Gradescope 510
submission – when its test suite completes running. 511
and “other”. The meanings of words like appropriate and required are determined by the requirements in the 514
style guide. Note that functions longer than 50 lines will be penalised in the automated style marking. Functions 515
that are also longer than 100 lines will be further penalised here. 516

Mark Description
0 The majority (50%+) of comments present are inappropriate OR there are many required comments missing
0.5 The majority of comments present are appropriate AND the majority of required comments are present
1.0 The vast majority (80%+) of comments present are appropriate AND there are at most a few missing comments
1.5 All or almost all comments present are appropriate AND there are at most a few missing comments
2.0 Almost all comments present are appropriate AND there are no missing comments
2.5 All comments present are appropriate AND there are no missing comments
518
Naming (1 mark) 519
Mark Description
0 At least a few names used are inappropriate
0.5 Almost all names used are appropriate
1.0 All names used are appropriate
520
Mark Description
0 One or more functions is longer than 100 lines of code OR there is more than one global/static variable present inappropriately OR there is a global struct variable present inappropriately OR there are more than a few instances of poor modularity (e.g. repeated code)
0.5 All functions are 100 lines or shorter AND there is at most one inappropriate non-struct global/static variable AND there are at most a few instances of poor modularity
1.0 All functions are 100 lines or shorter AND there are no instances of inappropriate global/static variables AND there is no or very limited use of magic numbers AND there is at most one instance or poor modularity
1.5 All functions are 100 lines or shorter AND there are no instances of inappropriate global/static variables AND there is no use of magic numbers AND there are no instances of poor modularity
522
will be graded according to the following principles: 525
• Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will 526
yield a score of zero for this section) 527
• Appropriate use of log messages to capture the changes represented by each commit. (Meaningful messages 528
explain briefly what has changed in the commit (e.g. in terms of functionality) and/or why the change 529
has been made and will be usually be more detailed for significant changes.) 530
The standards expected are outlined in the following rubric: 531
Mark
(out of 5) Description
0 Minimal commit history – only one or two commits OR all commit messages are meaningless.
1 Some progressive development evident (three or more commits) AND at least one commit message is meaningful.
2 Progressive development is evident (multiple commits) AND at least half the commit messages are meaningful.
3 Multiple commits that show progressive development of ALL functionality (e.g. no large commits with multiple features in them) AND at least half the commit messages are meaningful.
4 Multiple commits that show progressive development of ALL functionality AND meaningful messages for all but one or two of the commits.
5 Multiple commits that show progressive development of ALL functionality AND meaningful messages for ALL commits.
532

Total Mark 533
Let 534
• F be the functionality mark for your assignment (out of 60 for CSSE2310 students or out of 70 for 535
CSSE7231 students). 536
• S be the automated style mark for your assignment (out of 5). 537
• H be the human style mark for your assignment (out of 5). 538
• C be the SVN commit history mark (out of 5). 539
• V is the scaling factor (0 to 1) determined after interview(s) (if applicable – see the Student Conduct 540
section above) – or 0 if you fail to attend a scheduled interview without having evidence of exceptional 541
circumstances impacting your ability to attend. 542
Your total mark for the assignment will be: 543
M = (F + min{F,S + H} + min{F,C}) × V 544
out of 75 (for CSSE2310 students) or out of 85 (for CSSE7231 students). 545
Pretty code that doesn’t work will not be rewarded! 547
Late Penalties 548
Late penalties will apply as outlined in the course profile. 549
Specification Updates 550
Any errors or omissions discovered in the assignment specification will be added here, and new versions released 551
discussed on the discussion forum or emailed to csse2310@uq.edu.au. 553
554
• Fixed program name in step 4 of the suggested approach. 556
• Added another example of an invalid command line. 557
• Clarified that stdin for uqcmp is not considered an unnecessary open file descriptor, and also added 558
clarification for marking category which requires unnecessary file descriptors to be closed. 559
• Clarified that Starting job T message should be flushed to stdout before a job is started, and the job 560
results must be flushed when printed also. 561
• Clarified that uqcmp must check that file descriptors 3 and 4 are open for reading, not just open – and 562
updated associated hint. 563
• Added #pragma directives to list of prohibited C features. 564
• Added hint about the dup2(3,3) issue. 565
• Clarified that some tests will be terminated earlier than after 10 seconds if there is a shorter expected 566
completion time for the test. 567
• Updated marking criteria so that testing of just one job is a separate marking category 568
• Made it clear that the make command must build the program in the Gradescope environment, not just 569
on moss. 570
• Made it clear that demo-uqwordiply and uqcmp must be found in the user’s PATH – hardwired locations 571
must not be specified. 572