Description
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 two programs – the first is called sigcat which is like the Unix utility cat, however it 4
has enhanced signal handling functionality. The second, and major program, is called hq, and it is used to 5
interactively spawn new processes, run programs, send and receive output and signals to those process, and 6
manage their lifecycle. The assignment will also test your ability to code to a programming style guide, to use 7
a revision control system appropriately, and document important design decisions (CSSE7231 only). 8
Student Conduct 9
This is an individual assignment. You should feel free to discuss general aspects of C programming and 10
the assignment specification with fellow students, including on the discussion forum. In general, questions like 11
“How should the program behave if hthis happensi?” would be safe, if they are seeking clarification on the 12
specification. 13
You must not actively help (or seek help from) other students or other people with the actual design, structure 14
and/or coding of your assignment solution. It is cheating to look at another student’s assignment code 15
and it is cheating to allow your code to be seen or shared in printed or electronic form by others. 16
All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or 17
collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if 18
you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your 19
code to a public place such as the course discussion forum or a public code repository, and do not allow others 20
to access your computer – you must keep your code secure. 21
Uploading or otherwise providing the assignment specification or part of it to a third party including online 22
tutorial and contract cheating websites is considered misconduct. The university is aware of these sites and 23
they cooperate with us in misconduct investigations. 24
You must follow the following code referencing rules for all code committed to your SVN repository (not 25
just the version that you submit): 26
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 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; 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). Copied code without
adjacent referencing will be considered misconduct and
action will be taken.
27
1 Version 1.2
The course coordinator reserves the right to conduct interviews with students about their submissions, for 28
the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from this 29
process. If you are not able to adequately explain your code or the design of your solution and/or be able to 30
make simple modifications to it as requested at the interview, then your assignment mark will be scaled down 31
based on the level of understanding you are able to demonstrate. 32
In short – Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. 33
Don’t be tempted to copy another student’s code or to use an online cheating service. You should read and 34
understand the statements on student misconduct in the course profile and on the school web-site: https: 35
//www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism 36
Specification – sigcat 37
sigcat reads one line at a time from stdin, and immediate writes and flushes that line to an output stream. 38
The output stream by default is stdout, however the output stream can be changed at runtime between stdout 39
and stderr by sending sigcat the SIGUSR1 and SIGUSR2 signals. 40
Full details of the required behaviour are provided below. 41
Command Line Arguments 42
Your program (sigcat) accepts no commandline arguments. 43
./sigcat 44
Any arguments that are provided can be silently ignored. 45
sigcat basic behaviour 46
Upon starting, sigcat shall enter an infinite loop reading newline-terminated lines or EOF-terminated non- 47
empty lines from standard input, and emitting them with newline termination to an output stream. It is 48
assumed that the data read from standard input is non-binary, i.e. does not contain null (\0) characters. See 49
the provided read_line() function, described on page 9. 50
• At program start, the output stream is to be standard output stdout. 51
• sigcat shall remain in this loop until it receives end of file on stdin. 52
• Upon reaching EOF on stdin, sigcat shall exit with exit code 0. 53
• No further error checking is required in sigcat. 54
sigcat signal handling 55
sigcat shall register a handler or handlers for all signals of numeric value 1 through to 31 inclusive – except 9 56
(KILL) and 19 (STOP) which are not able to be caught. 57
Upon receiving a signal, sigcat is to emit, to the current output stream, the following text: 58
59
sigcat received
where
Note that this line is terminated by a newline and sigcat must flush its output buffer after every emitted line 62
of text. 63
Examples include: 64
sigcat received Quit
sigcat received Hangup
The signals SIGUSR1 and SIGUSR2 have special meaning to sigcat. After printing the output as specified 65
above, upon receipt of either of these signals sigcat shall further 66
• set its output stream to standard output (stdout) if SIGUSR1 is received 67
• set its output stream to standard error (stderr) if SIGUSR2 is received 68
2 Version 1.2
In this way, sigcat can be instructed to direct its output to either stdout or stderr by sending it the 69
appropriate signals. 70
Specification – hq 71
hq reads commands from its standard input one line at a time. All of hq’s output goes to stdout– and all 72
commands are terminated by a single newline. The commands are documented below, and allow the user to 73
run programs, send them signals, manage their input and output streams, report on their status and so on. 74
Full details of the required behaviour are provided below. 75
Command Line Arguments 76
hq accepts no commandline arguments. 77
./hq 78
Any arguments that are provided may be silently ignored. 79
hq basic behaviour 80
hq prints and flushes a prompt “> ” (greater than symbol followed by a single space) to stdout then waits to read 81
a command from stdin. The command will be newline-terminated or EOF-terminated – see the read_line() 82
function described on page 9. 83
The following table describes the commands that must be implemented by hq, and their syntax. Additional 84
notes on each command will follow. 85
Command Usage Comments
spawn
spawn
[
Run
spaces may be quoted in double quotes. The new process’s
stdin and stdout must be connected to hq by pipes, so that
they can be accessed with the send and rvc commands. The
new process’s stderr should be unchanged.
report report [
provided
signal signal
(
sleep sleep
send send
containing spaces must be quoted with double quotes.
rcv rcv
display it to hq’s stdout.
eof eof
cleanup cleanup Terminate and reap all child processes spawned by hq by sending
them signal 9 (SIGKILL).
86
The following apply to all command handling and inputs: 87
• Upon reaching EOF on stdin, hq shall terminate and clean up any jobs (see the cleanup command 88
below), and exit with status 0. 89
• hq shall block or otherwise ignore SIGINT (Control-C). 90
• Any invalid commands provided to hq (i.e. a word at the start of a line is not one of the above) shall 91
result in the following message to stdout: 92
Error: Invalid command
Note that empty input lines (user just presses return) shall just result in the prompt being printed again. 93
3 Version 1.2
• All commands have a minimum number of arguments (possibly zero such as for report and cleanup). 94
If this minimum number of arguments is not provided, the following error message shall be emitted to 95
standard output: 96
Error: Insufficient arguments
Extraneous arguments, if provided, shall be silently ignored. 97
• All numerical arguments, if present, must be complete and valid numbers. e.g. “15” is a valid integer, 98
but “15a” is not. Similarly, “2.7” is a valid floating point value, but “2.7foobar” is not. Your program 99
must correctly identify and report invalid numerical arguments (see details below for each command). 100
Leading whitespace characters are permitted, e.g. “ 10” is a valid number – these whitespace characters 101
are automatically skipped over by functions like strtol() and strtod(). 102
• Any text arguments, including strings and program names, may contain spaces if the argument is sur- 103
rounded by double quotation marks, e.g. “text with spaces”. A line with an odd number of double 104
quotes will be treated as though there is an additional double quote at the end of the line1
. A helper 105
function is provided to assist you with quote-delimited parsing, see the “Provided Library” section on 106
page 9 for usage details. 107
• One or more spaces may be present before the command and there may be more than one space between 108
arguments. The provided helper function will deal with this for you. 109
• Where a command takes a jobID argument then a valid jobID is the ID of any job created using spawn– 110
even if the execution failed or the job has exited. 111
spawn 112
The spawn command shall cause hq to fork() a new process, setup pipes such that the child’s stdin and 113
stdout are directed from/to hq, and exec() the requested program. The $PATH variable is to be searched for 114
executable programs. 115
Each spawned process is to be allocated an integer job identifier (jobID), starting from zero. Jobs are created 116
and job IDs should increment even if the exec() call fails. 117
hq should emit the following to stdout: 118
New Job ID [N] created
where N is replaced by the integer value, e.g. 119
New Job ID [34] created
If at least one argument is not provided (the program name), then spawn shall emit the following message: 120
Error: Insufficient arguments
If the exec() call fails then your child process is to exit with exit status 99. 121
report 122
The report command shall output information on all jobs spawned so far, with a header row and in the following 123
format: 124
> report
[Job] cmd:status
[0] cat:running
[1] ls:exited(0)
[2] sleep:signalled(9)
…
1This will not be tested
4 Version 1.2
The cmd field shall be the name of the job (the value of the first argument given to the spawn command). 125
The status field shall be one of running – if the job has not yet exited; exited – if the job has terminated 126
normally – with the exit status shown in parentheses; or signalled – if the job terminated due to a signal – 127
with the signal number shown in parentheses. Jobs are to be reported in numerical order. 128
report may optionally take a single integer argument, which is a job ID. If provided, and valid, then only 129
the status of that job shall be reported. (The header line is also output.) 130
> report 1
[Job] cmd:status
[1] ls:exited(0)
If an invalid job ID is provided (i.e. non-numerical value or job was never spawned), then an error message 131
is to be emitted to standard output as demonstrated below: 132
> report 45
Error: Invalid job
> report abc
Error: Invalid job
signal 133
The signal command shall cause a signal to be sent to a job. Exactly two integer arguments must be specified 134
– the target job ID, and the signal number. If fewer arguments are provided, the following error is emitted: 135
Error: Insufficient arguments
If the job ID is invalid, emit: 136
Error: Invalid job
If the signal number is invalid (non-numeric, less than 1 or greater than 31): 137
Error: Invalid signal
If all arguments are valid, the signal shall be sent to the targetted job. (There is no need to check whether 138
the job is still running.) 139
sleep 140
The sleep command shall cause the hq program to sleep for the number of seconds specified in its single 141
mandatory argument. Non-integer numbers, such as 1.5, are considered valid2
. 142
If no duration is provided, emit the error message: 143
Error: Insufficient arguments
If a negative or non-numerical duration is provided, emit the error message to stdout: 144
Error: Invalid sleep time
send 145
The send command shall send a single line of text, whose contents are the second argument to the command, 146
to the identified job. (The line that is sent is terminated with a newline character.) Send requires exactly two 147
arguments, the job ID and the string to be sent. Because arguments are separated by spaces, to send a line 148
containing spaces, the text must be contained in double quotes. A helper function is provided to assist you with 149
quote-delimited parsing, see see the “Provided Library” section on page 9 for usage details. 150
If less than two arguments are provided, send shall emit: 151
Error: Insufficient arguments
If an invalid job ID is provided, emit the error message: 152
2The strtod() function may prove useful here
5 Version 1.2
Error: Invalid job
Example of usage: 153
> send 0 “hello job, quotes matter!”
> send 2 textwithoutspaces
> send 1 “”
> send 4 text with spaces but these extra words are all ignored
It is possible that the receiving process has exited – it is your job to manage any SIGPIPE signals so that 154
your program does not terminate in this situation. You are not required to detect or report if a job specified in 155
a send command is in this state – simply ensure that hq continues to run. 156
rcv 157
rcv shall attempt to read one line of text from the identified job, and print it to standard output. One mandatory 158
argument is required – the job ID. If not specified, then emit 159
Error: Insufficient arguments
If an invalid job ID is specified, emit 160
Error: Invalid job
rcv must not block if there is no output available from the job. To facilitate this, a helper function 161
is_ready() is provided – see the “Provided Library” section on page 9. 162
If there is no output available to read from the job, rcv shall emit 163
If end-of-file is (or has previously been) received from the pipe connected to the job, then rcv shall emit 164
Otherwise, rcv shall emit to standard output, the line of text read from the job, e.g. 165
> rcv 0
Hello from the job!
Lines read from the given job will be newline-terminated or non-empty EOF-terminated lines and should be 166
emitted with a terminating newline character. See the read_line() function described on page 9. 167
eof 168
The eof command shall close the stdin of the given job. One mandatory argument is required – the job ID. If 169
not specified, then emit 170
Error: Insufficient arguments
If an invalid job ID is specified, eof shall emit 171
Error: Invalid job
If the job ID is valid, hq does not output anything. 172
cleanup 173
The cleanup command shall send the SIGKILL (numerical value 9) signal to all jobs and wait() or waitpid() 174
on them to reap zombies. 175
6 Version 1.2
Example hq Sessions 176
1 $ ./hq
2 > spawn cat /etc/resolv.conf
3 New Job ID [0] created
4 > report
5 [Job] cmd:status
6 [0] cat:exited(0)
7 > rcv 0
8 # Generated by NetworkManager
9 > rcv 0
10 search labs.eait.uq.edu.au eait.uq.edu.au
11 > rcv 0
12 nameserver 130.102.71.160
13 > rcv 0
14 nameserver 130.102.71.161
15 > rcv 0
16
17 > send 0 foobar
18 > send 0 “anybody there?”
19 > rcv 0
20
21 >
Even though the cat process has exited almost immediately, its output has been buffered in the connecting 177
pipe and can still be read. Note also that the send command is sending down a pipe that has nothing listening 178
on the other end. The kernel will be sending SIGPIPE to hq but these are being handled / ignored. 179
In the next example, we spawn a process running cat which will be expecting input on stdin, and sending 180
it back to stdout. hq can be used to manage this with the send and rcv commands: 181
1 $ ./hq
2 > spawn cat
3 New Job ID [0] created
4 > report
5 [Job] cmd:status
6 [0] cat:running
7 > rcv 0
8
9 > send 0 “hello world”
10 > rcv 0
11 hello world
12 > report
13 [Job] cmd:status
14 [0] cat:running
15 > send 0 “line 1” extra args
16 > send 0 “line 2”
17 > rcv 0
18 line 1
19 > rcv 0
20 line 2
21 >
Next we illustrate the use and effects of the signal command: 182
1 $ ./hq
2 > spawn cat
3 New Job ID [0] created
4 > report
5 [Job] cmd:status
6 [0] cat:running
7 Version 1.2
7 > signal 0 9
8 > report
9 [Job] cmd:status
10 [0] cat:signalled(9)
All of these examples had only a single job, however hq must be able to keep an arbitrary number of jobs in 183
flight at once: 184
1 $ ./hq
2 > spawn cat /etc/services
3 New Job ID [0] created
4 > spawn cat /etc/passwd
5 New Job ID [1] created
6 > spawn cat
7 New Job ID [2] created
8 > report
9 [Job] cmd:status
10 [0] cat:running
11 [1] cat:exited(0)
12 [2] cat:running
13 > rcv 0
14 # /etc/services:
15 > send 2 “hello world”
16 > rcv 1
17 root:x:0:0:root:/root:/bin/bash
18 > rcv 2
19 hello world
20 > rcv 2
21
22 > eof 2
23 > rcv 2
24
25 > report
26 [Job] cmd:status
27 [0] cat:running
28 [1] cat:exited(0)
29 [2] cat:exited(0)
In this example, jobs 0 and 1 were simply catting files. Job 1 ran and terminated almost immediately, but 185
job 0 did not because the file being cat’ed was larger than the pipe buffer so cat was blocked on output. Job 186
2 was a cat blocking on standard input, and we interacted with it using send and rcv. We then send job 2 an 187
end-of-file with the eof command, and confirmed using report that job 2 had now also exited, having come to 188
end of file on input. 189
Here is an example of hq and sigcat interacting: 190
1 > spawn ./sigcat
2 New Job ID [0] created
3 > send 0 “Hello sigcat”
4 > rcv 0
5 Hello sigcat
6 > signal 0 1
7 > rcv 0
8 sigcat received Hangup
9 > signal 0 12
10 > signal 0 1
11 > sigcat received Hangup
12 rcv 0
13 sigcat received User defined signal 2
14 > report
15 [Job] cmd:status
8 Version 1.2
16 [0] ./sigcat:running
There are some very important subtleties demonstrated in this example: 191
• We spawn the sigcat process (line 1), send it some text (line 3) and then read it back (lines 4 & 5). 192
• We then send it signal 1 (SIGHUP) on line 6, and read back the output triggered by that signal (lines 7 & 193
8). Remember that by default, sigcat emits its output to stdout, which is captured by hq and accessible 194
only via the rcv command. 195
• on line 9, we send signal 12 (SIGUSR2), which causes sigcat to emit the signal message to stdout, but 196
then switch its output stream to stderr . 197
• When we then resend signal 1 (line 10), the output message from sigcat (underlined here) appears imme- 198
diately on the console – because it’s emitted over stderr and this stream is not captured by hq. 199
• There is no prompt before the input on line 12 because the prompt is shown on line 11 (it was output 200
before the message to stderr). 201
Provided Library: libcsse2310a3 202
A library has been provided to you with the following functions which your program may use. See the man 203
pages on moss for more details on these library functions. 204
char* read_line(FILE *stream); 205
The function attempts to read a line of text from the specified stream, allocating memory for it, and returning 206
the buffer. 207
char* int is_ready(int fd); 208
This function will detect if there is any data available to read on the specified file descriptor, returning 0 (no 209
input) or 1 (input available) accordingly. You will need to use this to prevent your rcv command blocking. 210
char** split_space_not_quote(char *input, int *numTokens); 211
This function takes an input string and tokenises it according to spaces, but will treat text within double quotes 212
as a single token. 213
To use the library, you will need to add #include
-I/local/courses/csse2310/include when compiling your code so that the compiler can find the include 215
file. You will also need to link with the library containing this function. To do this, use the compiler arguments 216
-L/local/courses/csse2310/lib -lcsse2310a3. 217
Style 218
Your program must follow version 2.2.0 of the CSSE2310/CSSE7231 C programming style guide available on 219
the course Blackboard site. 220
Hints 221
1. You may wish to consider the use of the standard library functions strtod(), strtol(), strsignal() 222
and usleep() or nanosleep(). 223
2. While not mandatory, the provided library functions will make your life a lot easier – use them! The 224
read_line() function can be used by both hq and sigcat when reading from stdin and within the rcv 225
command when reading from a job. 226
3. The standard Unix tee command behaves like cat, but also writes whatever it receives on stdin to a 227
file. This, combined with watch -n 1 cat
when trying to figure out if you are setting up and using your pipes correctly. You can also examine the 229
file descriptors associated with a process by running ls -l /proc/PID/fd where PID is the process id of 230
the process. 231
4. Review the lectures/contacts from weeks 5 and 6. These cover the basic concepts needed for this assign- 232
ment and the code samples may be useful. 233
9 Version 1.2
Suggested Approach 234
It is suggested that you write your program using the following steps. Test your program at each stage and 235
commit to your SVN repository frequently. Note that the specification text above is the definitive description 236
of the expected program behaviour. The list below does not cover all required functionality. 237
1. Write sigcat first. It will be useful for testing hq later. 238
2. Write small test programs to figure out the correct usage of the system calls required for each hq command 239
– i.e. how to connect both stdin and stdout of a child process to pipes and manage access to them from 240
the parent. 241
3. Prototype the overall command loop of hq first, and work out how to parse input lines into tokens. You 242
can then implement each command (spawn, report etc) incrementally, using knowledge you gained from 243
step 2 above. 244
Forbidden Functions 245
You must not use any of the following C functions/statements. If you do so, you will get zero (0) marks for the 246
assignment. 247
• goto 248
• longjmp() and equivalent functions 249
• system() 250
• mkfifo() or mkfifoat() 251
Submission 252
Your submission must include all source and any other required files (in particular you must submit a Makefile). 253
Do not submit compiled files (e.g. .o files and compiled programs). 254
Your programs (named sigcat and hq) must build on moss.labs.eait.uq.edu.au with: 255
make 256
Your programs must be compiled with gcc with at least the following options: 257
-pedantic -Wall -std=gnu99 258
You are not permitted to disable warnings or use pragmas to hide them. You may not use source files other 259
than .c and .h files as part of the build process – such files will be removed before building your program. 260
The default target of your Makefile must cause both programs to be built3
. 261
If any errors result from the make command (i.e. no executable is created) then you will receive 0 marks 262
for functionality (see below). Any code without academic merit will be removed from your program before 263
compilation is attempted (and if compilation fails, you will receive 0 marks for functionality). 264
Your program must not invoke other programs or use non-standard headers/libraries. 265
Your assignment submission must be committed to your subversion repository under 266
https://source.eait.uq.edu.au/svn/csse2310-sem1-sXXXXXXX/trunk/a3 267
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 268
files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these 269
will not be considered in marking – they will not be checked out of your repository. 270
You must ensure that all files needed to compile and use your assignment (including a Makefile) are commit- 271
ted and within the trunk/a3 directory in your repository (and not within a subdirectory) and not just sitting 272
in your working directory. Do not commit compiled files or binaries. You are strongly encouraged to check out 273
a clean copy for testing purposes. 274
To submit your assignment, you must run the command 275
2310createzip a3 276
3
If you only submit an attempt at one program then it is acceptable for just that single program to be built when running make.
10 Version 1.2
on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 277
available in the Assessment area on the CSSE2310/7231 Blackboard site)4
. The zip file will be named 278
sXXXXXXX_csse2310_a3_timestamp.zip 279
where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 280
the time that the zip file was created. 281
The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 282
ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your 283
Subversion commit history and a checksum of the zip file contents. You may be asked for your password as 284
part of this process in order to check out your submission from your repository. 285
You must not create the zip file using some other mechanism and you must not modify the zip file prior 286
to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file 287
is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 288
creation of your submission zip file. 289
We will mark your last submission, even if that is after the deadline and you made submissions before the 290
deadline. Any submissions after the deadline5 will incur a late penalty – see the CSSE2310/7231 course profile 291
for details. 292
Marks 293
Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked 294
to attend an interview about your assignment and you are unable to adequately respond to questions – see the 295
Student conduct section above. 296
Functionality (60 marks) 297
Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), and 298
your zip file has been generated correctly and has not been modified prior to submission, then you will earn 299
functionality marks based on the number of features your program correctly implements, as outlined below. 300
Partial marks will be awarded for partially meeting the functionality requirements. Not all features are of equal 301
difficulty. If your program does not allow a feature to be tested then you will receive 0 marks for 302
that feature, even if you claim to have implemented it. For example, if your program can never create a child 303
process (spawn) then we can not test your communication with that job (send, rcv), nor can we test the report 304
command. If your program doesn’t prompt for input correctly then it is likely all hq tests will fail. The report 305
functionality is required to test many of the other hq commands. Some rcv tests require send functionality to 306
be working. Memory-freeing tests require correct functionality also – a program that frees allocated memory 307
but doesn’t implement the required functionality can’t earn marks for this criteria. This is not a complete list 308
of all dependencies, other dependencies may exist also. If your program takes longer than 15 seconds to run 309
any test, then it will be terminated and you will earn no marks for the functionality associated with that test. 310
The markers will make no alterations to your code (other than to remove code without academic merit). 311
Marks will be assigned in the following categories. 312
1. sigcat correctly copies its input to stdout (3 marks) 313
2. sigcat correctly outputs messages upon receiving signals (3 marks) 314
3. sigcat correctly changes output streams upon receipt of SIGUSR1 and SIGUSR2 (4 marks) 315
4. hq correctly rejects invalid commands (3 marks) 316
5. hq correctly implements spawn command (6 marks) 317
6. hq correctly implements report command (7 marks) 318
7. hq correctly implements sleep command (4 marks) 319
8. hq correctly implements send command (6 marks) 320
9. hq correctly implements eof command (3 marks) 321
4You 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.
5or your extended deadline if you are granted an extension.
11 Version 1.2
10. hq correctly implements rcv command (6 marks) 322
11. hq correctly implements signal command (4 marks) 323
12. hq correctly implements cleanup command and cleans up on exit (4 marks) 324
13. hq correctly handles SIGPIPE and SIGINT as appropriate (2 marks) 325
14. hq frees all allocated memory prior to exit (when exiting under normal circumstances, 326
i.e. EOF received on hq’s stdin) (5 marks) 327
Some functionality may be assessed in multiple categories, e.g. the ability to tokenise strings containing spaces 328
and within quotes. Your programs must not create any files, temporary or otherwise. Doing so may cause tests 329
to fail. 330
Style Marking 331
Style marking is based on the number of style guide violations, i.e. the number of violations of version 2.2 of 332
the CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of 333
two components – automated style marks and human style marks. These are detailed below. 334
You should pay particular attention to commenting so that others can understand your code. The marker’s 335
decision with respect to commenting violations is final – it is the marker who has to understand your code. To 336
satisfy layout related guidelines, you may wish to consider the indent(1) tool. Your style marks can never be 337
more than your functionality mark – this prevents the submission of well styled programs which don’t meet at 338
least a minimum level of required functionality. 339
You are encouraged to use the style.sh tool installed on moss to style check your code before submission. 340
This does not check all style requirements, but it will determine your automated style mark (see below). Other 341
elements of the style guide are checked by humans. 342
All .c and .h files in your submission will be subject to style marking. This applies whether they are 343
compiled/linked into your executable or not6
. 344
Automated Style Marking (5 marks) 345
Automated style marks will be calculated over all of your .c and .h files as follows. If any of your submitted 346
.c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). 347
(Automated style marking can only be undertaken on code that compiles. The provided style.sh script checks 348
this for you.) 349
If your code does compile then your automated style mark will be determined as follows: Let 350
• W be the total number of distinct compilation warnings recorded when your .c files are individually built 351
(using the correct compiler arguments) 352
• A be the total number of style violations detected by style.sh when it is run over each of your .c and 353
.h files individually7
. 354
Your automated style mark S will be 355
S = 5 − (W + A) 356
If W +A ≥ 5 then S will be zero (0) – no negative marks will be awarded. Note that in some cases style.sh 357
may erroneously report style violations when correct style has been followed. If you believe that you have been 358
penalised incorrectly then please bring this to the attention of the course coordinator and your mark can be 359
updated if this is the case. Note also that when style.sh is run for marking purposes it may detect style 360
errors not picked up when you run style.sh on moss. This will not be considered a marking error – it is your 361
responsibility to ensure that all of your code follows the style guide, even if styling errors are not detected in 362
some runs of style.sh. 363
6Make sure you remove any unneeded files from your repository, or they will be subject to style marking.
7Every .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.
12 Version 1.2
Human Style Marking (5 marks) 364
The human style mark (out of 5 marks) will be based on the criteria/standards below for “comments”, “naming” 365
and “other”. The meanings of words like appropriate and required are determined by the requirements in the 366
style guide. Note that functions longer than 50 lines will be penalised in the automated style marking. Functions 367
that are also longer than 100 lines will be further penalised here. 368
Comments (2.5 marks) 369
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
370
Naming (1 mark) 371
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
372
Other (1.5 marks) 373
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
374
SVN commit history assessment (5 marks) 375
Markers will review your SVN commit history for your assignment up to your submission time. This element 376
will be graded according to the following principles: 377
• Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will 378
yield a score of zero for this section) 379
• Appropriate use of log messages to capture the changes represented by each commit. (Meaningful messages 380
explain briefly what has changed in the commit (e.g. in terms of functionality) and/or why the change 381
has been made and will be usually be more detailed for significant changes.) 382
The standards expected are outlined in the following rubric: 383
13 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.
384
Design Documentation (10 marks) – for CSSE7231 students only 385
CSSE7231 students must submit a PDF document containing a written overview of the architecture and design 386
of your program. This must be submitted via the Turnitin submission link on Blackboard. 387
Please refer to the grading criteria available on BlackBoard under “Assessment” for a detailed breakdown 388
of how these submissions will be marked. Note that your submission time for the whole assignment will be 389
considered to be the later of your submission times for your zip file and your PDF design document. Any late 390
penalty will be based on this submission time and apply to your whole assignment mark. 391
This document should describe, at a general level, the functional decomposition of the program, the key design 392
decisions you made and why you made them. It must meet the following formatting requirements: 393
• Maximum two A4 pages in 12 point font 394
• Diagrams are permitted up to 25% of the page area. The diagram(s) must be discussed in the text, it is 395
not ok to just include a figure without explanatory discussion. 396
Don’t overthink this! The purpose is to demonstrate that you can communicate important design decisions, 397
and write in a meaningful way about your code. To be clear, this document is not a restatement of the program 398
specification – it is a discussion of your design and your code. 399
If your documentation obviously does not match your code, you will get zero for this compo- 400
nent, and will be asked to explain why. 401
Total Mark 402
Let 403
• F be the functionality mark for your assignment (out of 60). 404
• S be the automated style mark for your assignment (out of 5). 405
• H be the human style mark for your assignment (out of 5). 406
• C be the SVN commit history mark (out of 5). 407
• D be the documentation mark for your assignment (out of 10 for CSSE7231 students) – or 0 for CSSE2310 408
students. 409
Your total mark for the assignment will be: 410
M = F + min{F, S + H} + min{F, C} + min{F, D} 411
out of 75 (for CSSE2310 students) or 85 (for CSSE7231 students). 412
In other words, you can’t get more marks for style or SVN commit history or documentation than you do 413
for functionality. Pretty code that doesn’t work will not be rewarded! 414
Late Penalties 415
Late penalties will apply as outlined in the course profile. 416
14 Version 1.2
Specification Updates 417
Any errors or omissions discovered in the assignment specification will be added here, and new versions released 418
with adequate time for students to respond prior to due date. Potential specification errors or omissions can be 419
discussed on the discussion forum or emailed to csse2310@uq.edu.au. 420
421
Version 1.1 422
• Fixed signature of is_ready() function to match man page. 423
• Clarified that EOF-terminated non-empty lines are to be treated the same as newline-terminated lines 424
and added a further hint about the read_line() function. 425
• Clarified that leading spaces are permitted in numerical arguments (to match the functionality of strtod() 426
and strtol(). 427
• Clarified how non-matching double quotes are handled (to match the functionality of the provided 428
split_space_not_quote() function. 429
• Noted some dependencies between commands to be tested. 430
• Noted that the cleanup criteria also includes cleaning up when hq is exited. 431
• Added hint text about examining file descriptors associated with a process. 432
• Added clarification that programs are not to create temporary files. 433
434
Version 1.2 435
• Clarified that waitpid() can be used in cleanup – it doesn’t have to be wait(). 436
• Clarified that the send command also sends a newline after the text. 437
• Clarified that freeing memory is only needed on normal exit from hq. 438
15 Version 1.2
