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

This specification was created for the use of Abhinav PRADEEP (s4803941) only.
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. 2873 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 hthis happensi?” would be safe, if they are seeking clarification on the 14

specification. 15

You must not actively help (or seek help from) other students or other people with the actual design, structure 16

and/or coding of your assignment solution. It is cheating to look at another 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 22

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- May be used freely without reference. (You must be able
board, found in /local/courses/csse2310/resources to point to the source if queried about it – so you may
on moss, posted on the discussion forum by teaching staff, find it easier to reference the code.)
provided in Ed Lessons, or shown in class).
Code you have personally written this semester for
May be used freely without reference. (This assumes that
CSSE2310/7231 (e.g. code written for A1 reused in A3)
no reference was required for the original use.)
– provided you have not shared or published it.

© 2024 The University of Queensland 1 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 Code Origin Usage/Referencing
Code you have personally written in a previous enrolment May be used provided you understand the code AND
in this course or in another EECS course and where that the source of the code is referenced in a comment
code has not been shared with any other person or pub- adjacent to that code (in the required format – see the
lished in any way. style guide). If such code is used without appropriate
Code examples found in man pages on moss. referencing then this will be considered misconduct.
May not be used. If the source of the code is referenced
Code copied from any website or forum (including Stack- adjacent to the code then this will be considered code
Overflow and CSDN), code copied from any public or without academic merit (not misconduct) and will be re-
private repositories; code copied from textbooks. (This moved from your assignment prior to marking (which may
includes code in other programming languages that has cause compilation to fail and zero marks to be awarded).
been converted to C.) Copied code without adjacent referencing will be consid-
ered misconduct and action will be taken.
Examples, websites, code (in any programming language), May be used provided you do not directly copy code AND
etc. that you have learned from or that you have taken you understand the code AND the source of the code or
inspiration from or based any part of your code on but inspiration or learning is referenced in a comment adjacent
have not copied or just converted from another program- to that code (in the required format – see the style guide).
ming language. This includes learning about individual If such code is used without appropriate referencing then
functions that are not covered in class. this will be considered misconduct.
May be used provided you understand that code AND the
source of the code is referenced in a comment adjacent to
Code written by, modified by, obtained from or based on that code (in the required format) AND an ASCII text
code output by a code generation tool (including any ar- file (named toolHistory.txt) is included in your repos-
tificial intelligence tool) that you alone personally have itory and with your submission that describes in detail
interacted with, without the assistance of another person. how the tool was used. The file must be committed to
This includes code you wrote but then modified or de- the repository at the same time as any code derived from
bugged because of your interaction with such a tool. It such a tool. If such code is used without appropriate refer-
also includes where comments are written by such a tool encing and without inclusion of the toolHistory.txt file
– comments are part of your code. 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.
May not be used. If the source of the code is referenced
Other code – includes (but may not be limited to): code
adjacent to the code then this will be considered code
provided by teaching staff only in a previous offering of
without academic merit (not misconduct) and will be re-
this course (e.g. previous assignment one solution); any
moved from your assignment prior to marking (which may
code written by or partially written by someone else or
cause compilation to fail and zero marks to be awarded).
with the assistance of someone else; and any code you
Copied code without adjacent referencing will be consid-
have written that is available to other students.
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

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 • 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 --allfiles "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 --allfiles --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. 2873 82

Command Line Arguments 83

Your program (uqfindexec) is to accept command line arguments as follows: 84

./uqfindexec [--dir dirname ] [--report] [--allfiles] [--recurse] [--parallel] [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 --allfiles --recurse 'wc -l {}' 94

The meaning of the arguments is as follows: 2873 95

1 This is not an exhaustive list and does not show all possible combinations of arguments.

© 2024 The University of Queensland 3 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 • --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. See details of required CSSE7231 functionality on page 8.
2873 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

• --allfiles – if specified, this option argument means that hidden files (those whose names begin with 104

.) must be processed in addition to non-hidden files. When the --recurse option is also specified, then 105

hidden subdirectories will also be processed. 106

• --report – 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 dirname] [--report] [--allfiles] [--recurse] [--parallel] [cmd] 116

to standard error (with a following newline), and exit with an exit status of 5. 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. 2873 121

• Any argument is the empty string. 122

• An argument other than the dirname argument starts with -- but isn’t one of the expected option 123

arguments. 124

Checking whether the dirname , and/or cmd arguments (if present) are themselves valid is not part of the 125

usage checking (other than checking that their values are not empty). The validity of these values is checked 126

after command line validity as described in the sections below – and in the same order as these sections are 127

listed. 128

Directory Validity Checking 129

Your program must check that the nominated directory (the directory specified on the command line or otherwise 130

the default directory (.)) exists and is readable. If it is not, then your program must print the message: 131

