CSSE2310/CSSE7231 Assignment 3

School of Information Technology and Electrical Engineering

CSSE2310/CSSE7231 — Semester 1, 2023

Assignment 3 (version 1.0)

Marks: 75 (for CSSE2310), 85 (for CSSE7231)

Weighting: 15%

Due: 4:00pm Friday 5th May, 2023

Introduction 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

This is an individual assignment. You should feel free to discuss general aspects of C programming and 13

the assignment specification with fellow students, including on the discussion forum. In general, questions like 14

“How should the program behave if h this 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

All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or 20

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

to the discussion forum is permitted.) You must assume that some students in the course may have very long 24

extensions so do not post your code to any public repository until at least three months after the result release 25

date for the course (or check with the course coordinator if you wish to post it sooner). Do not allow others to 26

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

Code Origin Usage/Referencing

Code provided to you in writing this semester by

CSSE2310/7231 teaching staff (e.g. code hosted on Black￾board, found in /local/courses/csse2310/resources on

moss, posted on the discussion forum by teaching staff, pro￾vided in Ed Lessons, or shown in class).

May be used freely without reference. (You must be able

to point to the source if queried about it – so you may

find it easier to reference the code.)

Code you have personally written this semester for

CSSE2310/7231 (e.g. code written for A1 reused in A3)

– provided you have not shared or published it.

May be used freely without reference. (This assumes

that no reference was required for the original use.)

Code examples found in man pages on moss. May be used provided you understand the code AND

the source of the code is referenced in a comment

adjacent to that code (in the required format – see the

style guide). If such code is used without appropriate

referencing then this will be considered misconduct.

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 copied1

.

1Code you have taken inspiration from must not be directly copied or just converted from one programming language to another.

1

Code Origin Usage/Referencing

Code written by or obtained from, or based on code written

by or obtained from, a code generation tool (including any

artificial intelligence tool) that you personally have inter￾acted with, without the assistance of another person.

May be used provided you understand that code AND

the source of the code is referenced in a comment ad￾jacent to that code (in the required format) AND an

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.

Other code – includes (but may not be limited to): code

provided by teaching staff only in a previous offering of this

course (e.g. previous assignment one solution); code from

public or private repositories; code from websites; code

from textbooks; any code written or partially written or

provided by or written with the assistance of someone else;

and any code you have written that is available to other

students.

May not be used. If the source of the code is referenced

adjacent to the code then this will be considered code

without academic merit (not misconduct) and will be

removed from your assignment prior to marking (which

may cause compilation to fail and zero marks to be

awarded). Copied code without adjacent referencing will

be considered misconduct and action will be taken.

Uploading or otherwise providing the assignment specification or part of it to a third party including online 30

tutorial and contract cheating websites is considered misconduct. The university is aware of these sites and 31

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

scaled down based on the level of understanding you are able to demonstrate and/or your submission may be 39

subject to a misconduct investigation where your interview responses form part of the evidence. Failure to 40

attend a scheduled interview will result in zero marks for the assignment. The use of referenced code in your 41

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

CSSE2310/7231 student with their code no matter how desperate they may be and no matter how close your 46

relationship. You should read and understand the statements on student misconduct in the course profile and 47

on the school website: https://www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism. 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

2

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

• --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

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

to standard error (with a following newline) and exit with an exit status of 2. 87

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

2To allow for getopt() implementations of argument parsing (not required) we will not run any tests using the argument --

3

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

4

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:

# 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 152

If all of the test jobs in the job specification file are valid then testuqwordiply must run the jobs, either in 153

sequence (one after the other) or in parallel (if the --parallel argument is provided on the command line). 154

The behaviour of these two different modes is described below. 155

Running Test Jobs Sequentially 156

If testuqwordiply is running jobs sequentially, then it must perform the following sequence of operations: 157

For each job (in the order specified in the job specification file): 158

• Start the job (as described below in Running One Test Job) 159

• Sleep for 2 seconds 160

• Send a SIGKILL signal to all processes that make up that job. (It is likely they are already dead, but 161

testuqwordiply does not need to check this prior to attempting to send a signal.) 162

