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