uqfindexec: directory "dirname" can not be accessed 132

to standard error (with a following newline) where dirname is replaced by the name of the directory from the 133

command line (or . if no directory was specified on the command line3 ). The double quotes must be present. 134

Your program must then exit with an exit status of 6. 135

Command Checking 136

If the cmd argument is specified then your program must check that it is valid. A library function has been 137

provided to parse the string. You can use the return value from this function to determine whether the command 138

or command pipeline is valid. See details of this provided library function on page 9. 139

If the cmd argument is not valid, then your program must print the message: 2873 140

uqfindexec: command is not valid 141

to standard error (with a following newline), and exit with an exit status of 17. 142

2 Note 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.
3 The 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

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
Command Description 143

The cmd argument is a string that may contain a single command to be executed (possibly with additional 144

arguments) or a pipeline of such commands to be executed. The format is a simplified form of a shell command 145

with elements separated by whitespace characters. Elements in the command can be enclosed in double quotes 146

to escape special characters such as spaces, |, < and >. It is not possible to escape double quote characters or 147

the {} placeholder. 148

A single command will have a format like the following (where square brackets [ ] indicate optional elements, 149

italics indicate text to to be replaced with an appropriate argument, and an ellipsis (. . . ) indicates that the 150

previous element is repeatable, e.g. that multiple arguments can be given): 151

cmd [arg ...] [ < inputfile ] [ > outputfile ] 152

If a standard input redirection is not specified then the command’s standard input must be inherited from 153

the command’s parent (uqfindexec). If a standard output redirection is not specified then the command’s 154

standard output must be inherited from the command’s parent (uqfindexec). The redirections can be in either 155

order. 156

A pipeline of commands will have two or more commands separated by the | symbol. Only the first command 157

may have a standard input redirection. (If not present, the standard input of the first command in the pipeline 158

will be inherited from the command’s parent - uqfindexec.) Only the last command may have a standard 159

output redirection. (If not present, the standard output of the last command in the pipeline will be inherited 160

from the command’s parent - uqfindexec.) A pipeline of commands will have the following format (using the 161

notation above): 162

cmd [arg ...] [ < inputfile ] [ | cmd [arg ...] ]... | cmd [arg ...] [ > outputfile ] 163

As mentioned above, a library function is provided (see Provided Library on page 9) that will parse the 164

command string so that you don’t have to write code to do this. (You will need to implement the filename 165

placeholder ({}) substitution as described under Filename Substitution below.) 166

The standard error for all commands executed will always be inherited from the parent (uqfindexec). 167

Program Operation 168

If the given directory and command are valid then your program must iterate over all files in that directory 169

and execute the command pipeline for that file. (The term command pipeline includes the case where just one 170

command is to be executed.) If the filename placeholder {} is present anywhere in the command pipeline then 171

it must be replaced by the name of the file being processed. See Filename Substitution below. 172

Only directory entries that are regular files or symbolic links to regular files are to be processed. Other 173

entry types such as those for subdirectories are to be ignored. Symbolic links to targets that don’t exist or are 174

in inaccessible directories can be either included or excluded from processing. This situation will not be tested. 175

Files must be processed in the same order that the command ls uses when listing filenames. ls sorts names 176

using the strcoll() comparison function. This compares strings based on the current locale. You must use 177

the “en_AU” collation locale for comparison purposes. Do this by calling 178

setlocale(LC_COLLATE, "en_AU"); 179

somewhere in your program prior to doing any sorting. See the Hints for a function that will return directory 180

entries in the correct order. 181

By default, hidden files (i.e. those whose names begin with .) must be skipped. However, if the --allfiles 182

argument is specified on the command line then these files must also be processed. Files must be processed in 183

the same order that ls -a uses when listing filenames. Again, only regular files or symbolic links to regular 184

files are to be processed. 185

Filename Substitution 186

Any occurrence of the placeholder {} in the supplied command string must be replaced by the name of the file
2873 187

being processed prior to the command being executed. The placeholder may be present in (or may be the whole 188

of) the name of an executable, an argument to an executable, the name of the file to be the standard input for 189

the first command in the pipeline, or the name of the file to be the standard output for the last command in 190

the pipeline. Multiple placeholders may be present in a command string. 191

If the --dir option is not specified on the command line then the {} placeholder must be substituted by 192

the name of the file without any path component present. 193

If the --dir option is specified on the command line then the path to the file must be included in the 194

substitution. A single slash (/) will be added between the path and the filename if the path does not have a 195

trailing /. For example: 196

© 2024 The University of Queensland 5 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 • if uqfindexec is run with the arguments --dir /etc then the placeholder {} will be substituted by 197