• Report the result of the job (as described below in Reporting the Result of One Test Job). 163

When one job is complete, the next job can be started. 164

Running Test Jobs In Parallel 165

If testuqwordiply is running jobs in parallel, then it must perform the following sequence of operations: 166

• Start all of the jobs specified in the job specification file (each individual job should be started as described 167

below in Running One Test Job) 168

• Sleep for 2 seconds 169

4This assumes that all of the listed input files are valid readable files in the current directory.

5

• Send a SIGKILL signal to all processes that make up all jobs. (It is likely they are already dead, but 170

testuqwordiply does not need to check this prior to attempting to send a signal.) 171

• Iterate over each job (in the order specified in the job specification file) and report the result of the job 172

(as described below in Reporting the Result of One Test Job). 173

Running One Test Job 174

Just before running a test job, testuqwordiply must output the following to standard output (followed by a 175

newline): 176

Starting job T 177

where T is replaced by the job number (1 to N, where N is the number of jobs in the job specification file). 178

For each individual test job, testuqwordiply must create four pipes and four processes as shown in Figure 1. 179

The four processes are: 180

• an instance of the program being tested (as specified on the command line). Standard input for this 181

process must come from the input file specified in the job. Standard output and standard error must be 182

sent to file descriptor 3 of two instances of uqcmp (see description of uqcmp instances below). 183

• an instance of demo-uqwordiply – which will be found in the user’s PATH. Standard input for this process 184

must come from the input file specified in the job. Standard output and standard error must be sent to 185

file descriptor 4 of the two instances of uqcmp. This is the expected output from the test program. 186

• an instance of uqcmp which compares standard outputs – which will receive the standard output of the 187

program being tested on file descriptor 3 and the standard output of demo-uqwordiply on file descriptor 188

4. uqcmp must be started with one command line argument: “Job T stdout” where T is replaced by the 189

job number. 190

• an instance of uqcmp which compares standard errors – which will receive the standard error of the 191

program being tested on file descriptor 3 and the standard error of demo-uqwordiply on file descriptor 192

4. uqcmp must be started with one command line argument: “Job T stderr” where T is replaced by the 193

job number. 194

If the --quiet option is provided on the testuqwordiply command line then the standard output and 195

standard error of the uqcmp instances must be redirected to /dev/null. If --quiet is not specified, then the 196

uqcmp instances must inherit standard output and standard error from testuqwordiply – i.e. send standard 197

output and standard error to wherever testuqwordiply’s standard output and standard error are being sent. 198

Reporting the Result of One Test Job 199

uqcmp will exit with an exit status of 0 if the data received on file descriptor 3 matches that received on file 200

descriptor 4, otherwise it will exit with a non-zero exit status. Full details on the behaviour of the uqcmp 201

program are given below. 202

If any of the programs were unable to be executed (demo-uqwordiply, uqcmp or the program under test) 203

then testuqwordiply must print the following to standard output (followed by a newline): 204

Job T : Unable to execute test 205

where T is replaced by the job number. This counts as a test failure. (If one test job fails then all test jobs are 206

likely to fail. A possible scenario is where one of the programs is not found in the user’s PATH.) 207

If the four programs run, then for one individual test (say job number T), testuqwordiply must report the 208

following – in this given order. (In all of the messages below, T is replaced by the job number. All messages 209

are sent to testuqwordiply’s standard output and are terminated by a single newline.) 210

• If the standard outputs of the two programs match (as determined by the exit status of that uqcmp 211

instance), then testuqwordiply must print the following: 212

Job T : Stdout matches 213

If the standard outputs do not match, then testuqwordiply must print the following: 214

Job T : Stdout differs 215

6

• If the standard errors of the two programs match (as determined by the exit status of that uqcmp instance), 216

then testuqwordiply must print the following: 217

Job T : Stderr matches 218

If the standard errors do not match, then testuqwordiply must print the following: 219

Job T : Stderr differs 220

• If both processes exit normally with the same exit status, then testuqwordiply must print the following: 221

Job T : Exit status matches 222

