Description
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 60 where is replaced with the signal name as reported by strsignal() (declared in ). 61 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 in a new process, optionally the with arguments provided. Arguments or program names containing 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 [] Report on the status of or all jobs if no argument provided signal signal Send the signal ( – an integer) to the given job (). sleep sleep Cause hq to sleep for the number of seconds specified. may be fractional, e.g. sleep 1.5 send send Send to the job with a terminating newline. Strings containing spaces must be quoted with double quotes. rcv rcv Attempt to read one line of text from the job specified and display it to hq’s stdout. eof eof Close the pipe connected to the specified job’s stdin, thus causing that job to receive EOF on its next read attempt. 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 to your code and use the compiler flag 214 -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 in another terminal window, may be very helpful 228 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