/etc/filename for each filename in /etc; 198

• if uqfindexec is run with the arguments --dir /etc/ then the placeholder {} will be substituted by 199

/etc/filename for each filename in /etc (i.e. there is no additional / between the path and the filename); 200

• if uqfindexec is run with the arguments --dir ./././/////./// then the placeholder {} will be sub- 201

stituted by ./././/////.///filename for each filename in the current directory. 202

Command Execution 203

For each file being processed, commands in the pipeline must be executed as follows. (The term pipeline here
2873 204

includes the case where there is only one command.) If there are N files then this sequence is repeated N times. 205

1. If an input file is specified for the first (or only) command in the pipeline then it must be opened for 206

reading and if this fails then the command execution process for this file is aborted (none of the steps 207

below are undertaken for this file) and the following message must be printed to standard error (with a 208

terminating newline): 209

uqfindexec: unable to open "filename1 " for reading while processing "filename2 " 210

where filename1 is replaced by the name of the file that could not be opened4 and filename2 is replaced 211

by the name of the file being processed (using the same format as would result from {} placeholder 212

substitution). 213

2. If an output file is specified for the last (or only) command in the pipeline then it must be opened for 214

writing (creating the file if it does not exist, truncating the file if it does exist)5 . If the open fails then the 215

command execution process for this file is aborted and the following message must be printed to standard 216

error (with a terminating newline): 217

uqfindexec: unable to open "filename1 " for writing when processing "filename2 " 218

where filename1 is replaced by the name of the file that could not be opened4 and filename2 is replaced 219

by the name of the file being processed (using the same format as would result from {} placeholder 220

substitution). Output files must be created with at least read and write permission for the owner (user) 221

and no permissions for others (i.e. rw????--- permissions where the ? bits can be set or not). 222

3. The commands that make up the pipeline must be executed (after appropriate creation of pipes and 223

redirection of standard input/output as required). Each command will be executed in its own child 224

process – where each process is an immediate child of uqfindexec. Executables must be searched for 225

in the user’s PATH. (Note that all processes in the pipeline must be created before any processes in the 226

pipelined are reaped.) 227

4. The child process(es) created in the previous step must be reaped in turn from the first in the pipeline 228

to the last, i.e. after all processes in the pipeline have been created, your program must wait for the first 229

process in the pipeline to finish and be reaped before moving on the second process, etc. If an execution 230

failed (i.e. a command could not be executed, e.g. because the executable was not found in the user’s 231

PATH) then the following message must be printed to standard error (with a terminating newline): 232

uqfindexec: unable to execute "cmd " while processing "filename " 233

where cmd is replaced by the name of the executable whose execution failed4 , and filename is replaced 234

by the name of the file being processed (using the same format as would result from {} placeholder 235

substitution). Multiple of these messages may be printed if multiple commands in a pipeline could not be 236

executed. 237

5. The steps above are repeated for the next file to be processed. (It is possible that this may result in 238

similar error messages being printed again.) 239

Your program must note the return status of each process to generate statistics – see Exiting (Statistics 240

output) below. 241

4 This name will be the name given on uqfindexec’s command line – with any {} placeholders substituted as described in the

Filename Substitution section.

5 It 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

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
Parallel Mode 242

If --parallel is specified on the uqfindexec command line then the command execution steps above are
2873 243

performed in a different order. All commands must be executed (or attempted to be executed) for each file 244

prior to any child processes being reaped. In other words, steps 1 to 3 above are performed for all files in the 245

directory, and then step 4 is performed for the same files – i.e. for each file in turn (in the same order), the 246

child process(es) created must be reaped in turn (from the first in the pipeline to the last). 247

Your program does not have to deal with the possibility of fork() failing due to creating too many processes. 248

Directories with “reasonable” numbers of files will be used in testing. 249

This functionality is considered to be more advanced as you will need to create data structures to record 250

many more process IDs to enable delayed reaping. 251

Interrupting the Jobs 252

If uqfindexec receives a SIGINT (as usually sent by pressing Ctrl-C) when running in sequential mode then it
2873 253

should allow the current file processing job to finish (and reap any associated child processes) and not commence 254

processing any further files. If uqfindexec is running in parallel mode (i.e. --parallel was specified on the 255

command line) then the SIGINT should be ignored, unless you are a CSSE7231 student implementing the 256

--recurse functionality described below. 257

Your program is permitted to use a single bool global variable to implement signal handling. 258

Note that pressing Ctrl-C on a terminal will send a signal to a whole process group – which will include the 259

children of uqfindexec. During testing for this functionality we will send a SIGINT only to uqfindexec 260

Other Requirements 261