otherwise it must print: 223

Job T : Exit status differs 224

Reporting the Overall Result 225

A test passes if the standard output, standard error and exit statuses of the program being tested and 226

demo-uqwordiply all match each other. 227

For both sequential and parallel modes of operation, when all test jobs have been run and finished, then 228

testuqwordiply must output the following message to stdout (followed by a newline): 229

testuqwordiply: M out of N tests passed 230

where M is replaced by the number of tests that passed, and N is replaced by the number of tests that have been 231

run (which may be fewer than the number of the tests in the job specification file if the tests are interrupted – 232

see below). 233

If all tests that have been run passed then testuqwordiply must exit with exit status 0 (indicating success), 234

otherwise it must exit with exit status 1 (indicating failure). 235

Interrupting the Tests 236

If testuqwordiply receives a SIGINT (as usually sent by pressing Ctrl-C) then it should complete the test job(s) 237

in progress (including any sleeps), not commence any more test jobs, and report the overall result (as described 238

above) based on the tests that have been run. 239

In practical terms, this will only make a difference in sequential mode – tests that haven’t been started will 240

not be run. In parallel mode, all tests are started immediately, so all tests should be run to completion if a 241

SIGINT is received. 242

Specification – uqcmp 243

This section details the expected operation of uqcmp. Only CSSE7231 students are required to implement 244

uqcmp, but this section is useful to all students so as to understand how uqcmp behaves. The UQ provided version 245

of uqcmp will be used in testing testuqwordiply. uqcmp programs implemented by CSSE7231 students will be 246

tested independently of testuqwordiply. 247

uqcmp will read from file descriptors 3 and 4, compare the data read from both file descriptors, and determine 248

whether it is the same. The data read from file descriptor 4 is considered to be the “expected” (i.e. “correct”) 249

data, and is being compared with that received from file descriptor 3. 250

uqcmp Command Line Arguments 251

uqcmp takes one optional command line argument – a prefix that is to be emitted with messages that are output 252

(see below). 253

If more than one command line argument is provided, then uqcmp is to output the following message to 254

standard error (with a following newline) and then exit with exit status 1: 255

Usage: uqcmp [prefix] 256

If no prefix is specified on the command line then the prefix “uqcmp” is to be used (without the quotes). 257

uqcmp Operation 258

If file descriptor 3 is not open, then uqcmp must output the following message to standard error (with a following 259

newline) and then exit with status 2: 260

7

uqcmp: fd 3 is not open 261

If file descriptor 3 is open and file descriptor 4 is not open, then uqcmp must output the following message 262

to standard error (with a following newline) and then exit with status 2: 263

uqcmp: fd 4 is not open 264

If both file descriptors are open, then uqcmp will print a message (with a following newline) and exit as 265

described below. The text PREFIX is to be replaced by the prefix specified on the command line (or uqcmp if 266

no prefix is specified on the command line). 267

• If identical data is received from both file descriptors 3 and 4 (from commencement to EOF) then uqcmp 268

must print the following to stdout: 269

PREFIX : OK 270

and exit with status 0. 271

• If no data is received on file descriptor 3 but data is received on file descriptor 4 then uqcmp must print 272

the following to stderr: 273

PREFIX : Expected data but received nothing 274

and exit with status 3. 275

• If data is received on file descriptor 3 but no data is received on file descriptor 4 then uqcmp must print 276

the following to stderr: 277

PREFIX : Received data but expected nothing 278

and exit with status 4. 279

• If data is received on both file descriptors 3 and 4 but this data does not match then uqcmp must print 280

the following to stderr: 281

PREFIX : Received data does not match expected data 282

and exit with status 5. 283

uqcmp may exit at any point after it is able to make this determination – i.e. it does not have to wait for 284

EOF on both file descriptors in order to exit if it has identified differences – though it may wait until then if 285

desired. 286

uqcmp ignores its standard input. 287

Testing uqcmp 288

You can test uqcmp at the command line by getting the shell to redirect files or standard input to file descriptors 289

3 and/or 4, e.g. 290

./uqcmp 3<&1 4