The University of Queensland
School of Information Technology and Electrical Engineering
CSSE2310/CSSE7231 — Semester 2, 2022
Assignment 3 (version 1.2)
Marks: 75 (for CSSE2310), 85 (for CSSE7231)
Weighting: 15%
Due: 6:00pm Friday 7th October, 2022
Specification changes from version 1.0 to 1.1 are shown in red and are summarised at the end of the document.
Specification changes from version 1.1 to 1.2 are shown in blue and are also summarised at the end.
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 jobthing, which creates and manages processes according to a job 4
specification file, and must monitor and maintain the status and input/output requirements of those processes. 5
The assignment will also test your ability to code to a programming style guide and to use a revision control 6
system appropriately. 7
CSSE7231 students will write an additional program, mytee which emulates some basic functionality of 8
the Unix tee command, as a further demonstration of your C programming, file and commandline handling 9
capabilities. 10
Student Conduct 11
This is an individual assignment. You should feel free to discuss general aspects of C programming and 12
the assignment specification with fellow students, including on the discussion forum. In general, questions like 13
“How should the program behave if h this happensi ?” would be safe, if they are seeking clarification on the 14
specification. 15
You must not actively help (or seek help from) other students or other people with the actual design, structure 16
and/or coding of your assignment solution. It is cheating to look at another student’s assignment code 17
and it is cheating to allow your code to be seen or shared in printed or electronic form by others. 18
All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or 19
collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if 20
you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your 21
code to a public place such as the course discussion forum or a public code repository, and do not allow others 22
to access your computer – you must keep your code secure. 23
You must follow the following code referencing rules for all code committed to your SVN repository (not 24
just the version that you submit): 25
Code Origin Usage/Referencing
Code provided to you in writing this semester by
CSSE2310/7231 teaching staff (e.g. code hosted on Blackboard, posted on the discussion forum, or shown in class).
May be used freely without reference. (You must be able
to point to the source if queried about it.)
Code you have personally written this semester for
CSSE2310/7231 (e.g. code written for A1 reused in A3)
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 the source of the code is
referenced in a comment adjacent to that code. (Code
you have taken inspiration from must not be directly
copied or just converted from one programming
language to another.)
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.
Other code – includes: code provided by teaching staff only
in a previous offering of this course (e.g. previous A1 solution); code from websites; code from textbooks; any code
written by someone else, or partially written by 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.
26
1 Version 1.2
Uploading or otherwise providing the assignment specification or part of it to a third party including online 27
tutorial and contract cheating websites is considered misconduct. The university is aware of these sites and 28
many cooperate with us in misconduct investigations. 29
The course coordinator reserves the right to conduct interviews with students about their submissions, for 30
the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from this 31
process. If you are not able to adequately explain your code or the design of your solution and/or be able to 32
make simple modifications to it as requested at the interview, then your assignment mark will be scaled down 33
based on the level of understanding you are able to demonstrate. 34
In short - Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. 35
Don’t be tempted to copy another student’s code or to use an online cheating service. You should read and 36
understand the statements on student misconduct in the course profile and on the school web-site: https: 37
//www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism 38
Specification – jobthing 39
jobthing reads a job configuration from a file whose name is provided as a command line argument. It creates 40
processes and runs programs according to that specification, optionally connecting those processes’ standard 41
input and output either to files, or jobthing itself via pipes. jobthing then reads input from stdin, interpreting 42
that input as commands that cause various actions to be taken, such as sending strings to the other processes, 43
reporting on statistics and so on. jobthing must handle certain signals and take specific action upon receiving 44
those signals. 45
Full details of the required behaviour are provided below. 46
Command Line Arguments 47
jobthing has one mandatory argument – the name of the job specification file, and also accepts several optional 48
arguments. These arguments may appear in any order. 49
./jobthing [-v] [-i inputfile] jobfile 50
• The optional -v argument, if supplied, puts jobthing into verbose mode, causing it to emit additional 51
debug and status information. Precise requirements are documented below. 52
• The optional -i inputfile argument is the name of a file which will be used to provide input to jobthing 53
and its managed processes. If no inputfile is specified (i.e. the -i argument is not given), then jobthing 54
is to take input from stdin 55
• The jobfile argument specifies the name of a file from which job information is to be read. This format 56
is documented below. This argument is mandatory. 57
If the user provides invalid options, too few or too many command line arguments, jobthing shall emit the 58
following usage information to stderr, and exit with return code 1: 59
Usage: jobthing [-v] [-i inputfile] jobfile 60
If the inputfile specified with the -i argument is unable to be opened for reading, then the following message 61
should be emitted to stderr and jobthing should exit with return code 3: 62
Error: Unable to read input file 63
This should be checked prior to attempting to open the job file. 64
jobthing basic behaviour 65
jobthing reads the job specification file provided on the command line, spawning child processes and executing 66
programs as required. In general, jobthing is required to maintain a constant process state, regardless of what 67
happens to those child processes and programs. For example, if a child process is killed or terminates somehow, 68
then, unless otherwise specified, jobthing is required to notice this, and re-spawn the job as required, up to 69
the maximum number of retries specified for each job. 70
Depending on the contents of the jobfile, each job created by jobthing may have its stdin and stdout 71
connected to a pipe (back to jobthing), or to a file on the filesystem. 72
2 Version 1.2
Once jobthing has created the initial set of jobs, it is to take input either from stdin, or from the file 73
specified with the -i inputfile commandline argument, one line at a time. By default each input line should 74
be sent to each job to which jobthing has a pipe connection, however a line starting with the asterisk character 75
‘*’ will be interpreted as a command. 76
After sending the input text to each job, jobthing will then attempt to read a line of input from each 77
job (again, only those to which jobthing is connected by a pipe). Output received from jobs is emitted to 78
jobthing’s standard output. 79
Upon reading EOF from the input (stdin or the input file), jobthing shall terminate. 80
jobthing job parsing 81
The job file provided to jobthing is a text file, with one line per job. 82
83
If jobthing is unable to open the job file for reading, it is to emit the following message to stderr, and 84
exit with return code 2: 85
Error: Unable to read job file 86
Lines beginning with the ‘#’ (hash) character are comments, and are to be ignored by jobthing. Similarly, 87
empty lines (i.e. with no characters before the newline) are to be ignored. 88
89
All other lines are to be interpreted as job specifications, split over 4 separate fields delimited by the colon (‘:’) 90
character as follows 91
92
numrestarts:input:output:cmd [arg1 arg2 ...] 93
94
where each field has the following meaning or intepretation: 95
• numrestarts – specifies how many times jobthing shall start or restart this job if it terminates. 0 96
(zero) or empty implies that jobthing shall restart the job every time it terminates, 1 (one) means that 97
jobthing should attempt to launch the job once only upon startup – if it terminates it is not restarted. 98
Other integers are interpreted similarly. 99
• input – empty implies that this job shall receive its standard input from a pipe connected to jobthing. 100
Otherwise, the named file is to be opened for reading and connected to this job’s standard input stream. 101
• output – empty implies that this job shall send its standard output to a pipe connected to jobthing. 102
Otherwise, the named file is to be opened for writing (with flags O_CREAT | O_TRUNC and permissions 103
S_IWUSR | S_IRUSR) and connected to this job’s standard output stream. 104
• cmd [arg1 arg2 ...] – the name of the program to be run for this job, and optional arguments to be 105
provided on the commandline to that program. Arguments are separated by spaces. Program names and 106
arguments containing spaces may be specified by enclosing them in double quotes. A helper function is 107
provided to make this easer, see the split_space_not_quote() function described on page 11. 108
Note: Individual job specifications are independent, and you do not need to consider if jobs might interact with 109
each other (e.g. sharing input or output files etc). We will only test job specifications that have predictable 110
and deterministic behaviour. 111
Note: The colon character has special meaning and will only appear in job files as a separator. You do not 112
need to consider, nor will we test for jobfiles that contain the colon character as part of a command name or 113
argument. 114
Note: See the split_line() function described on page 11 for an easy way to split the colon-delimited job 115
specifications. 116
117
Following are several sample jobfiles with explanatory comments:
# A job, running cat, stdin/stdout connected to jobthing. Only start 'cat' once
1:::cat
# A job, running cat, stdin/stdout connected to jobthing. Start 'cat' a maximum of 5 times
5:::cat
3 Version 1.2
# A job, running cat, stdin/stdout connected to jobthing.
# retries = 0 -> re-launch cat every time it terminates, no limit
0:::cat
# A job, running cat, take stdin from /etc/services, send stdout to foo.txt.
# Only run 'cat' once
1:/etc/services:foo.out:cat
# A job, running cat, take stdin from /etc/services, stdout connected back to jobthing
# Only run 'cat' once
1:/etc/services::cat
# two jobs, both running cat, stdin and stdout connected to jobthing.
# The first job runs cat only once, the second will restart it forever as required
1:::cat
0:::cat
If verbose mode is specified, for each valid job line read from the jobfile, jobthing should emit the following 118
output to its stdout 119
Registering worker N: cmd arg1 arg2 ... 120
where 121
• N is the replaced with job number, incrementing from 1 (one) 122
• cmd is the command to be run, and arg1, arg2, ... are any arguments provided to the command. Note 123
that there should be a single space between cmd and any arguments, and there should be no trailing space 124
on this line of output 125
The following is an example of such output: 126
Registering worker 1: cat
Registering worker 2: tee logfile.txt
A job line in the jobfile is invalid if any of the following conditions are met: 127
• There are not precisely 4 fields separated by colons 128
• The integer value restarts is not a proper, non-negative integer 129
• The cmd field in the job line is empty or starts with a space 130
Invalid job lines are to be ignored and are not given job numbers. Further, if verbose mode is specifed on 131
the command line, then jobthing shall emit the following to its stderr: 132
Error: invalid job specification: 133
where is replaced by the offending job specification line, e.g. 134
Error: invalid job specification: -10:0:foobar baz 135
jobthing startup phase 136
Once the jobfile has been read, jobs are to be created in the order they were specified in the job file. 137
• If an input file is specified for the job, jobthing shall attempt to open that file in read mode and the 138
job is to have its stdin redirected from that file. Otherwise, jobthing shall create a pipe, connecting 139
that job’s stdin to the reading end of the pipe, with jobthing holding the write end of the pipe through 140
which it will later send information. 141
4 Version 1.2
• Similarly, if an output file is specified for the job, jobthing shall attempt to open that file in for writing and 142
the job is to have its stdout redirected to that file. Otherwise, jobthing shall create a pipe, connecting 143
that job’s stdout to the writing end of the pipe, with jobthing holding the read end of the pipe through 144
which it will later receive information. 145
If a job has an input file specified, and that file cannot be opened, jobthing shall emit the following message 146
to stderr. The job shall be considered invalid unrunnable and no further handling or respawn attempts shall 147
be made for that job. (If an output file is also specified, no attempt shall be made to open it.) 148
Error: unable to open "" for reading 149
where is the name of the file from the job specification. 150
Similarly, if an output file is specified and cannot be opened for writing, the job is considered invalid 151
unrunnable, no further processing or spawn attempts are made, and jobthing shall emit to stderr: 152
Error: unable to open "" for writing 153
Once any input and output files and pipes are opened/created, jobthing shall spawn a new process for 154
each runnable job, connect the stdin and stdout of the new job as required, and then exec the command line 155
specified for the job. 156
If verbose mode is specified, then jobthing should emit the following to its stdout: 157
Spawning worker N 158
where N is replaced by the job number. 159
160
Important: jobthing shall ensure that all un-used file handles are closed before executing the job process. 161
That is, the job shall have only its standard input, output and error file handles open. (Standard error is just 162
to be inherited from jobthing.) Test scripts will check to ensure that no other file handles leak from jobthing 163
to individual jobs. 164
If the child’s exec call fails, the child process is to call _exit() with the return code 99. jobthing is not 165
expected to detect a failure to exec (e.g. such jobs don’t become unrunnable) – this is treated exactly the same 166
as a successful child execution where the child immediately returned exit status 99. 167
jobthing operation and command format 168
Once jobthing has started the jobs, it should sleep for one second and then enter an infinite loop (terminated 169
only by reading EOF on its input stream (stdin or the supplied input file) or by running out of viable workers 170
– see descriptions below). 171
Each time through the loop jobthing shall perform the following operations, in the exact order specified 172
below. 173
Note: Any jobs that were marked invalid unrunnable during the startup phase (i.e. because their input or 174
output files could not be opened) are excluded from all handling during this main loop. 175
1. Check on the status of each job (in the order they were specified in the job file), report on any jobs that 176
have terminated, and restart those which need to be restarted. 177
• for any jobs that have terminated since the last check, jobthing shall generate a line of output to 178
stdout in the following format: 179
Job N has terminated with exit code M 180
or 181
Job N has terminated due to signal S 182
depending on the reason for the job terminating. N, M and S should be substituted by the job number, 183
exit code or signal number as appropriate. 184
• close and clean up any pipes and file descriptors associated with communication to the terminated 185
job 186
• for each job that has terminated, if the total number of times it has been (re-)started is less than the 187
maximum number specified in the job file, then the job shall be restarted in exactly the same way it 188
was started (including input/output file redirection/pipes as required). Note that it is possible that 189
a respawning might not be possible due to the inability to open an input or output file for reading 190
or writing (even though that succeeded for an earlier run). In this case, jobthing should print the 191
5 Version 1.2
same error message as specified above (see “jobthing startup phase”) and make no further attempts 192
to respawn that job – i.e. the job becomes unrunnable. If the job is restarted and verbose mode is 193
specified, then jobthing shall emit the following to its stdout: 194
Restarting worker N 195
where N is replaced by the job number. 196
• If a job has already been restarted the maximum number of times, then it should not be restarted – 197
the job is now unrunnable. 198
2. If jobthing determines that there are no jobs running and no further possible jobs left to (re)launch (all 199
jobs are unrunnable), then it shall emit the following message to stderr, and exit with exit code 0 (zero): 200
No more viable workers, exiting
Reasons for this are 201
• No jobs remain with a non-zero restart count remaining 202
• No jobs remain that have valid input or output redirection files 203
3. Read a line of input from stdin or the specific jobthing input file, and process it as a command according 204
to the following requirements: 205
• If EOF is detected, then jobthing shall exit with exit status 0 (zero). 206
• Lines beginning with the asterisk ‘*’ character are treated as commands – see below for details. After 207
processing the command, jobthing shall return to the top of the main loop, checking job status again 208
etc. 209
• Any other lines are sent as-is to each job to which jobthing has a connection (i.e. a pipe exists 210
between jobthing and the job’s stdin). 211
• Data sent to each job is to be echoed to jobthing’s stdout in the following format: 212
ID<-’text’ 213
where ID is the job ID (starting from one), and ’text’ is the line of input sent to the job, surrounded 214
by single quotes. 215
4. jobthing shall sleep for 1 second 216
5. jobthing shall attempt to read exactly one line of input from each job to which it has a pipe connected 217
to that job’s stdout. Each line of output received from each job shall be emitted to jobthing’s stdout 218
as follows: 219
ID->’text’ 220
where ID is the job ID (starting from one), and ’text’ is the line of output received from the job, 221
surrounded by single quotes. It is expected that jobs will have a line of output available. If a job fails to 222
send such a line it is acceptable for jobthing to block until such time as a line is returned (or EOF is 223
detected). If EOF is detected, no message is output unless verbose mode is enabled. If verbose mode is 224
enabled then jobthing should output the following to stderr: 225
Received EOF from job N 226
where N is replaced by the job number. 227
6. Otherwise, jobthing shall repeat the loop starting back at Step 1 above. 228
NOTE: it is critical that you do these actions in this order, otherwise your program will behave differently and 229
fail many tests. 230
jobthing signal handling requirements 231
Upon receiving SIGHUP, jobthing is to emit to its stderr statistics on the history and status of each job that 232
was specified in the jobfile. Each line of the statistics report is of the format 233
234
jobnum:numstarts:linesto 235
where each field has the following interpretation: 236
6 Version 1.2
• jobnum – the number of the job, starting from one which is the first job in the provided jobfile 237
• numstarts – how many times jobthing has attempted to start or restart the job, including the initial 238
process creation upon startup 239
• linesto – how many lines of input jobthing has sent to the job. Jobs whose stdin is read from a file 240
(rather than a pipe from jobthing) will report 0 (zero). 241
Note that the statistics for any given job accumulate over multiple restarts – if a job is terminated and 242
respawned multiple times, the total number of lines sent to it over the lifetime of jobthing is reported. 243
jobthing shall block or otherwise ignore SIGINT (Control-C). 244
245
jobthing must gracefully handle the possibility that it attempts to write information down a pipe to a job that 246
has terminated. If this occurs, jobthing shall silently ignore this fact, and the terminated job and associated 247
pipes should be cleaned up as per normal processing, with the job being restarted if appropriate. 248
jobthing command handling 249
The following table describes the commands that must be implemented by jobthing, and their syntax. Addi- 250
tional notes on each command will follow. 251
Command Usage Comments
*signal *signal jobID signum Send the signal (signum – an integer) to the given job
(jobID).
*sleep *sleep millisec Sleep for millisec (an integer) milliseconds.
252
• Any invalid commands provided to jobthing (i.e. a command word starting with ‘*’ is invalid), shall 253
result in the following message to stdout: 254
Error: Bad command 'cmd'
where ’cmd’ is the offending command enclosed in single quotes 255
• if the command is not provided the correct number of arguments, the following is emitted to stdout 256
Error: Incorrect number of arguments
• All numerical arguments, if present, must be complete and valid numbers. e.g. “15” is a valid integer, but 257
“15a” is not. Your program must correctly identify and report invalid numerical arguments (see details 258
below for each command). Leading whitespace characters are permitted, e.g. “ 10” is a valid number – 259
these whitespace characters are automatically skipped over by functions like strtol() and strtod(). 260
• Any text arguments, including strings and program names, may contain spaces if the argument is surrounded 261
by double quotation marks, e.g. "text with spaces". A line with an odd number of double quotes will 262
be treated as though there is an additional double quote at the end of the line1
. A helper function is 263
provided to assist you with quote-delimited parsing, see the “Provided Library” section on page 11 for 264
usage details. 265
*signal 266
The *signal command shall cause a signal to be sent to a job. Exactly two integer arguments must be specified 267
– the target job ID, and the signal number. 268
If the job ID is invalid, your program should emit the following to stdout: 269
Error: Invalid job
Reasons for a job number being invalid are: 270
• an invalid integer, e.g. “23a” 271
• an invalid job number (less than 1, greater than the total number of jobs) 272
1This will not be tested
7 Version 1.2
• the specified job is unrunnable has terminated or is otherwise invalid (reached maximum number of 273
restarts, input or output files could not be opened) 274
If the signal number is invalid (non-numeric, less than 1 or greater than 31) then your program should emit 275
the following to stdout: 276
Error: Invalid signal
If all arguments are valid, the signal shall be sent to the targetted job. (There is no need to check whether 277
the job is still running when the signal is actually sent.) 278
*sleep 279
The *sleep command shall cause jobthing to sleep for the specified number of milliseconds. Exactly one 280
non-negative integer argument must be provided. 281
If the sleep duration value is invalid (not a properly formed integer, or a negative value), your program 282
should emit the following to stdout: 283
Error: Invalid duration
If the arguments are valid, jobthing shall sleep for the required duration (in milliseconds). 284
Example jobthing Sessions 285
In this section we walk through a couple of increasingly more complex examples of jobthing’s behaviour. Note 286
however that these examples, like provided test-cases, are not exhaustive. You need to implement the program 287
specification as it is written, and not just code for these few examples. 288
Consider a config file once_cat.txt with following contents: 289
1 1:::cat
This defines a single job, running cat, to be launched once only, and stdin and stdout connected via pipes 290
to jobthing. We launch jobthing in verbose mode and interact with the job in some simple ways. Note that 291
text formatted in bold is entered and echoed on the terminal, it is not output of jobthing itself. 292
1 $./jobthing -v once_cat.txt
2 Registering worker 1:cat
3 Spawning worker 1
4 hello there
5 1<-'hello there'
6 1->'hello there'
7 this is some text
8 1<-'this is some text'
9 1->'this is some text'
Thus we see simple job startup, and text passing to and from the job. Next we can explore the *signal 293
command (continuing the same session): 294
10 *signal 0 11
11 Error: Invalid job
12 *signal 1 45
13 Error: Invalid signal
14 *signal 23a 45
15 Error: Invalid job
16 *signal 1 9
17 Worker 1 terminated due to signal 9
18 No more viable workers, exiting
Here after several invalid *signal command attempts, we finally send signal 9 to worker 1, which causes 295
its termination. jobthing then determined that this job should only be launched once, and that with no more 296
viable runnable jobs to run it terminates. 297
We next consider job input and output redirection, with the file cat_once_in_out.txt: 298
8 Version 1.2
1 1:/etc/services:./foo.out:cat
This job file runs a single job, cat, but it takes its standard input from /etc/services, and redirects its 299
output to ./foo.out. It runs only once. 300
Launching this job, in verbose mode, we see the following: 301
1 Registering worker 1: cat
2 Spawning worker 1
3 Worker 1 terminated with exit code 0
4 No more viable workers, exiting
In this example, we see that the process was spawned, but because its input was redirected from a file, the 302
cat process ran to completion almost immediately. This was detected by jobthing, which identified that no 303
further restarts should be attempted, and that no runnable jobs remained, so the program exits without pausing 304
for any user input. 305
Let’s now consider a more complex example, with multiple processes and different run counts. The example 306
configuration file is mixed_multicat.txt: 307
1 0:::cat
2 1:::cat
3 2:::cat
Here we have three jobs, all to run cat with their stdin and stdout connected via pipes to jobthing, 308
however each has a different number of restarts: zero (i.e. re-start endlessly), 1, and 2. 309
1 $./jobthing -v mixed_multicat.txt
2 Hello
3 1<-'Hello'
4 2<-'Hello'
5 3<-'Hello'
6 1->'Hello'
7 2->'Hello'
8 3->'Hello'
Entering a single line of input (’Hello’) has it sent to each job in turn, then that same string is returned 310
from each job by the cat process. 311
We then kill job number 2, and send some more input: 312
9 *signal 2 9
10 Worker 2 terminated due to signal 9
11 Hello again
12 1<-'Hello again'
13 3<-'Hello again'
14 1->'Hello again'
15 3->'Hello again'
Here we see that job 2 was terminated and not restarted (its restart count was only 1), and that the 313
subsequent input (Hello again) was then only sent to remaining live jobs (1 and 3). Let’s send a signal to job 314
number 3, and send some more input: 315
16 *signal 3 11
17 Worker 3 terminated due to signal 11
18 Restarting worker 3
19 foobar
20 1<-'foobar'
21 3<-'foobar'
22 1->'foobar'
23 3->'foobar'
And again: 316
9 Version 1.2
24 *signal 3 11
25 Worker 3 terminated due to signal 11
26 baz
27 1<-'baz'
28 1->'baz'
After the second signal, worker 3 has finally terminated and not restarted, and the input entered at the 317
console is sent only to worker 1. Since worker 1 has a restart count of zero (restart forever), we can send it as 318
many signals as we like, it will continue being restarted: 319
29 *signal 1 5
30 Worker 1 terminated due to signal 5
31 Restarting worker 1
32 *signal 1 6
33 Worker 1 terminated due to signal 6
34 Restarting worker 1
35 still there?
36 1<-'still there?'
37 1->'still there?'
Finally, let’s send SIGHUP to jobthing, and see the statistics reporting: 320
38 1:cat:2:4
39 2:cat:1:1
40 3:cat:2:3
Here we can see how many times each job was restarted (including expired ones like jobs 2 and 3), and how 321
many lines of input were sent to each. 322
Specification - mytee (CSSE7231 students only) 323
CSSE7231 students are to write an additional program, called mytee. mytee reads lines of input from stdin, 324
and writes them back out to stdout, and also to another file whose name is provided on the command line. By 325
default, mytee creates a new output file every time it is run, however this can be overridden by providing the 326
-a command line option. 327
Command Line Arguments 328
mytee requires one mandatory argument – the name of the output file, and accepts one optional argument. 329
These arguments may appear in any order. 330
./mytee [-a] outfile 331
• The optional -a argument puts mytee into append mode. In this mode, if the specified output file already 332
exists, then mytee shall append content to it (add it at the end). Otherwise, and by default, mytee shall 333
overwrite the outfile. 334
• The outfile argument specifies the name of the file to which the input received from stdin should be 335
written. 336
Operation and errors 337
Once the required output file has been opened for writing (and possibly appending, depending on the presence 338
or absence of the -a option), mytee shall sit in an endless loop reading input one line at a time from stdin. 339
Each line of input should then be written to the output file, and also written to stdout. All output should be 340
flushed immediately to ensure predictable operation. 341
Upon receiving EOF on stdin, mytee shall terminate immediately with exit code 0. 342
If mytee is run with an invalid command line (incorrect, missing or additional arguments), it shall emit the 343
following usage message to stderr, and exit with return code 1: 344
Usage: mytee [-a] outfile 345
10 Version 1.2
If mytee is unable to open the specified outfile for writing, it shall emit the follow to stderr, and return 346
exit code 2: 347
Error: unable to open for writing 348
where the string is replaced with the offending filename, for example 349
Error: unable to open /etc/services for writing 350
Provided Library: libcsse2310a3 351
A library has been provided to you with the following functions which your program may use. See the man 352
pages on moss for more details on these library functions. 353
char* read_line(FILE *stream); 354
The function attempts to read a line of text from the specified stream, allocating memory for it, and returning 355
the buffer. 356
char **split_line(char* line, char delimiter); 357
This function will split a line into substrings based on a given delimiter character. 358
char** split_space_not_quote(char *input, int *numTokens); 359
This function takes an input string and tokenises it according to spaces, but will treat text within double quotes 360
as a single token. 361
To use the library, you will need to add #include to your code and use the compiler flag 362
-I/local/courses/csse2310/include when compiling your code so that the compiler can find the include 363
file. You will also need to link with the library containing this function. To do this, use the compiler arguments 364
-L/local/courses/csse2310/lib -lcsse2310a3. 365
Style 366
Your program must follow version 2.2.0 of the CSSE2310/CSSE7231 C programming style guide available on 367
the course Blackboard site. 368
Hints 369
1. You may wish to consider the use of the standard library functions strtol(), and usleep() or nanosleep(). 370
2. While not mandatory, the provided library functions will make your life a lot easier – use them! 371
3. The standard Unix tee command behaves like cat, but also writes whatever it receives on stdin to a 372
file. This, combined with watch -n 1 cat in another terminal window, may be very helpful 373
when trying to figure out if you are setting up and using your pipes correctly. 374
4. You can examine the file descriptors associated with a process by running ls -l /proc/PID/fd where PID 375
is the process ID of the process. This may be helpful to ensure you are closing all required file descriptors 376
before executing jobs. 377
5. Review the lectures/contacts from weeks 6 and 7. These cover the basic concepts needed for this assign- 378
ment and the code samples may be useful. Similarly, the Ed Lessons exercises for weeks 6 and 7 may be 379
useful. 380
Suggested Approach 381
It is suggested that you write your program using the following steps. Test your program at each stage and 382
commit to your SVN repository frequently. Note that the specification text above is the definitive description 383
of the expected program behaviour. The list below does not cover all required functionality. 384
1. Write small test programs to figure out the correct usage of the system calls required for each jobthing 385
command – i.e. how to connect both stdin and stdout of a child process to pipes and manage access to 386
them from the parent. (This is essentially what the week 6 and 7 Ed Lessons exercises ask you to do.) 387
2. Write the initial job spawning capability of jobthing. 388
11 Version 1.2
3. Add the required input/output setup for each job. 389
4. Add the main loop functionality – implement the basic input/output functionality of jobthing first, and 390
make sure you can talk to the jobs. Then extend that to add command processing as a special case. 391
Forbidden Functions 392
You must not use any of the following C functions/statements. If you do so, you will get zero (0) marks for the 393
assignment. 394
• goto 395
• longjmp() and equivalent functions 396
• system() or popen() 397
• mkfifo() or mkfifoat() 398
Submission 399
Your submission must include all source and any other required files (in particular you must submit a Makefile). 400
Do not submit compiled files (e.g. .o files and compiled programs). 401
Your programs jobthing and mytee (CSSE7231 only) must build on moss.labs.eait.uq.edu.au with: 402
make 403
Your program must be compiled with gcc with at least the following options: 404
-pedantic -Wall -std=gnu99 405
You are not permitted to disable warnings or use pragmas to hide them. You may not use source files other 406
than .c and .h files as part of the build process – such files will be removed before building your program. 407
CSSE7231 only - The default target of your Makefile must cause both programs to be built2
. 408
If any errors result from the make command (i.e. no executable is created) then you will receive 0 marks 409
for functionality (see below). Any code without academic merit will be removed from your program before 410
compilation is attempted (and if compilation fails, you will receive 0 marks for functionality). 411
Your program must not invoke other programs or use non-standard headers/libraries other than those 412
explicity described in this specification. 413
Your assignment submission must be committed to your subversion repository under 414
https://source.eait.uq.edu.au/svn/csse2310-sem2-sXXXXXXX/trunk/a3 415
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 416
files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these 417
will not be considered in marking – they will not be checked out of your repository. 418
You must ensure that all files needed to compile and use your assignment (including a Makefile) are com- 419
mitted and within the trunk/a3 directory in your repository (and not within a subdirectory or some other part 420
of your repository) and not just sitting in your working directory. Do not commit compiled files or binaries. 421
You are strongly encouraged to check out a clean copy for testing purposes. 422
To submit your assignment, you must run the command 423
2310createzip a3 424
on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 425
available in the Assessment area on the CSSE2310/7231 Blackboard site)3
. The zip file will be named 426
sXXXXXXX_csse2310_a3_timestamp.zip 427
where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 428
the time that the zip file was created. 429
The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 430
ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your 431
2
If you only submit an attempt at one program then it is acceptable for just that single program to be built when running make.
3You may need to use scp or a graphical equivalent such as WinSCP, Filezilla or Cyberduck in order to download the zip file to
your local computer and then upload it to the submission site.
12 Version 1.2
Subversion commit history and a checksum of the zip file contents. You may be asked for your password as 432
part of this process in order to check out your submission from your repository. 433
You must not create the zip file using some other mechanism and you must not modify the zip file prior 434
to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file 435
is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 436
creation of your submission zip file. 437
We will mark your last submission, even if that is after the deadline and you made submissions before the 438
deadline. Any submissions after the deadline4 will incur a late penalty – see the CSSE2310/7231 course profile 439
for details. 440
Marks 441
Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked 442
to attend an interview about your assignment and you are unable to adequately respond to questions – see the 443
Student conduct section above. 444
Functionality (60 marks) 445
Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), and 446
your zip file has been generated correctly and has not been modified prior to submission, then you will earn 447
functionality marks based on the number of features your program correctly implements, as outlined below. 448
Partial marks will be awarded for partially meeting the functionality requirements. Not all features are of equal 449
difficulty. If your program does not allow a feature to be tested then you will receive 0 marks for 450
that feature, even if you claim to have implemented it. For example, if your program can never create a child 451
process then we can not test your communication with that job, or your ability to send it signals. Memory- 452
freeing tests require correct functionality also – a program that frees allocated memory but doesn’t implement 453
the required functionality can’t earn marks for this criteria. This is not a complete list of all dependencies, 454
other dependencies may exist also. If your program takes longer than 15 seconds to run any test, then it will be 455
terminated and you will earn no marks for the functionality associated with that test. The markers will make 456
no alterations to your code (other than to remove code without academic merit). 457
Functionality marks (out of 60) will be assigned for jobthing in the following categories (CSSE2310 and 458
CSSE7231): 459
1. jobthing correctly rejects invalid command lines and handles inability to open files (3 marks) 460
2. jobthing correctly starts jobs and sets up their input and output correctly (including pipes) 461
(includes handling comments in job files and invalid job specifications) (12 marks) 462
3. jobthing correctly handles jobthing standard input (or inputfile) text (non commands 463
and invalid commands) (9 marks) 464
4. jobthing correctly handles and identifies the termination of child jobs and their causes 465
(including restarting jobs when appropriate) (8 marks) 466
5. jobthing correctly closes all unnecessary file handles in child processes (4 marks) 467
6. jobthing correctly implements *signal command and argument error checking (7 marks) 468
7. jobthing correctly implements *sleep command and argument error checking (5 marks) 469
8. jobthing correctly handles SIGHUP and emits job statistics (5 marks) 470
9. jobthing correctly handles SIGPIPE and SIGINT as appropriate (2 marks) 471
10. jobthing frees all allocated memory prior to exit (when exiting under normal circumstances, 472
i.e. EOF received on jobthing’s stdin, or no viable jobs remain) (5 marks) 473
Note that verbose mode functionality is covered in multiple categories. 474
Functionality marks (out of 10) will be assigned for mytee in the following categories (CSSE7231 only): 475
4or your extended deadline if you are granted an extension.
13 Version 1.2
11. mytee correctly rejects invalid command lines (3 marks) 476
12. mytee correctly handles errors with output files (2 marks) 477
13. mytee correctly duplicates input onto stdout and the required output file (3 marks) 478
14. mytee correctly handles appending to output files (2 marks) 479
Some functionality may be assessed in multiple categories, e.g. the ability to launch jobs must be working to 480
test more advanced functionality. Your programs must not create any files other than those possibly specified 481
as output redirection for jobs, or files created by the jobs themselves. Doing otherwise may cause tests to fail. 482
Style Marking 483
Style marking is based on the number of style guide violations, i.e. the number of violations of version 2.2 of 484
the CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of 485
two components – automated style marks and human style marks. These are detailed below. 486
You should pay particular attention to commenting so that others can understand your code. The marker’s 487
decision with respect to commenting violations is final – it is the marker who has to understand your code. To 488
satisfy layout related guidelines, you may wish to consider the indent(1) tool. Your style marks can never be 489
more than your functionality mark – this prevents the submission of well styled programs which don’t meet at 490
least a minimum level of required functionality. 491
You are encouraged to use the style.sh tool installed on moss to style check your code before submission. 492
This does not check all style requirements, but it will determine your automated style mark (see below). Other 493
elements of the style guide are checked by humans. 494
All .c and .h files in your submission will be subject to style marking. This applies whether they are 495
compiled/linked into your executable or not5
. 496
Automated Style Marking (5 marks) 497
Automated style marks will be calculated over all of your .c and .h files as follows. If any of your submitted 498
.c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). 499
(Automated style marking can only be undertaken on code that compiles. The provided style.sh script checks 500
this for you.) 501
If your code does compile then your automated style mark will be determined as follows: Let 502
• W be the total number of distinct compilation warnings recorded when your .c files are individually built 503
(using the correct compiler arguments) 504
• A be the total number of style violations detected by style.sh when it is run over each of your .c and 505
.h files individually6
. 506
Your automated style mark S will be 507
S = 5 − (W + A) 508
If W +A ≥ 5 then S will be zero (0) – no negative marks will be awarded. Note that in some cases style.sh 509
may erroneously report style violations when correct style has been followed. If you believe that you have been 510
penalised incorrectly then please bring this to the attention of the course coordinator and your mark can be 511
updated if this is the case. Note also that when style.sh is run for marking purposes it may detect style 512
errors not picked up when you run style.sh on moss. This will not be considered a marking error – it is your 513
responsibility to ensure that all of your code follows the style guide, even if styling errors are not detected in 514
some runs of style.sh. 515
5Make sure you remove any unneeded files from your repository, or they will be subject to style marking.
6Every .h file in your submission must make sense without reference to any other files, e.g., it must #include any .h files that
contain declarations or definitions used in that .h file.
14 Version 1.2
Human Style Marking (5 marks) 516
The human style mark (out of 5 marks) will be based on the criteria/standards below for “comments”, “naming” 517
and “other”. The meanings of words like appropriate and required are determined by the requirements in the 518
style guide. Note that functions longer than 50 lines will be penalised in the automated style marking. Functions 519
that are also longer than 100 lines will be further penalised here. 520
Comments (2.5 marks) 521
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
522
Naming (1 mark) 523
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
524
Other (1.5 marks) 525
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
526
SVN commit history assessment (5 marks) 527
Markers will review your SVN commit history for your assignment up to your submission time. This element 528
will be graded according to the following principles: 529
• Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will 530
yield a score of zero for this section) 531
• Appropriate use of log messages to capture the changes represented by each commit. (Meaningful messages 532
explain briefly what has changed in the commit (e.g. in terms of functionality) and/or why the change 533
has been made and will be usually be more detailed for significant changes.) 534
The standards expected are outlined in the following rubric: 535
15 Version 1.2
Mark
(out of 5) Description
0
Minimal commit history – single commit OR
all commit messages are meaningless.
1
Some progressive development evident (more than one commit) OR
at least one commit message is meaningful.
2
Some progressive development evident (more than one commit) AND
at least one commit message is meaningful.
3
Progressive development is evident (multiple commits) AND
at least half the commit messages are meaningful.
4
Multiple commits that show progressive development of all functionality AND
meaningful messages for most commits.
5
Multiple commits that show progressive development of all functionality AND
meaningful messages for ALL commits.
536
Total Mark 537
Let 538
• F be the functionality mark for your assignment (out of 60 for CSSE2310, or 70 for CSSE7231). 539
• S be the automated style mark for your assignment (out of 5). 540
• H be the human style mark for your assignment (out of 5) 541
• C be the SVN commit history mark (out of 5) 542
Your total mark for the assignment will be: 543
M = F + min{F, S + H} + min{F, C} + min{F, D} 544
out of 75 (for CSSE2310 students) or 85 (for CSSE7231 students). 545
In other words, you can’t get more marks for style or SVN commit history or documentation than you do 546
for functionality. 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
with adequate time for students to respond prior to due date. Potential specification errors or omissions can be 552
discussed on the discussion forum or emailed to csse2310@uq.edu.au. 553
554
Version 1.1 555
• Added details of what should happen when inputfile (after -i argument) can not be opened (and where 556
inability to open files is covered in the marking criteria). 557
• Clarify what is meant by “no inputfile is specified”. 558
559
16 Version 1.2
Version 1.2 560
• Added details of spawning/restarting messages to be printed in verbose mode (to make the spec. consistent 561
with the examples). 562
• Added note that respawning may not be possible because it may not be possible to open required files. 563
• Clarified that mark category 2 includes handling comments in job files and invalid job specifications. 564
• Described another type of invalid job line. 565
• Clarified which jobs get “registered”/numbered (valid job lines). 566
• Use the terms “runnable” and “unrunnable” for jobs that resulted from valid job lines but are still able 567
to be run or not able to be run (replace previous overloaded use of “valid”/“invalid”). 568
• Made it clear that jobthing does not need to handle child execution failure in any special way. 569
• Removed redundant text about invalid text arguments for jobthing commands. 570
• Added clarification about sending signals to jobs that may have died. 571
• Added note that verbose mode functionality is covered in multiple categories. 572
• Clarified that handling of invalid commands is covered in category 3. 573
17 Version 1.2