Your program must must free all dynamically allocated memory before exiting. (This requirement does not
2873 2873 262

apply to child processes of uqfindexec.) 263

Child processes of uqfindexec must not inherit any unnecessary open file descriptors opened by uqfindexec. 264

(Open file descriptors that uqfindexec inherits from its parent and that are passed to a child must remain open 265

in the child.) 266

uqfindexec is not to leave behind any orphan processes (i.e. when uqfindexec exits normally then none 267

of its children must still be running). uqfindexec is also not to leave behind any zombie processes – when 268

processing files sequentially, all child processes from processing one file must be reaped before commands are 269

run for the next file. 270

uqfindexec must not busy wait, i.e. it should not repeatedly check for something (e.g. process termination) 271

in a loop. This means that use of the WNOHANG option when waiting is not permitted. 272

All commands run by uqfindexec when processing files must be direct children of uqfindexec, i.e. the use 273

of grandchild processes is not permitted. 274

Exiting (Statistics output) 275

When uqfindexec has finished processing all the files (or has been interrupted and will not be processing further
2873 276

files), then, if --report is specified on the command line, uqfindexec must print the following to its standard 277

error: 278

Attempted to process N1 files 279

- operations succeeded for N2 files 280

- non-zero exit status detected when processing N3 files 281

- processing was terminated by signal for N4 files 282

- operations unable to be executed for N5 files 283

284

where 285

• N1 is replaced by the number of files that were processed; 286

• N2 is replaced by the number of files for which every command in the pipeline exited normally with status 287

0; 288

• N3 is replaced by the number of files for which every command in the pipeline exited normally but one 289

or more of them exited with a non-zero exit status; 290

• N4 is replaced by the number of files for which some command in the pipeline exited due to being signalled; 291

and 292

© 2024 The University of Queensland 7 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 • N5 is replaced by the number of files for which the pipeline was not executed (due to the input or output 293

file not being able to be opened) or for which any command in the pipeline was not able to be executed 294

(e.g. the command was not in the user’s PATH). 295

Note that N 1 = N 2 + N 3 + N 4 + N 5. 296

If --report is not specified on the command line then nothing is output on exit. 297

Whether the statistics are printed or not, your program must exit with exit status: 298

• 16 if any processing failed (i.e. N 5 > 0) 299

• 19 if no processing failed but the program is exiting was interrupted by SIGINT prior to completion of the 300

processing due to interruption by SIGINT (i.e. not all files were processed because of the interruption) 301

• 0 otherwise 302

CSSE7231 Functionality – Directory Recursion 303

2873 CSSE2310 students are not expected to implement this functionality. No marks will be awarded if you do so. 304

If the --recurse argument is given on the uqfindexec command line then your program must process files 305

in subdirectories of the given (or default) directory after processing the files in that given (or default) directory. 306

After files in the given (or default) directory are processed as described above then your program must 307

iterate over all the subdirectories in that directory. Subdirectories must be processed in the same order as ls 308

lists their names. If the --allfiles argument is also given, then hidden subdirectories (those whose names 309

begin with .) must also be included – and subdirectories will be processed in the same order as ls -a lists 310

their names. (Note that . and .. are not subdirectories.) 311

After a subdirectory’s files are processed then your program must recursively descend into its subdirectories 312

before returning to the next subdirectory of the original directory. In other words, your program must undertake 313

a depth-first traversal of the directory hierarchy. For example, if the directory to be processed is /A and the 314

following directories also exist: /A/B1, /A/B2, /A/B3, /A/B1/C1, /A/B1/C2, /A/B3/D1, then the directories must 315

be processed in the following order: 316

• /A 317

• /A/B1 318

• /A/B1/C1 319

• /A/B1/C2 320

• /A/B2 321

• /A/B3 322

• /A/B3/D1 323

Note that symbolic links to directories are not considered to be subdirectories and must not be traversed. 324

Filename placeholder substitution will take place as described in Filename Substitution above with the 325

addition of subdirectory information between the given/default path and the filename. Added path elements 326

must be separated by a single /. 327

For example: 328

• if uqfindexec was run without the --dir argument and is currently processing the abc/def subdirectory 329

of the current directory, then the placeholder {} will be substituted by abc/def/filename for each 330

filename in that subdirectory 331

• if uqfindexec was run with the --recurse --dir /etc arguments and is currently processing the 332

/etc/ssh directory, then the placeholder {} will be substituted by /etc/ssh/filename for each file- 333

name in that subdirectory 334

If a subdirectory is inaccessible (i.e. can not be opened for reading) then your program must print the 335

following message to stderr (terminated with a newline): 336

uqfindexec: unable to access child directory "subdir " 337

