The University of Queensland
School of Electrical Engineering and Computer Science
CSSE2310/CSSE7231 — Semester 1, 2024
Assignment 3 (version 1.2)
Marks: 75
Weighting: 15%
Due: 4:00pm Friday 3 May, 2024
Do not share this document. Sharing this document may result in a misconduct penalty.
Specification changes from version 1.0 to version 1.1 are shown in red. Specification changes from version 1.1
to version 1.2 are shown in blue. All 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 2
and communication concepts (pipes and signals), and to further develop your C programming skills with a 3
moderately complex program. 4
You are to create a program (called uqfindexec) which allows users to run a specified command, or a 5
pipeline of commands, on all files in a given directory. (This is similar to the -exec functionality available with 6
the Linux find command.) The assignment will also test your ability to code to a particular programming style 7
guide, and to use a revision control system appropriately. 2655 8
CSSE7231 students will be required to implement additional functionality for full marks. 9
Student Conduct 10
This section is unchanged from assignment one – but you should remind yourself of the referencing requirements. 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 person’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. (Code in private posts
to the discussion forum is permitted.) You must assume that some students in the course may have very long 23
extensions so do not post your code to any public repository until at least three months after the result release 24
date for the course (or check with the course coordinator if you wish to post it sooner). Do not allow others to 25
access your computer – you must keep your code secure. Never leave your work unattended. 26
You must follow the following code usage and referencing rules for all code committed to your SVN 27
repository (not just the version that you submit): 28
Code Origin Usage/Referencing
Code provided to you in writing this semester by
CSSE2310/7231 teaching staff (e.g. code hosted on Black-
board, found in /local/courses/csse2310/resources
on moss, posted on the discussion forum by teaching staff,
provided in Ed Lessons, or shown in class).
May be used freely without reference. (You must be able
to point to the source if queried about it – so you may
find it easier to reference the code.)
Code you have personally written this semester for
CSSE2310/7231 (e.g. code written for A1 reused in A3)
– provided you have not shared or published it.
May be used freely without reference. (This assumes that
no reference was required for the original use.)
© 2024 The University of Queensland 1 Version 1.2
Code Origin Usage/Referencing
Code you have personally written in a previous enrolment
in this course or in another EECS course and where that
code has not been shared with any other person or pub-
lished in any way.
May be used provided you understand the code AND
the source of the code is referenced in a comment
adjacent to that code (in the required format – see the
style guide). If such code is used without appropriate
referencing then this will be considered misconduct.Code examples found in man pages on moss.
Code copied from any website or forum (including Stack-
Overflow and CSDN), code copied from any public or
private repositories; code copied from textbooks. (This
includes code in other programming languages that has
been converted to C.)
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 re-
moved 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 consid-
ered misconduct and action will be taken.
Examples, websites, code (in any programming language),
etc. that you have learned from or that you have taken
inspiration from or based any part of your code on but
have not copied or just converted from another program-
ming language. This includes learning about individual
functions that are not covered in class.
May be used provided you do not directly copy code AND
you understand the code AND the source of the code or
inspiration or learning is referenced in a comment adjacent
to that code (in the required format – see the style guide).
If such code is used without appropriate referencing then
this will be considered misconduct.
Code written by, modified by, obtained from or based on
code output by a code generation tool (including any ar-
tificial intelligence tool) that you alone personally have
interacted with, without the assistance of another person.
This includes code you wrote but then modified or de-
bugged because of your interaction with such a tool. It
also includes where comments are written by such a tool
– comments are part of your code.
May be used provided you understand that code AND the
source of the code is referenced in a comment adjacent to
that code (in the required format) AND an ASCII text
file (named toolHistory.txt) is included in your repos-
itory and with your submission that describes in detail
how the tool was used. The file must be committed to
the repository at the same time as any code derived from
such a tool. If such code is used without appropriate refer-
encing and without inclusion of the toolHistory.txt file
then this will be considered misconduct. See the detailed
AI tool use documentation requirements on Blackboard –
this tells you what must be in the toolHistory.txt file.
Other code – includes (but may not be limited to): code
provided by teaching staff only in a previous offering of
this course (e.g. previous assignment one solution); any
code written by or partially written by someone else or
with the assistance of someone else; and any code you
have written that is available to other students.
May not be used. If the source of the code is referenced
adjacent to the code then this will be considered code
without academic merit (not misconduct) and will be re-
moved 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 consid-
ered misconduct and action will be taken.
You must not share this assignment specification with any person (other than course staff), organ- 29
isation, website, etc. Uploading or otherwise providing the assignment specification or part of it to a third 30
party including online tutorial and contract cheating websites is considered misconduct. The university is aware 31
of many of these sites and many cooperate with us in misconduct investigations. You are permitted to post 32
small extracts of this document to the course Ed Discussion forum for the purposes of seeking or providing 33
clarification on this specification. 34
The teaching staff will conduct interviews with a subset of students about their submissions, 35
for the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from 36
this process. If you legitimately use code from other sources (following the usage/referencing requirements in the 37
table above) then you are expected to understand that code. If you are not able to adequately explain the design 38
of your solution and/or adequately explain your submitted code (and/or earlier versions in your repository) 39
and/or be able to make simple modifications to it as requested at the interview, then your assignment mark will 40
be scaled down based on the level of understanding you are able to demonstrate and/or your submission may 41
be subject to a misconduct investigation where your interview responses form part of the evidence. Failure to 42
attend a scheduled interview will result in zero marks for the assignment unless there are documented exceptional 43
circumstances that prevent you from attending. 44
Students will be selected for interview based on a number of factors that may include (but are not limited 45
to): 46
• Feedback from course staff based on observations in class, on the discussion forum, and during marking; 47
• An unusual commit history (versions and/or messages), e.g. limited evidence of progressive development; 48
• Variation of student performance, code style, etc. over time; 49
© 2024 The University of Queensland 2 Version 1.2
• Use of unusual or uncommon code structure/functions etc.; 50
• Referencing, or lack of referencing, present in code; 51
• Use of, or suspicion of undocumented use of, artificial intelligence or other code generation tools; and 52
• Reports from students or others about student work. 53
In short – Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. 54
Don’t be tempted to copy another student’s code or to use an online cheating service. Don’t help another 55
CSSE2310/7231 student with their code no matter how desperate they may be and no matter how close your 56
relationship. You should read and understand the statements on student misconduct in the course profile and 57
on the school website: https://eecs.uq.edu.au/current-students/guidelines-and-policies-students/ 58
student-conduct. 59
Specification 60
The uqfindexec program will execute a specified command, or pipeline of commands, for each file found in a 61
specified directory. If the string {} appears in the command(s) then it will be replaced by the name of the file 62
being processed. For example, running 63
uqfindexec --dir /etc "wc -l {}" 64
will run the command 65
wc -l /etc/filename 66
for every file found in /etc – where filename is replaced by the name of each file in turn. (Overall, this will 67
report the number of lines in each file in /etc.) 68
Running 69
uqfindexec --all "tr a-z A-Z < {} > {}.out" 70
will run the command 71
tr a-z A-Z < filename > filename.out 72
for every file found in the current directory – including hidden files whose names begin with ‘.’. (Overall, this 73
command capitalises the content of every file found in the current directory and saves that output to a new file 74
with the .out suffix added to the name.) 75
The command 76
uqfindexec --all --dir /etc 'stat {} | grep "Change: 2023" | cut -d " " -f 2' 77
will run the pipeline 78
stat /etc/filename | grep "Change: 2023" | cut -d " " -f 2 79
on every file found in /etc – including hidden files. (This command reports the modification dates of all files 80
in /etc that were modified in 2023.) 81
Full details of the required behaviour are provided below.2655 82
Command Line Arguments 83
Your program (uqfindexec) is to accept command line arguments as follows: 84
./uqfindexec [--dir dir ] [--stats] [--parallel] [--all] [--recurse] [cmd ] 85
The square brackets ([]) indicate optional arguments (or pairs of arguments). The italics indicate placehold- 86
ers for user-supplied arguments. Any or all of the options can be specified (at most once each). The command, 87
if specified, must always be the last argument and can be assumed not to start with --. Option arguments can 88
be in any order. 89
Some examples of how the program might be run include the following1: 90
./uqfindexec 91
./uqfindexec --recurse 92
./uqfindexec --dir .. "echo {}" 93
./uqfindexec --parallel --dir /etc --all --recurse 'wc -l {}' 94
The meaning of the arguments is as follows:2655 95
1This is not an exhaustive list and does not show all possible combinations of arguments.
© 2024 The University of Queensland 3 Version 1.2
• --dir – if specified, this option argument is followed by the name of the directory whose files are to be 96
processed. If omitted, the current directory (.) is to be used. 97
• --recurse – if specified, this option argument indicates that all subdirectories of the given (or default) 98
directory are to be processed recursively after files in the given/default directory are processed. Support 99
for this functionality is only required for CSSE7231 students but the programs of all students must accept 100
the argument without error.2655 See details of required CSSE7231 functionality on page 8. 101
• --parallel – if specified, this option argument indicates that the processing of the files must be performed 102
in parallel. (By default, processing must take place sequentially – one file at a time.) 103
• --all – if specified, this option argument means that hidden files (those whose names begin with .) must 104
be processed in addition to non-hidden files. When the --recurse option is also specified, then hidden 105
subdirectories will also be processed. 106
• --stats – if specified, this option argument means that statistics are output to standard error when 107
uqfindexec finishes 108
• cmd – if specified, the given command or command pipeline must be run for each file being processed. 109
Any instances of {} in the command argument must first be replaced by the name of the file being 110
processed. (More details are provided below about the syntax of the command or command pipeline.) If 111
this argument is not present then the default command ("echo {}") must be used. This default command 112
will just print the name of each file being processed2. 113
Prior to doing anything else, your program must check the command line arguments for validity. If the 114
program receives an invalid command line then it must print the (single line) message: 115
Usage: uqfindexec [--dir dir] [--stats] [--parallel] [--all] [--recurse] [cmd] 116
to standard error (with a following newline), and exit with an exit status of 15. 117
Invalid command lines include (but may not be limited to) any of the following: 118
• The --dir option argument is given but it is not followed by an associated value argument. 119
• Any of the option arguments is listed more than once. 120
• An unexpected argument is present.2655 121
• Any argument is the empty string. 122
• An argument other than the dir argument starts with -- but isn’t one of the expected option arguments. 123
Checking whether the dir , and/or cmd arguments (if present) are themselves valid is not part of the usage 124
checking (other than checking that their values are not empty). The validity of these values is checked after 125
command line validity as described in the sections below – and in the same order as these sections are listed. 126
Directory Validity Checking 127
Your program must check that the nominated directory (the directory specified on the command line or otherwise 128
the default directory (.)) exists and is readable. If it is not, then your program must print the message: 129
uqfindexec: cannot read directory "dir" 130
to standard error (with a following newline) where dir is replaced by the name of the directory from the 131
command line (or . if no directory was specified on the command line3). The double quotes must be present. 132
Your program must then exit with an exit status of 1. 133
Command Checking 134
If the cmd argument is specified then your program must check that it is valid. A library function has been 135
provided to parse the string. You can use the return value from this function to determine whether the command 136
or command pipeline is valid. See details of this provided library function on page 9. 137
If the cmd argument is not valid, then your program must print the message:2655 138
uqfindexec: command is invalid 139
to standard error (with a following newline), and exit with an exit status of 3. 140
2Note that the default command must be implemented by forking and executing the echo command found in the PATH. Your
program must not just print the file name.
3The current directory will always exist (otherwise it couldn’t be the current directory) but it may not be readable, i.e., you
may not have permission to read the names of the files in the current directory even if you have permission to change into it.
© 2024 The University of Queensland 4 Version 1.2
Command Description 141
The cmd argument is a string that may contain a single command to be executed (possibly with additional 142
arguments) or a pipeline of such commands to be executed. The format is a simplified form of a shell command 143
with elements separated by whitespace characters. Elements in the command can be enclosed in double quotes 144
to escape special characters such as spaces, |, < and >. It is not possible to escape double quote characters or 145
the {} placeholder. 146
A single command will have a format like the following (where square brackets [ ] indicate optional elements, 147
italics indicate text to to be replaced with an appropriate argument, and an ellipsis (. . . ) indicates that the 148
previous element is repeatable, e.g. that multiple arguments can be given): 149
cmd [arg ...] [ < inputfile ] [ > outputfile ] 150
If a standard input redirection is not specified then the command’s standard input must be inherited from 151
the command’s parent (uqfindexec). If a standard output redirection is not specified then the command’s 152
standard output must be inherited from the command’s parent (uqfindexec). The redirections can be in either 153
order. 154
A pipeline of commands will have two or more commands separated by the | symbol. Only the first command 155
may have a standard input redirection. (If not present, the standard input of the first command in the pipeline 156
will be inherited from the command’s parent - uqfindexec.) Only the last command may have a standard 157
output redirection. (If not present, the standard output of the last command in the pipeline will be inherited 158
from the command’s parent - uqfindexec.) A pipeline of commands will have the following format (using the 159
notation above): 160
cmd [arg ...] [ < inputfile ] [ | cmd [arg ...] ]... | cmd [arg ...] [ > outputfile ] 161
As mentioned above, a library function is provided (see Provided Library on page 9) that will parse the 162
command string so that you don’t have to write code to do this. (You will need to implement the filename 163
placeholder ({}) substitution as described under Filename Substitution below.) 164
The standard error for all commands executed will always be inherited from the parent (uqfindexec). 165
Program Operation 166
If the given directory and command are valid then your program must iterate over all files in that directory 167
and execute the command pipeline for that file. (The term command pipeline includes the case where just one 168
command is to be executed.) If the filename placeholder {} is present anywhere in the command pipeline then 169
it must be replaced by the name of the file being processed. See Filename Substitution below. 170
Only directory entries that are regular files or symbolic links to regular files are to be processed. Other 171
entry types such as those for subdirectories are to be ignored. Symbolic links to targets that don’t exist or are 172
in inaccessible directories can be either included or excluded from processing. This situation will not be tested. 173
Files must be processed in the same order that the command ls uses when listing filenames. ls sorts names 174
using the strcoll() comparison function. This compares strings based on the current locale. You must use 175
the “en_AU” collation locale for comparison purposes. Do this by calling 176
setlocale(LC_COLLATE, "en_AU"); 177
somewhere in your program prior to doing any sorting. See the Hints for a function that will return directory 178
entries in the correct order. 179
By default, hidden files (i.e. those whose names begin with .) must be skipped. However, if the --all 180
argument is specified on the command line then these files must also be processed. Files must be processed in 181
the same order that ls -a uses when listing filenames. Again, only regular files or symbolic links to regular 182
files are to be processed. 183
Filename Substitution 184
2655Any occurrence of the placeholder {} in the supplied command string must be replaced by the name of the file 185
being processed prior to the command being executed. The placeholder may be present in (or may be the whole 186
of) the name of an executable, an argument to an executable, the name of the file to be the standard input for 187
the first command in the pipeline, or the name of the file to be the standard output for the last command in 188
the pipeline. Multiple placeholders may be present in a command string. 189
If the --dir option is not specified on the command line then the {} placeholder must be substituted by 190
the name of the file without any path component present. 191
If the --dir option is specified on the command line then the path to the file must be included in the 192
substitution. A single slash (/) will be added between the path and the filename if the path does not have a 193
trailing /. For example: 194
© 2024 The University of Queensland 5 Version 1.2
• if uqfindexec is run with the arguments --dir /etc then the placeholder {} will be substituted by 195
/etc/filename for each filename in /etc; 196
• if uqfindexec is run with the arguments --dir /etc/ then the placeholder {} will be substituted by 197
/etc/filename for each filename in /etc (i.e. there is no additional / between the path and the filename); 198
• if uqfindexec is run with the arguments --dir ./././/////./// then the placeholder {} will be sub- 199
stituted by ./././/////.///filename for each filename in the current directory. 200
Command Execution 201
2655For each file being processed, commands in the pipeline must be executed as follows. (The term pipeline here 202
includes the case where there is only one command.) If there are N files then this sequence is repeated N times. 203
1. If an input file is specified for the first (or only) command in the pipeline then it must be opened for 204
reading and if this fails then the command execution process for this file is aborted (none of the steps 205
below are undertaken for this file) and the following message must be printed to standard error (with a 206
terminating newline): 207
uqfindexec: unable to open "filename1" for reading when processing "filename2" 208
where filename1 is replaced by the name of the file that could not be opened4 and filename2 is replaced 209
by the name of the file being processed (using the same format as would result from {} placeholder 210
substitution). 211
2. If an output file is specified for the last (or only) command in the pipeline then it must be opened for 212
writing (creating the file if it does not exist, truncating the file if it does exist)5. If the open fails then the 213
command execution process for this file is aborted and the following message must be printed to standard 214
error (with a terminating newline): 215
uqfindexec: cannot write "filename1" when processing "filename2" 216
where filename1 is replaced by the name of the file that could not be opened4 and filename2 is replaced 217
by the name of the file being processed (using the same format as would result from {} placeholder 218
substitution). Output files must be created with at least read and write permission for the owner (user) 219
and no permissions for others (i.e. rw????--- permissions where the ? bits can be set or not). 220
3. The commands that make up the pipeline must be executed (after appropriate creation of pipes and 221
redirection of standard input/output as required). Each command will be executed in its own child 222
process – where each process is an immediate child of uqfindexec. Executables must be searched for 223
in the user’s PATH. (Note that all processes in the pipeline must be created before any processes in the 224
pipelined are reaped.) 225
4. The child process(es) created in the previous step must be reaped in turn from the first in the pipeline 226
to the last, i.e. after all processes in the pipeline have been created, your program must wait for the first 227
process in the pipeline to finish and be reaped before moving on the second process, etc. If an execution 228
failed (i.e. a command could not be executed, e.g. because the executable was not found in the user’s 229
PATH) then the following message must be printed to standard error (with a terminating newline): 230
uqfindexec: cannot execute "cmd " when processing "filename " 231
where cmd is replaced by the name of the executable whose execution failed4, and filename is replaced 232
by the name of the file being processed (using the same format as would result from {} placeholder 233
substitution). Multiple of these messages may be printed if multiple commands in a pipeline could not be 234
executed. 235
5. The steps above are repeated for the next file to be processed. (It is possible that this may result in 236
similar error messages being printed again.) 237
Your program must note the return status of each process to generate statistics – see Exiting (Statistics 238
output) below. 239
4This name will be the name given on uqfindexec’s command line – with any {} placeholders substituted as described in the
Filename Substitution section.
5It should be noted that if the output filename does not include a {} placeholder then the nominated output file will be repeatedly
overwritten as each file is processed. This is the expected behaviour.
© 2024 The University of Queensland 6 Version 1.2
Parallel Mode 240
2655If --parallel is specified on the uqfindexec command line then the command execution steps above are 241
performed in a different order. All commands must be executed (or attempted to be executed) for each file 242
prior to any child processes being reaped. In other words, steps 1 to 3 above are performed for all files in the 243
directory, and then step 4 is performed for the same files – i.e. for each file in turn (in the same order), the 244
child process(es) created must be reaped in turn (from the first in the pipeline to the last). 245
Your program does not have to deal with the possibility of fork() failing due to creating too many processes. 246
Directories with “reasonable” numbers of files will be used in testing. 247
This functionality is considered to be more advanced as you will need to create data structures to record 248
many more process IDs to enable delayed reaping. 249
Interrupting the Jobs 250
2655If uqfindexec receives a SIGINT (as usually sent by pressing Ctrl-C) when running in sequential mode then it 251
should allow the current file processing job to finish (and reap any associated child processes) and not commence 252
processing any further files. If uqfindexec is running in parallel mode (i.e. --parallel was specified on the 253
command line) then the SIGINT should be ignored, unless you are a CSSE7231 student implementing the 254
--recurse functionality described below. 255
Your program is permitted to use a single bool global variable to implement signal handling. 256
Note that pressing Ctrl-C on a terminal will send a signal to a whole process group – which will include the 257
children of uqfindexec. During testing for this functionality we will send a SIGINT only to uqfindexec 258
Other Requirements 259
2655Your program must must free all dynamically allocated memory before exiting.2655 (This requirement does not 260
apply to child processes of uqfindexec.) 261
Child processes of uqfindexec must not inherit any unnecessary open file descriptors opened by uqfindexec. 262
(Open file descriptors that uqfindexec inherits from its parent and that are passed to a child must remain open 263
in the child.) 264
uqfindexec is not to leave behind any orphan processes (i.e. when uqfindexec exits normally then none 265
of its children must still be running). uqfindexec is also not to leave behind any zombie processes – when 266
processing files sequentially, all child processes from processing one file must be reaped before commands are 267
run for the next file. 268
uqfindexec must not busy wait, i.e. it should not repeatedly check for something (e.g. process termination) 269
in a loop. This means that use of the WNOHANG option when waiting is not permitted. 270
All commands run by uqfindexec when processing files must be direct children of uqfindexec, i.e. the use 271
of grandchild processes is not permitted. 272
Exiting (Statistics output) 273
2655When uqfindexec has finished processing all the files (or has been interrupted and will not be processing further 274
files), then, if --stats is specified on the command line, uqfindexec must print the following to its standard 275
error: 276
Attempted to process a total of N1 files 277
- operations finished successfully for N2 files 278
- processing may have failed for N3 files 279
- processing was terminated by signal for N4 files 280
- processing failed for N5 files 281
282
where 283
• N1 is replaced by the number of files that were processed; 284
• N2 is replaced by the number of files for which every command in the pipeline exited normally with status 285
0; 286
• N3 is replaced by the number of files for which every command in the pipeline exited normally but one 287
or more of them exited with a non-zero exit status; 288
• N4 is replaced by the number of files for which some command in the pipeline exited due to being signalled; 289
and 290
© 2024 The University of Queensland 7 Version 1.2
• N5 is replaced by the number of files for which the pipeline was not executed (due to the input or output 291
file not being able to be opened) or for which any command in the pipeline was not able to be executed 292
(e.g. the command was not in the user’s PATH). 293
Note that N1 = N2 +N3 +N4 +N5. 294
If --stats is not specified on the command line then nothing is output on exit. 295
Whether the statistics are printed or not, your program must exit with exit status: 296
• 19 if any processing failed (i.e. N5 > 0) 297
• 16 if no processing failed but the program is exiting was interrupted by SIGINT prior to completion of the 298
processing due to interruption by SIGINT (i.e. not all files were processed because of the interruption) 299
• 0 otherwise 300
CSSE7231 Functionality – Directory Recursion 301
2655 CSSE2310 students are not expected to implement this functionality. No marks will be awarded if you do so. 302
If the --recurse argument is given on the uqfindexec command line then your program must process files 303
in subdirectories of the given (or default) directory after processing the files in that given (or default) directory. 304
After files in the given (or default) directory are processed as described above then your program must 305
iterate over all the subdirectories in that directory. Subdirectories must be processed in the same order as ls 306
lists their names. If the --all argument is also given, then hidden subdirectories (those whose names begin 307
with .) must also be included – and subdirectories will be processed in the same order as ls -a lists their 308
names. (Note that . and .. are not subdirectories.) 309
After a subdirectory’s files are processed then your program must recursively descend into its subdirectories 310
before returning to the next subdirectory of the original directory. In other words, your program must undertake 311
a depth-first traversal of the directory hierarchy. For example, if the directory to be processed is /A and the 312
following directories also exist: /A/B1, /A/B2, /A/B3, /A/B1/C1, /A/B1/C2, /A/B3/D1, then the directories must 313
be processed in the following order: 314
• /A 315
• /A/B1 316
• /A/B1/C1 317
• /A/B1/C2 318
• /A/B2 319
• /A/B3 320
• /A/B3/D1 321
Note that symbolic links to directories are not considered to be subdirectories and must not be traversed. 322
Filename placeholder substitution will take place as described in Filename Substitution above with the 323
addition of subdirectory information between the given/default path and the filename. Added path elements 324
must be separated by a single /. 325
For example: 326
• if uqfindexec was run without the --dir argument and is currently processing the abc/def subdirectory 327
of the current directory, then the placeholder {} will be substituted by abc/def/filename for each 328
filename in that subdirectory 329
• if uqfindexec was run with the --recurse --dir /etc arguments and is currently processing the 330
/etc/ssh directory, then the placeholder {} will be substituted by /etc/ssh/filename for each file- 331
name in that subdirectory 332
If a subdirectory is inaccessible (i.e. can not be opened for reading) then your program must print the 333
following message to stderr (terminated with a newline): 334
uqfindexec: unable to access child directory "subdir " 335
where subdir is replaced by the name of the subdirectory (formatted as if it were a filename after {} placeholder 336
substitution). For example, if uqfindexec was run with the --recurse --dir /etc arguments and it fails to 337
access the /nftables subdirectory of /etc, then the subdir name printed will be /etc/nftables. 338
If the --parallel argument is given in addition to the --recurse argument then the files within a 339
(sub)directory must be processed in parallel but each (sub)directory must be processed in turn in the or- 340
der specified above. If a SIGINT signal is received while in parallel mode, then processing of all files in that 341
(sub)directory must be completed but no further subdirectories are to be processed. 342
© 2024 The University of Queensland 8 Version 1.2
Provided Library 343
A library has been provided to you with the following functions which your program may use:2655 344
CommandPipeline* parse_pipeline_string(const char* str); 345
The function and the return type are described in the parse_pipeline_string(3) man page on moss. (Run 346
man parse_pipeline_string.)2655 347
There is also an associated function free_pipeline(CommandPipeline*) that will free the memory allocated 348
by the parse_pipeline_string() function. This function is described in the same man page. 349
To use the library, you will need to add #include to your code and use the compiler flag 350
-I/local/courses/csse2310/include when compiling your code so that the compiler can find the include 351
file. You will also need to link with the library containing this function. To do this, use the compiler arguments 352
-L/local/courses/csse2310/lib -lcsse2310a3.2655 353
Style 354
Your program must follow version 3 of the CSSE2310/CSSE7231 C programming style guide available on the 355
course Blackboard site. Your submission must also comply with the Documentation required for the use of AI 356
tools if applicable. 2655 357
Note that a single global variable of type bool may be used in your assignment – for the implementation of 358
signal handling. Any other use of global variables will be heavily penalised – see style marking details on page 359
12. 360
Hints 361
1. A demo program has been provided to you on moss that implements the required functionality: demo-uqfindexec.362
Make sure you try it out to see how your program is expected to behave. 363
2. It is recommended that you review the provided assignment one sample solution to see what you can learn 364
from it. 365
3. The easiest way to determine whether a directory is accessible or not is to try and open it using 366
opendir(3). Don’t forget to close it afterwards with closedir(3). 367
4. Consider the use of the scandir(3) function with the alphasort(3) comparison function to obtain an 368
appropriately sorted directory listing. 369
5. The readdir(3) man page describes the contents of a struct dirent. There is information in this 370
structure that lets you determine the type of a directory entry. If the entry is a symbolic link, consider 371
the use of the stat(2) system call to determine the type of a symbolic link target. 372
6. Remember that uqfindexec should flush buffers on output so that filled buffers are not inherited on 373
fork(). 374
7. Failure to execute a command in the pipeline (i.e. failure of execvp()) can be detected by having the 375
child process return an unexpected exit code to uqfindexec (e.g. 99). 376
8. For a given process, you can examine the file descriptors that it has open by running ls -l /proc/PID/fd 377
where PID is replaced by the process ID. 378
9. You can use the --trace-children=no and --child-silent-after-fork=yes options to valgrind when 379
checking for memory leaks. This will look only at uqfindexec and ignore child processes. 380
Suggested Approach 381
It is suggested that you write your program using the following steps. Test your program at each stage and 382
commit to your SVN repository frequently. Note that the specification text above is the definitive description 383
of the expected program behaviour. The list below does not cover all required functionality. 384
1. Write a program that checks the command line arguments and exits with a usage error if they are invalid. 385
2. Add functionality to check that the directory is accessible and that the supplied command is valid. 386
© 2024 The University of Queensland 9 Version 1.2
3. Add functionality to iterate over all files in a directory (and for now just print their names). 387
4. Add functionality to handle a single command (with arguments) being executed (and waited on) for each 388
file (no pipes or redirection) 389
5. Implement the placeholder substitution on the command/arguments 390
6. Add support for stdin and stdout redirection 391
7. Add support for a pipeline of commands 392
8. Implement remaining functionality as required . . . 393
Forbidden Functions, Statements etc.
2655You must not use any of the following C statements/directives/etc. If you do so, you will get zero (0) marks
for the assignment.
• goto
• #pragma2655
• gcc attributes (other than the possible use of __attribute__((unused)) as described in the style guide)2655
You must not use any of the following C functions. If you do so, you will get zero (0) marks for any test case
that calls the function.
• longjmp() and equivalent functions
• system()
• popen()2655
• mkfifo() or mkfifoat()
• signal(), sigpending(), sigqueue(), sigwaitinfo(), sigtimedwait(), sigsuspend()
• Any pthread* functions
• As noted in Other Requirements, you must not use the WNOHANG option when waiting.
• Functions described in the man page as non standard, e.g. strcasestr(). Standard functions will
conform to a POSIX standard – often listed in the “CONFORMING TO” section of a man page. Note
that getopt_long() and getopt_long_only() are an exception to this – these functions are permitted
if desired.
The use of comments to control the behaviour of clang-format and/or clang-tidy (e.g., to disable style
checking) will result in zero marks for automatically marked style.
Submission 415
Your submission must include all source and any other required files (in particular you must submit a Makefile). 416
Do not submit compiled files (e.g. .o, compiled programs).2655 417
Your program (named uqfindexec) must build on moss.labs.eait.uq.edu.au and in the Gradescope 418
environment with: 419
make 420
Your program must be compiled with gcc with at least the following options: 421
-Wall -Wextra -pedantic -std=gnu99 422
You are not permitted to disable warnings or use pragmas to hide them. You may not use source files other 423
than .c and .h files as part of the build process – such files will be removed before building your program. 2655 424
If any errors result from the make command (i.e. the uqfindexec executable can not be created) then you 425
will receive 0 marks for functionality (see below). Any code without academic merit will be removed from your 426
program before compilation is attempted (and if compilation fails, you will receive 0 marks for functionality).2655 427
Your program must not invoke other programs (other than those expected to be invoked when running a 428
command or command pipeline) or use non-standard headers/libraries. 429
Your assignment submission must be committed to your subversion repository under 430
https://source.eait.uq.edu.au/svn/csse2310-sem1-sXXXXXXX/trunk/a3 431
© 2024 The University of Queensland 10 Version 1.2
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 432
files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these 433
will not be considered in marking – they will not be checked out of your repository. 434
You must ensure that all files needed to compile and use your assignment (including a Makefile) are commit- 435
ted and within the trunk/a3 directory in your repository (and not within a subdirectory) and not just sitting 436
in your working directory. Do not commit compiled files or binaries. You are strongly encouraged to check out 437
a clean copy for testing purposes. 438
To submit your assignment, you must run the command 2655 439
2310createzip a3 440
on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 441
available in the Assessment area on the CSSE2310/7231 Blackboard site)6. The zip file will be named 442
sXXXXXXX_csse2310_a3_timestamp.zip 443
where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 444
the time that the zip file was created. 445
The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 446
ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your 447
Subversion commit history and a checksum of the zip file contents. You may be asked for your password as 448
part of this process in order to check out your submission from your repository. You will be asked to confirm 449
references in your code and also to confirm your use (or not) of AI tools to help you.2655 450
You must not create the zip file using some other mechanism and you must not modify the zip file prior 451
to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file 452
is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 453
creation of your submission zip file. 454
We will mark your last submission, even if that is after the deadline and you made submissions before the 455
deadline. Any submissions after the deadline7 will incur a late penalty – see the CSSE2310/7231 course profile 456
for details.2655 457
Note that Gradescope will run the test suite immediately after you submit. When complete8 you will be 458
able to see the results of the “public” tests. You should check these test results to make sure your program is 459
working as expected. 460
Marks 461
Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked 462
to attend an interview about your assignment and you are unable to adequately respond to questions – see the 463
Student conduct section above. 464
Functionality (60 marks CSSE2310 / 70 marks CSSE7231) 465
Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), and 466
your zip file has been generated correctly and has not been modified prior to submission, then you will earn 467
functionality marks based on the number of features your program correctly implements, as outlined below. 468
Not all features are of equal difficulty. Partial marks will be awarded for partially meeting the functionality 469
requirements. A number of tests will be run for each marking category listed below. Your mark in that category 470
will be proportional (or approximately proportional) to the number of tests passed in that category. 471
If your program does not allow a feature to be tested then you will receive 0 marks for that 472
feature, even if you claim to have implemented it. For example, if your program can never create a child 473
process then we can not determine whether pipes are created successfully. Your tests must run in a reasonable 474
time frame, which could be as short as a few seconds for usage checking to many tens of seconds when valgrind 475
is used to test for memory leaks. If your program takes too long to respond, then it will be terminated and you 476
will earn no marks for the functionality associated with that test. The markers will make no alterations to your 477
code (other than to remove code without academic merit). 2655 478
Functionality marks (out of 60 total) will be assigned in the following categories (CSSE2310 and CSSE7231): 479
6You 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.
7or your extended deadline if you are granted an extension.
8Gradescope marking may take only a few minutes or more than 30 minutes depending on the functionality and efficiency of
your code.
© 2024 The University of Queensland 11 Version 1.2
1. Program correctly handles invalid command lines (usage errors). (6 marks) 480
2. Program correctly handles an invalid directory argument. (2 marks) 481
3. Program correctly handles an invalid command argument. (2 marks) 482
4. Program correctly handles an empty command line (in a variety of directories) – i.e. the 483
default command that prints each filename is run. (6 marks) 484
5. Program correctly handles the --dir option argument and value (with no other 485
command line arguments). (4 marks) 486
6. Program correctly handles the --all option (with and without the --dir 487
option argument and value specified but no other command line arguments). (5 marks) 488
7. Program correctly handles execution with filename substitution when the cmd 489
argument is just a single command (i.e. possibly with arguments and redirection but 490
no pipeline). A variety of combinations of --all and --dir arguments 491
will be used. (This includes detection of commands that can’t be executed and 492
input/output files that can’t be opened.)2655 (6 marks) 493
8. Program correctly handles execution with filename substitution when the cmd 494
argument is a pipeline of commands. A variety of combinations of --all and 495
--dir arguments will be used. (6 marks) 496
9. Program correctly implements statistics generation when --stats is specified 497
(for a variety of execution scenarios). (Parallel execution and interruption will 498
not be tested in this category.) (6 marks) 499
10. Program correctly implements parallel execution (with a variety of other command 500
line arguments, including statistics generation). (5 marks) 501
11. Program correctly implements interruption (signal handling) (for a variety of execution 502
scenarios). (4 marks) 503
12. Program correctly closes all unnecessary file descriptors in child processes (for a variety 504
of execution scenarios, i.e. any potential valid combination of command line arguments). 2655 (4 marks) 505
13. Program frees all allocated memory prior to exit (original process, not children) (for a 506
variety of execution scenarios, i.e. any potential valid combination of command line 507
arguments). (4 marks) 508
Some functionality may be assessed in multiple categories – e.g. successful filename substitution will be 509
required in many tests after category 8. Correct output will also be required when checking the closure of file 510
descriptors and memory use in categories 12 and 13. 511
Functionality marks (out of 10) will be assigned in the following categories (CSSE7231 only): 512
14. Program correctly implements recursion functionality with no cmd specified for a 513
variety of directories with and without the --dir option and value specified 514
(but no other arguments) (3 marks) 515
15. Program correctly implements recursion functionality without --parallel being 516
specified but with a variety of other arguments specified (including pipelines of commands) (4 marks) 517
16. Program correctly implements recursion functionality with --parallel also specified (3 marks) 518
Style Marking 519
Style marking is based on the number of style guide violations, i.e. the number of violations of version 3 of the 520
CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of two 521
components – automated style marks and human style marks. These are detailed below. Your style marks can 522
never be more than your functionality mark – this prevents the submission of well styled programs which don’t 523
meet at least a minimum level of required functionality. 524
© 2024 The University of Queensland 12 Version 1.2
You should pay particular attention to commenting so that others can understand your code. The marker’s 525
decision with respect to commenting violations is final – it is the marker who has to understand your code. 526
You are encouraged to use the 2310reformat.sh and 2310stylecheck.sh tools installed on moss to cor- 527
rect and/or check your code style before submission. The 2310stylecheck.sh tool does not check all style 528
requirements, but it will determine your automated style mark (see below). Other elements of the style guide 529
are checked by humans. 530
All .c and .h files in your submission will be subject to style marking. This applies whether they are 531
compiled/linked into your executable or not9. 532
Automated Style Marking (5 marks) 533
Automated style marks will be calculated over all of your .c and .h files as follows. If any of your submitted 534
.c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). If 535
your code uses comments to control the behaviour of clang-format and/or clang-tidy then your automated 536
style mark will be zero. If any of your source files contain C functions longer than 100 lines of code10 then your 537
automated and human style marks will both be zero. If you use any global variables (other than a single flag 538
of bool type for signal handling) then your automated and human style marks will both be zero. 539
If your code does compile and does not contain any C functions longer than 100 lines and does not use 540
any global variables (other than a single flag of bool type for signal handling) and does not interfere with the 541
expected behaviour of clang-format and/or clang-tidy then your automated style mark will be determined 542
as follows: Let 543
• W be the total number of distinct compilation warnings recorded when your .c files are individually built 544
(using the correct compiler arguments) 545
• A be the total number of style violations detected by 2310stylecheck.sh when it is run over each of your 546
.c and .h files individually11. 547
Your automated style mark S will be 548
S = 5− (W +A) 549
If W +A ≥ 5 then S will be zero (0) – no negative marks will be awarded. If you believe that 550
2310stylecheck.sh is behaving incorrectly or inconsistently then please bring this to the attention of the 551
course coordinator prior to submission, e.g., it is possible the style checker may report different issues on moss 552
than it does in the Gradescope environment. Your automated style mark can be updated if this is deemed to 553
be appropriate. You can check the result of Gradescope style marking soon after your Gradescope submission 554
– when the test suite completes running. 555
Human Style Marking (5 marks) 556
The human style mark (out of 5 marks) will be based on the criteria/standards below for “comments”, “nam- 557
ing” and “modularity”. Note that if your code contains any functions longer than 100 lines or uses a global 558
variable (other than a single flag of bool type for signal handling) then your human style mark is zero and the 559
criteria/standards below are not relevant. 560
The meanings of words like appropriate and required are determined by the requirements in the style guide. 561
9Make sure you remove any unneeded files from your repository, or they will be subject to style marking.
10Note that the style guide requires functions to be 50 lines of code or fewer. Code that contains functions whose length is 51 to
100 lines will be penalised somewhat – one style violation (i.e. one mark) per function. Code that contains functions longer than
100 lines will be penalised very heavily – no marks will be awarded for human style or automatically marked style.
11Every .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. You can check that a header file compiles by itself by running gcc -c
filename.h – with any other gcc arguments as required.
© 2024 The University of Queensland 13 Version 1.2
Comments (3 marks) 562
Mark Description
0 25% or more of the comments that are present are inappropriate AND/OR at least 50% of therequired comments are missing
1 At least 50% of the required comments are present AND the vast majority (75%+) of commentspresent are appropriate AND the requirements for a higher mark are not met
2 All or almost all required comments are present AND all or almost all comments present are appro-priate AND the requirements for a mark of 3 are not met
3 All required comments are present AND all comments present are appropriate AND additionalcomments are present as appropriate to ensure clarity
563
Naming (1 mark) 564
Mark Description
0 At least a few names used are inappropriate
0.5 Almost all names used are appropriate
1 All names used are appropriate
565
Modularity (1 mark) 566
Mark Description
0 There are two or more instances of poor modularity (e.g. repeated code blocks)
0.5 There is one instance of poor modularity (e.g. a block of code repeated once)
1 There are no instances of poor modularity
567
SVN Commit History Marking (5 marks) 568
Markers will review your SVN commit history for your assignment up to your submission time. This element 569
will be graded according to the following principles: 570
• Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will 571
yield a score of zero for this section). Progressive development is expected, i.e., no large commits with 572
multiple features in them. 573
• Appropriate use of log messages to capture the changes represented by each commit. (Meaningful messages 574
explain briefly what has changed in the commit (e.g. in terms of functionality, not in terms of specific 575
numbered test cases in the test suite) and/or why the change has been made and will be usually be more 576
detailed for significant changes.). 577
The standards expected are outlined in the following rubric. The mark awarded will be the highest for which 578
the relevant standard is met. 579
Mark
(out of 5) Description
0 Minimal commit history – only one or two commits ORall commit messages are meaningless.
1 Some progressive development evident (three or more commits) ANDat least one commit message is meaningful.
2 Progressive development is evident (multiple commits) ANDat least half the commit messages are meaningful
3 Multiple commits that show progressive development of almost all or all functionality ANDat least two-thirds of the commit messages are meaningful.
4 Multiple commits that show progressive development of ALL functionality ANDmeaningful messages for all but one or two of the commits.
5 Multiple commits that show progressive development of ALL functionality ANDmeaningful messages for ALL commits.
580
© 2024 The University of Queensland 14 Version 1.2
Total Mark 581
Let 582
• F be the functionality mark for your assignment (out of 60 for CSSE2310 students or out of 70 for 583
CSSE7231 students). 584
• S be the automated style mark for your assignment (out of 5). 585
• H be the human style mark for your assignment (out of 5). 586
• C be the SVN commit history mark (out of 5). 587
• V is the scaling factor (0 to 1) determined after interview(s) (if applicable – see the Student Conduct 588
section above) – or 0 if you fail to attend a scheduled interview without having evidence of exceptional 589
circumstances impacting your ability to attend. 590
Your total mark for the assignment will be: 591
M = (F + min{F, S +H} + min{F,C})× V 592
out of 75 (for CSSE2310 students) or out of 85 (for CSSE7231 students). 593
In other words, you can’t get more marks for style or SVN commit history than you do for functionality. 594
Pretty code that doesn’t work will not be rewarded! 595
Late Penalties 596
Late penalties will apply as outlined in the course profile. 597
Specification Updates 598
Any clarifications or updates to the assignment specification will be summarised here. Any updated versions 599
of the specification will be released with adequate time for students to respond prior to due date. Potential 600
specification errors or omissions can be discussed on the discussion forum.2655 601
602
Version 1.1 603
• Added clarification about invalid command lines. 604
• Clarified that symbolic links to inaccessible targets can be either included or excluded from processing. 605
• Added additional hint information about determining the type of a directory entry. 606
• Reinforced that all processes in a pipeline must be created before any are reaped. 607
• Added hint about detecting execution failure. 608
609
Version 1.2 610
• Added clarifications to multiple marking categories.2655 611
• Added hints about examining open file descriptors and checking for memory leaks. 612
• Added clarification of when to exit with status 16 (due to interruption). 613
• Added some additional spaces where text had run together. 614
© 2024 The University of Queensland 15 Version 1.2