where subdir is replaced by the name of the subdirectory (formatted as if it were a filename after {} placeholder 338

substitution). For example, if uqfindexec was run with the --recurse --dir /etc arguments and it fails to 339

access the /nftables subdirectory of /etc, then the subdir name printed will be /etc/nftables. 340

If the --parallel argument is given in addition to the --recurse argument then the files within a 341

(sub)directory must be processed in parallel but each (sub)directory must be processed in turn in the or- 342

der specified above. If a SIGINT signal is received while in parallel mode, then processing of all files in that 343

(sub)directory must be completed but no further subdirectories are to be processed. 344

© 2024 The University of Queensland 8 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
Provided Library 345

A library has been provided to you with the following functions which your program may use: 2873 346

CommandPipeline* parse_pipeline_string(const char* str); 347

The function and the return type are described in the parse_pipeline_string(3) man page on moss. (Run 348

man parse_pipeline_string.) 2873 349

There is also an associated function free_pipeline(CommandPipeline*) that will free the memory allocated 350

by the parse_pipeline_string() function. This function is described in the same man page. 351

To use the library, you will need to add #include <csse2310a3.h> to your code and use the compiler flag 352

-I/local/courses/csse2310/include when compiling your code so that the compiler can find the include 353

file. You will also need to link with the library containing this function. To do this, use the compiler arguments 354

-L/local/courses/csse2310/lib -lcsse2310a3. 2873 355

Style 356

Your program must follow version 3 of the CSSE2310/CSSE7231 C programming style guide available on the 357

course Blackboard site. Your submission must also comply with the Documentation required for the use of AI 358

tools if applicable. 2873 359

Note that a single global variable of type bool may be used in your assignment – for the implementation of 360

signal handling. Any other use of global variables will be heavily penalised – see style marking details on page 361

12. 362

Hints 363

1. A demo program has been provided to you on moss that implements the required functionality: demo-uqfindexec.
364

Make sure you try it out to see how your program is expected to behave. 365

2. It is recommended that you review the provided assignment one sample solution to see what you can learn 366

from it. 367

3. The easiest way to determine whether a directory is accessible or not is to try and open it using 368

opendir(3). Don’t forget to close it afterwards with closedir(3). 369

4. Consider the use of the scandir(3) function with the alphasort(3) comparison function to obtain an 370

appropriately sorted directory listing. 371

5. The readdir(3) man page describes the contents of a struct dirent. There is information in this 372

structure that lets you determine the type of a directory entry. If the entry is a symbolic link, consider 373

the use of the stat(2) system call to determine the type of a symbolic link target. 374

6. Remember that uqfindexec should flush buffers on output so that filled buffers are not inherited on 375

fork(). 376

7. Failure to execute a command in the pipeline (i.e. failure of execvp()) can be detected by having the 377

child process return an unexpected exit code to uqfindexec (e.g. 99). 378

8. For a given process, you can examine the file descriptors that it has open by running ls -l /proc/PID/fd 379

where PID is replaced by the process ID. 380

9. You can use the --trace-children=no and --child-silent-after-fork=yes options to valgrind when 381

checking for memory leaks. This will look only at uqfindexec and ignore child processes. 382

Suggested Approach 383

It is suggested that you write your program using the following steps. Test your program at each stage and 384

commit to your SVN repository frequently. Note that the specification text above is the definitive description 385

of the expected program behaviour. The list below does not cover all required functionality. 386

1. Write a program that checks the command line arguments and exits with a usage error if they are invalid. 387

2. Add functionality to check that the directory is accessible and that the supplied command is valid. 388

© 2024 The University of Queensland 9 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 3. Add functionality to iterate over all files in a directory (and for now just print their names). 389

4. Add functionality to handle a single command (with arguments) being executed (and waited on) for each 390

file (no pipes or redirection) 391

5. Implement the placeholder substitution on the command/arguments 392

6. Add support for stdin and stdout redirection 393

7. Add support for a pipeline of commands 394

8. Implement remaining functionality as required . . . 395

Forbidden Functions, Statements etc. 396

You must not use any of the following C statements/directives/etc. If you do so, you will get zero (0) marks
2873 397

for the assignment. 398

• goto 399

• #pragma 2873 400

• gcc attributes (other than the possible use of __attribute__((unused)) as described in the style guide) 2873 401

You must not use any of the following C functions. If you do so, you will get zero (0) marks for any test case 402

that calls the function. 403

• longjmp() and equivalent functions 404

• system() 405

• popen() 2873 406

• mkfifo() or mkfifoat() 407

• signal(), sigpending(), sigqueue(), sigwaitinfo(), sigtimedwait(), sigsuspend() 408

• Any pthread* functions 409

• As noted in Other Requirements, you must not use the WNOHANG option when waiting. 410

• Functions described in the man page as non standard, e.g. strcasestr(). Standard functions will 411

conform to a POSIX standard – often listed in the “CONFORMING TO” section of a man page. Note 412

that getopt_long() and getopt_long_only() are an exception to this – these functions are permitted 413

if desired. 414

The use of comments to control the behaviour of clang-format and/or clang-tidy (e.g., to disable style 415

checking) will result in zero marks for automatically marked style. 416

Submission 417

Your submission must include all source and any other required files (in particular you must submit a Makefile). 418

Do not submit compiled files (e.g. .o, compiled programs). 2873 419

Your program (named uqfindexec) must build on moss.labs.eait.uq.edu.au and in the Gradescope 420

environment with: 421

make 422

Your program must be compiled with gcc with at least the following options: 423

-Wall -Wextra -pedantic -std=gnu99 424

You are not permitted to disable warnings or use pragmas to hide them. You may not use source files other 425

than .c and .h files as part of the build process – such files will be removed before building your program. 2873 426

If any errors result from the make command (i.e. the uqfindexec executable can not be created) then you 427

will receive 0 marks for functionality (see below). Any code without academic merit will be removed from your 428

program before compilation is attempted (and if compilation fails, you will receive 0 marks for functionality). 2873 429

Your program must not invoke other programs (other than those expected to be invoked when running a 430

command or command pipeline) or use non-standard headers/libraries. 431

Your assignment submission must be committed to your subversion repository under 432

https://source.eait.uq.edu.au/svn/csse2310-sem1-sXXXXXXX/trunk/a3 433

© 2024 The University of Queensland 10 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 434

files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these 435

will not be considered in marking – they will not be checked out of your repository. 436

You must ensure that all files needed to compile and use your assignment (including a Makefile) are commit- 437

ted and within the trunk/a3 directory in your repository (and not within a subdirectory) and not just sitting 438

in your working directory. Do not commit compiled files or binaries. You are strongly encouraged to check out 439

a clean copy for testing purposes. 440

To submit your assignment, you must run the command 2873 441

2310createzip a3 442

on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 443

available in the Assessment area on the CSSE2310/7231 Blackboard site)6 . The zip file will be named 444

sXXXXXXX_csse2310_a3_timestamp.zip 445

where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 446

the time that the zip file was created. 447

The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 448

ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your 449

Subversion commit history and a checksum of the zip file contents. You may be asked for your password as 450

part of this process in order to check out your submission from your repository. You will be asked to confirm 451

references in your code and also to confirm your use (or not) of AI tools to help you. 2873 452

You must not create the zip file using some other mechanism and you must not modify the zip file prior 453

to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file 454

is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 455

creation of your submission zip file. 456

We will mark your last submission, even if that is after the deadline and you made submissions before the 457

deadline. Any submissions after the deadline7 will incur a late penalty – see the CSSE2310/7231 course profile 458

for details.2873 459

Note that Gradescope will run the test suite immediately after you submit. When complete8 you will be 460

able to see the results of the “public” tests. You should check these test results to make sure your program is 461

working as expected. 462

Marks 463

Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked 464

to attend an interview about your assignment and you are unable to adequately respond to questions – see the 465

Student conduct section above. 466

Functionality (60 marks CSSE2310 / 70 marks CSSE7231) 467

Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), and 468

your zip file has been generated correctly and has not been modified prior to submission, then you will earn 469

functionality marks based on the number of features your program correctly implements, as outlined below. 470

Not all features are of equal difficulty. Partial marks will be awarded for partially meeting the functionality 471

requirements. A number of tests will be run for each marking category listed below. Your mark in that category 472

will be proportional (or approximately proportional) to the number of tests passed in that category. 473

If your program does not allow a feature to be tested then you will receive 0 marks for that 474

feature, even if you claim to have implemented it. For example, if your program can never create a child 475

process then we can not determine whether pipes are created successfully. Your tests must run in a reasonable 476

time frame, which could be as short as a few seconds for usage checking to many tens of seconds when valgrind 477

is used to test for memory leaks. If your program takes too long to respond, then it will be terminated and you 478

will earn no marks for the functionality associated with that test. The markers will make no alterations to your 479

code (other than to remove code without academic merit). 2873 480

Functionality marks (out of 60 total) will be assigned in the following categories (CSSE2310 and CSSE7231): 481

6 You 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.

7 or your extended deadline if you are granted an extension.
8 Gradescope 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

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 1. Program correctly handles invalid command lines (usage errors). (6 marks) 482

2. Program correctly handles an invalid directory argument. (2 marks) 483

3. Program correctly handles an invalid command argument. (2 marks) 484

4. Program correctly handles an empty command line (in a variety of directories) – i.e. the 485

default command that prints each filename is run. (6 marks) 486

5. Program correctly handles the --dir option argument and value (with no other 487

command line arguments). (4 marks) 488

6. Program correctly handles the --allfiles option (with and without the --dir 489

option argument and value specified but no other command line arguments). (5 marks) 490

7. Program correctly handles execution with filename substitution when the cmd 491

argument is just a single command (i.e. possibly with arguments and redirection but 492

no pipeline). A variety of combinations of --allfiles and --dir arguments 493

will be used. (This includes detection of commands that can’t be executed and 494

input/output files that can’t be opened.) 2873 (6 marks) 495

8. Program correctly handles execution with filename substitution when the cmd 496

argument is a pipeline of commands. A variety of combinations of --allfiles and 497

--dir arguments will be used. (6 marks) 498

9. Program correctly implements statistics generation when --report is specified 499

(for a variety of execution scenarios). (Parallel execution and interruption will 500

not be tested in this category.) (6 marks) 501

10. Program correctly implements parallel execution (with a variety of other command 502

line arguments, including statistics generation). (5 marks) 503

11. Program correctly implements interruption (signal handling) (for a variety of execution 504

scenarios). (4 marks) 505

12. Program correctly closes all unnecessary file descriptors in child processes (for a variety 506

of execution scenarios, i.e. any potential valid combination of command line arguments). 2873 (4 marks) 507

13. Program frees all allocated memory prior to exit (original process, not children) (for a 508

variety of execution scenarios, i.e. any potential valid combination of command line 509

arguments). (4 marks) 510

Some functionality may be assessed in multiple categories – e.g. successful filename substitution will be 511

required in many tests after category 8. Correct output will also be required when checking the closure of file 512

descriptors and memory use in categories 12 and 13. 513

Functionality marks (out of 10) will be assigned in the following categories (CSSE7231 only): 514

14. Program correctly implements recursion functionality with no cmd specified for a 515

variety of directories with and without the --dir option and value specified 516

(but no other arguments) (3 marks) 517

15. Program correctly implements recursion functionality without --parallel being 518

specified but with a variety of other arguments specified (including pipelines of commands) (4 marks) 519

16. Program correctly implements recursion functionality with --parallel also specified (3 marks) 520

Style Marking 521

Style marking is based on the number of style guide violations, i.e. the number of violations of version 3 of the 522

CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of two 523

components – automated style marks and human style marks. These are detailed below. Your style marks can 524

never be more than your functionality mark – this prevents the submission of well styled programs which don’t 525

meet at least a minimum level of required functionality. 526

© 2024 The University of Queensland 12 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
 You should pay particular attention to commenting so that others can understand your code. The marker’s 527

decision with respect to commenting violations is final – it is the marker who has to understand your code. 528

You are encouraged to use the 2310reformat.sh and 2310stylecheck.sh tools installed on moss to cor- 529

rect and/or check your code style before submission. The 2310stylecheck.sh tool does not check all style 530

requirements, but it will determine your automated style mark (see below). Other elements of the style guide 531

are checked by humans. 532

All .c and .h files in your submission will be subject to style marking. This applies whether they are 533

compiled/linked into your executable or not9 . 534

Automated Style Marking (5 marks) 535

Automated style marks will be calculated over all of your .c and .h files as follows. If any of your submitted 536

.c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). If 537

your code uses comments to control the behaviour of clang-format and/or clang-tidy then your automated 538

style mark will be zero. If any of your source files contain C functions longer than 100 lines of code10 then your 539

automated and human style marks will both be zero. If you use any global variables (other than a single flag 540

of bool type for signal handling) then your automated and human style marks will both be zero. 541

If your code does compile and does not contain any C functions longer than 100 lines and does not use 542

any global variables (other than a single flag of bool type for signal handling) and does not interfere with the 543

expected behaviour of clang-format and/or clang-tidy then your automated style mark will be determined 544

as follows: Let 545

• W be the total number of distinct compilation warnings recorded when your .c files are individually built 546

(using the correct compiler arguments) 547

• A be the total number of style violations detected by 2310stylecheck.sh when it is run over each of your 548

.c and .h files individually11 . 549

Your automated style mark S will be 550

S = 5 − (W + A) 551

If W + A ≥ 5 then S will be zero (0) – no negative marks will be awarded. If you believe that 552

2310stylecheck.sh is behaving incorrectly or inconsistently then please bring this to the attention of the 553

course coordinator prior to submission, e.g., it is possible the style checker may report different issues on moss 554

than it does in the Gradescope environment. Your automated style mark can be updated if this is deemed to 555

be appropriate. You can check the result of Gradescope style marking soon after your Gradescope submission 556

– when the test suite completes running. 557

Human Style Marking (5 marks) 558

The human style mark (out of 5 marks) will be based on the criteria/standards below for “comments”, “nam- 559

ing” and “modularity”. Note that if your code contains any functions longer than 100 lines or uses a global 560

variable (other than a single flag of bool type for signal handling) then your human style mark is zero and the 561

criteria/standards below are not relevant. 562

The meanings of words like appropriate and required are determined by the requirements in the style guide. 563

9 Make sure you remove any unneeded files from your repository, or they will be subject to style marking.
10 Note 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.
11 Every .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

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
Comments (3 marks) 564

Mark Description
25% or more of the comments that are present are inappropriate AND/OR at least 50% of the
0
required comments are missing
At least 50% of the required comments are present AND the vast majority (75%+) of comments
1
present are appropriate AND the requirements for a higher mark are not met 565

All or almost all required comments are present AND all or almost all comments present are appro-
2
priate AND the requirements for a mark of 3 are not met
All required comments are present AND all comments present are appropriate AND additional
3
comments are present as appropriate to ensure clarity
Naming (1 mark) 566

Mark Description
0 At least a few names used are inappropriate
567
0.5 Almost all names used are appropriate
1 All names used are appropriate
Modularity (1 mark) 568

Mark Description
0 There are two or more instances of poor modularity (e.g. repeated code blocks)
569
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

SVN Commit History Marking (5 marks) 570

Markers will review your SVN commit history for your assignment up to your submission time. This element 571

will be graded according to the following principles: 572

• Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will 573

yield a score of zero for this section). Progressive development is expected, i.e., no large commits with 574

multiple features in them. 575

• Appropriate use of log messages to capture the changes represented by each commit. (Meaningful messages 576

explain briefly what has changed in the commit (e.g. in terms of functionality, not in terms of specific 577

numbered test cases in the test suite) and/or why the change has been made and will be usually be more 578

detailed for significant changes.). 579

The standards expected are outlined in the following rubric. The mark awarded will be the highest for which 580

the relevant standard is met. 581

Mark
Description
(out of 5)
Minimal commit history – only one or two commits OR
0
all commit messages are meaningless.
Some progressive development evident (three or more commits) AND
1
at least one commit message is meaningful.
Progressive development is evident (multiple commits) AND
2 582
at least half the commit messages are meaningful
Multiple commits that show progressive development of almost all or all functionality AND
3
at least two-thirds of the commit messages are meaningful.
Multiple commits that show progressive development of ALL functionality AND
4
meaningful messages for all but one or two of the commits.
Multiple commits that show progressive development of ALL functionality AND
5
meaningful messages for ALL commits.

© 2024 The University of Queensland 14 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59
Total Mark 583

Let 584

• F be the functionality mark for your assignment (out of 60 for CSSE2310 students or out of 70 for 585

CSSE7231 students). 586

• S be the automated style mark for your assignment (out of 5). 587

• H be the human style mark for your assignment (out of 5). 588

• C be the SVN commit history mark (out of 5). 589

• V is the scaling factor (0 to 1) determined after interview(s) (if applicable – see the Student Conduct 590

section above) – or 0 if you fail to attend a scheduled interview without having evidence of exceptional 591

circumstances impacting your ability to attend. 592

Your total mark for the assignment will be: 593

M = (F + min{F, S + H} + min{F, C}) × V 594

out of 75 (for CSSE2310 students) or out of 85 (for CSSE7231 students). 595

In other words, you can’t get more marks for style or SVN commit history than you do for functionality. 596

Pretty code that doesn’t work will not be rewarded! 597

Late Penalties 598

Late penalties will apply as outlined in the course profile. 599

Specification Updates 600

Any clarifications or updates to the assignment specification will be summarised here. Any updated versions 601

of the specification will be released with adequate time for students to respond prior to due date. Potential 602

specification errors or omissions can be discussed on the discussion forum.

2873 603

604

Version 1.1 605

• Added clarification about invalid command lines. 606

• Clarified that symbolic links to inaccessible targets can be either included or excluded from processing. 607

• Added additional hint information about determining the type of a directory entry. 608

• Reinforced that all processes in a pipeline must be created before any are reaped. 609

• Added hint about detecting execution failure. 610

611

Version 1.2 612

• Added clarifications to multiple marking categories. 2873 613

• Added hints about examining open file descriptors and checking for memory leaks. 614

• Added clarification of when to exit with status 19 (due to interruption). 615

• Added some additional spaces where text had run together. 616

© 2024 The University of Queensland 15 Version 1.2

Document created for Abhinav PRADEEP (s4803941) only. Document generated 2024-04-24 13:59