The University of Queensland
School of Electrical Engineering and Computer Science
CSSE2310/CSSE7231 — Semester 2, 2023
Assignment 4 (version 1.1 - 13 October 2023)
Do not share this document. Sharing this document may result in a misconduct penalty.
Specification changes since version 1.0 are shown in red and are summarised at the end of the document.
Introduction 1
The goal of this assignment is to further develop your C programming skills, and to demonstrate your un- 2
derstanding of networking and multithreaded programming. You are to create two programs which together 3
implement a real-time, online auction platform. The main program – auctioneer – is a network server which 4
accepts connections from clients (including auctionclient which you will implement). Clients connect, and 5
interact with auctioneer in various ways to sell and buy items. 2263 6
Communication between the clients and auctioneer is over TCP using a newline-terminated text command 7
protocol. Advanced functionality such as connection limiting, signal handling and statistics reporting are also 8
required for full marks. CSSE7231 students shall also implement a simple HTTP interface to auctioneer. 9
The assignment will also test your ability to code to a particular programming style guide and to use a 10
revision control system appropriately. 11
Student Conduct 12
This section is unchanged from assignments one and three – but you should remind yourself of the referencing
requirements. Remember that you can’t copy code from websites and if you learn about how to use a library
function from a website then you must reference it.
13
This is an individual assignment. You should feel free to discuss general aspects of C programming and 14
the assignment specification with fellow students, including on the discussion forum. In general, questions like 15
“How should the program behave if hthis happensi?” would be safe, if they are seeking clarification on the 16
specification. 17
You must not actively help (or seek help from) other students or other people with the actual design, structure 18
and/or coding of your assignment solution. It is cheating to look at another student’s assignment code 19
and it is cheating to allow your code to be seen or shared in printed or electronic form by others. 20
All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or 21
collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if 22
you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your 23
code to a public place such as the course discussion forum or a public code repository. (Code in private posts 24
to the discussion forum is permitted.) You must assume that some students in the course may have very long 25
extensions so do not post your code to any public repository until at least three months after the result release 26
date for the course (or check with the course coordinator if you wish to post it sooner). Do not allow others to 27
access your computer – you must keep your code secure. Never leave your work unattended. 28
You must follow the following code referencing rules for all code committed to your SVN repository 29
(not just the version that you submit): 30
Code Origin Usage/Referencing
Code provided to you in writing this semester by
CSSE2310/7231 teaching staff (e.g. code hosted on Blackboard, 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.)
© 2023 The University of Queensland
1 Version 1.1 - 13 October 2023
Code Origin Usage/Referencing
Code examples found in man pages on moss. 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 you have personally written in a previous enrolment
in this course or in another ITEE course and where that
code has not been shared or published.
Code (in any programming language) that you have
learned from or that you have taken inspiration from but
have not copied1.
Code written by, modified by, or obtained from, or code
based on code written by, modified by, or obtained from,
a code generation tool (including any artificial intelligence
tool) that you personally have interacted with, without the
assistance of another person.
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 repository 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 referencing and without inclusion of the
toolHistory.txt file then this will be considered misconduct.
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); code
from public or private repositories; code from websites or
based on code from websites; code from textbooks; any
code written or partially written or provided by or written
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
removed from your assignment prior to marking (which
may cause compilation to fail and zero marks to be
awarded). Copied code without adjacent referencing will
be considered misconduct and action will be taken.
You must not share this assignment specification with any person, organisation, website, etc. Up- 31
loading or otherwise providing the assignment specification or part of it to a third party including online tutorial 32
and contract cheating websites is considered misconduct. The university is aware of many of these sites and 33
many cooperate with us in misconduct investigations. You are permitted to post small extracts of this document 34
to the course Ed Discussion forum for the purposes of seeking or providing clarification on this specification. 35
The teaching staff will conduct interviews with a subset of students about their submissions, 36
for the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from 37
this process. If you legitimately use code from other sources (following the usage/referencing requirements in the 38
table above) then you are expected to understand that code. If you are not able to adequately explain the design 39
of your solution and/or adequately explain your submitted code (and/or earlier versions in your repository) 40
and/or be able to make simple modifications to it as requested at the interview, then your assignment mark will 41
be scaled down based on the level of understanding you are able to demonstrate and/or your submission may 42
be subject to a misconduct investigation where your interview responses form part of the evidence. Failure to 43
attend a scheduled interview will result in zero marks for the assignment. The use of referenced code in your 44
submission (particularly from artificial intelligence tools) is likely to increase the probability of your selection 45
for an interview. 46
In short – Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. 47
Don’t be tempted to copy another student’s code or to use an online cheating service. Don’t help another 48
CSSE2310/7231 student with their code no matter how desperate they may be and no matter how close your 49
relationship. You should read and understand the statements on student misconduct in the course profile and 50
on the school website: https://eecs.uq.edu.au/current-students/guidelines-and-policies-students/ 51
student-conduct. 52
Online auctions 53
In a simple auction, an item is put up for sale by a seller. One or more buyers then place bids – statements 54
describing how much they are willing to pay for the item. Each bid must be higher than the previous. Buyers 55
may place multiple bids, so long as each is higher than the current maximum bid. Once a buyer has set the 56
highest bid, they may not bid again until a different buyer places a higher bid on the item. At the end of the 57
auction, the highest bidder is the winner. 58
1Code from elsewhere must not be directly copied or just converted from one programming language to another.
© 2023 The University of Queensland
2 Version 1.1 - 13 October 2023
The seller sets a reserve price – the lowest amount they are willing to sell the item for. If the auction does 59
not reach the reserve price, the auction ends with the item unsold. The item is described as being passed in, 60
and there is no winner. Any bids below the reserve price are rejected. 2263 61
The auctioneer manages the auction. They receive items and their reserve prices from sellers, and accept 62
bids from potential buyers. The auctioneer is responsible for rejecting invalid bids – such as ones that do not 63
exceed the current maximum bid, and those that are below the reserve. 64
Online auctions face some challenges – automated buying agents can attempt to wait until the very last 65
moments of an auction, and place a bid that is fractionally above the current highest bid, seeking to win the 66
auction for the lowest possible price. This strategy is known as sniping. Because sniping can give an unfair 67
advantage over regular, human-placed bids, it is common to place limits on how frequently bids may be made. 68
In this assignment, all auctions are time-limited, with the duration being specified by the seller when placing 69
the item up for auction. The auctioneer is the final arbiter of time. Bids received after an auction has finished, 70
even if they were sent before expiration, are rejected. 2263 71
Specification – auctionclient 72
The auctionclient program provides a command line interface that allows you to interact with the server 73
(auctioneer) as a client – connecting, placing items for sale, finding items available, bidding on other auctions 74
currently underway, and receiving and displaying the results of the auctions on your items. 75
To implement this functionality, auctionclient will probably require two threads – one for handling stdin 76
and sending commands to the server, and another for handling messages from the server. You may optionally 77
use a single thread and multiplexed I/O, such as poll() or select(), however this is not required. 78
Command Line Arguments 79
Your auctionclient program is to accept command line arguments as follows: 80
./auctionclient portnum 81
• The mandatory portnum argument indicates which localhost port the server is listening on – either nu- 82
merical or the name of a service. 83
auctionclient behaviour 84
If an incorrect number of command line arguments is provided then auctionclient should emit the following 85
message (terminated by a newline) to stderr and exit with status 19: 86
Usage: auctionclient portnum
If the correct number of arguments is provided, then further errors are checked for in the order below. 87
Connection error 88
If auctionclient is unable to connect to the auction server on the specified port (or service name) of localhost, 89
it shall emit the following message (terminated by a newline) to stderr and exit with status 20: 90
auctionclient: connection failed to port N
where N should be replaced by the argument given on the command line. (This may be a non-numerical string.) 91
auctionclient runtime behaviour 92
Assuming that the commandline arguments are without errors, auctionclient is to perform the following 93
actions: 94
• connect to the server on the specified port number (or service name) – see above for how to handle a 95
connection error; 96
• read commands from stdin, and handle them as described below; and 97
• echo all lines received from the auctioneer to stdout.2263 98
© 2023 The University of Queensland
3 Version 1.1 - 13 October 2023
If the network connection to the server is closed (e.g. auctionclient detects EOF on the socket, or receives
SIGPIPE), then auctionclient shall emit the following message to stderr and terminate with exit status 5:
auctionclient: server has gone away
auctionclient shall interpret its input from stdin as follows: 99
• Blank lines (i.e. those lines containing no characters), and those beginning with the # character (comment 100
lines), shall be ignored. (“beginning with” means the # character is in the leftmost position on the line.) 101
• The command quit on a line by itself shall cause the auctionclient to exit (with exit status 0) if the 102
client is not currently involved in any auctions, i.e., any auctions for which that client submitted an 103
item for sale are completed, and that client is not currently the highest bidder on any auctions. If those 104
conditions are not true, then the client must print (and flush) the following message to stdout: 105
Auction in progress - can not exit yet
and must not exit. 106
• All other lines shall be sent unaltered to the server (no error checking is required or to be performed) 107
If auctionclient detects EOF on stdin then it will exit. If the client still has auctions in progress (i.e. it 108
has offered one or more items for sale and those auctions haven’t expired, or if it is currently the highest bidder 109
on one or more auctions) then auctionclient must print the following to stderr and exit with exit status 4: 110
Quitting with auction(s) still in progress
Otherwise (i.e. the client is not involved in any current auctions), it will print nothing and exit with exit 111
status 0. 112
Upon sending a command to the server, auctionclient shall expect a single line reply as per the commu- 113
nication protocol described in Communication protocol. 114
Other than SIGPIPE (which is required to gracefully handle the unexpected disconnection by the server) 115
your auctionclient program is not to register any signal handlers nor attempt to mask or block any signals. 116
auctionclient termination 117
The recommended architecture for the auctionclient is to have one thread handling stdin and sending 118
commands to the server, and another thread for receiving and interpreting responses from the server. (Note 119
that you only need two threads total, not a “main” thread that creates two other threads to do this.) Since 120
blocking reads will be performed on stdin and the server socket, it is difficult to use the methods described in 121
lectures for cleaning up threads (e.g. a “terminate“ flag variable in a shared data structure). For this reason, 122
when either thread detects a valid termination condition for the program, it may simply call 123
exit() immediately – you should not attempt to use pthread_cancel() or any other, more complicated 124
termination mechanism. 2263 125
The command protocol (see Communication protocol) is designed such that auctionclient can easily keep 126
track of how many auctions it is currently involved in – both as a seller and/or a buyer. All commands sent 127
to auctioneer, whether correct or not, generate replies. By interpreting these replies, auctionclient can 128
determine when all of its auctions have completed. For the purposes of determining this condition, the client 129
may assume that the server is correct and well-behaved. 130
auctionclient example usage 131
The following is an example of an interactive session with auctionclient (assuming the auctioneer is listening 132
on port 49152). Lines in bold face are typed interactively on the console, they are not part of the output of 133
the program. Lines in italics are explanatory comments on the overall system state, and do not appear in the 134
terminal output): 2263 135
1 $ ./auctionclient 49152
2 # A comment line - ignored
3 # A blank line - ignored
45 # An invalid item listing, missing an argument
6 sell chicken 10
© 2023 The University of Queensland
4 Version 1.1 - 13 October 2023
7 :invalid
8 # A simple item listing, reserve 10, 30 second auction
9 sell chicken 10 30
10 :listed chicken
11 # A duplicate item listing
12 sell chicken 20 60
13 :rejected
14 # Attempt to bid on own item
15 bid chicken 1000
16 :rejected
17 # Another item for sale
18 sell potato 10 30
19 :listed potato
20 # Invalid listing - non-numeric reserve price
21 sell apple zz 60
22 :invalid
23 (...time passes, chicken auction over but no bids over reserve ...)
24 :unsold chicken
25 # Fast auction on a cow (5 seconds)
26 sell cow 1000 5
27 :listed cow
28 # See all items available (note our items are listed but so too is pumpkin
29 # listed by a different client before ours. We can see current bids on our items as well)
30 list
31 :list pumpkin 10 100 76|potato 10 20 7|cow 1000 2000 2|
32 # Bid on the pumpkin, which is accepted
33 bid pumpkin 110
34 :bid pumpkin
35 (...time passes, somebody else outbids us on pumpkin ...)
36 :outbid pumpkin
37 (...time passes, fast cow auction finishes ...)
38 :sold cow 2500
39 # try to quit, but potato still unsold
40 quit
41 Auction in progress - can not exit yet
42 (...time passes ...potato has now sold - we have no more ‘live’ auctions)
43 :sold potato 20
44 # now the quit command can succeed
45 quit
Note that not all possible error conditions are present in this example. 136
Further note that the auctionclient must keep track of items it has listed as they are sold or 137
passed-in – this is the only way it can determine whether it can exit or not. Similarly, it must 138
also keep track of items for which it is the highest bidder. 139
Specification – auctioneer 140
auctioneer is a networked, multithreaded auction server allowing clients to connect, submit items for sale, bid 141
on items, and list the items currently available. All communication between clients and the server is over TCP 142
using a simple command protocol that is described in the Communication protocol section. 2263 143
Command Line Arguments 144
Your auctioneer program is to accept command line arguments as follows: 145
./auctioneer [--maxconn num-connections ] [--port portnum ] 146
In other words, your program should accept up to three two optional arguments (two with associated values) 147
– which can be in any order. 148
© 2023 The University of Queensland
5 Version 1.1 - 13 October 2023
The num-connections argument, if specified, indicates the maximum number of simultaneous client con- 149
nections to be permitted. If this is zero or absent, then there is no limit to how many clients may connect (other 150
than operating system limits which we will not test). 151
The portnum argument, if specified, indicates which localhost port auctioneer is to listen on. If the port 152
number is absent or zero, then auctioneer is to use an ephemeral port. 2263 153
Important: Even if you do not implement the connection limiting functionality, your program must correctly 154
handle command lines which include either of those arguments (after which it can ignore any provided values 155
– you will simply not receive any marks for that feature). 156
Program Operation 157
The auctioneer program is to operate as follows: 158
• If the program receives an invalid command line then it must print the message: 159
Usage: auctioneer [--maxconn num-connections] [--port portnum]
to stderr, and exit with an exit status of 19. 160
Invalid command lines include (but may not be limited to) any of the following: 161
– either of --maxconn or --port does not have an associated value argument 162
– the num-connections argument (if present) is not a non-negative integer 163
– the port number (portnum ) argument (if present) is not an integer value, or is an integer value and 164
is not either zero, or in the range of 1024 to 65535 inclusive 165
– any of the arguments is specified more than once 166
– any additional arguments are supplied 167
• If portnum is missing or zero, then auctioneer shall attempt to open an ephemeral localhost port for 168
listening. Otherwise, it shall attempt to open the specified port number. If auctioneer is unable to listen 169
on either the ephemeral or specified port, it shall emit the following message to stderr and terminate 170
with exit status 4: 171
auctioneer: unable to open socket for listening
• Once the port is opened for listening, auctioneer shall print to stderr the port number followed by a 172
single newline character and then flush the output. In the case of ephemeral ports, the actual port 173
number obtained shall be printed, not zero.2263 174
• Upon receiving an incoming client connection on the port, auctioneer shall spawn a new thread to handle 175
that client (see below for client thread handling). 176
• If specified (and implemented), auctioneer must keep track of how many active client connections exist, 177
and must not let that number exceed the connections parameter. See below on client handling threads 178
for more details on how this limit is to be implemented. 179
• Note that all error messages above must be terminated by a single newline character. 180
• The auctioneer program should not terminate under normal circumstances, nor should it block or oth- 181
erwise attempt to handle SIGINT. 182
• Note that your auctioneer must be able to deal with any clients using the correct communication protocol, 183
not just the client programs specified for the assignment. Testing with netcat is highly recommended. 184
Client handling threads 185
A client handler thread is spawned for each incoming connection. This client thread must then wait for commands 186
from the client, one per line, over the socket. The exact format of the requests is described in the Communication 187
protocol section below. 188
Due to the simultaneous nature of the multiple client connections, your auctioneer will need to ensure 189
mutual exclusion around any shared data structure(s) to ensure that these do not get corrupted. 190
Once a client disconnects or there is a communication error on the socket then the client handler thread is 191
to close the connection, clean up and terminate. Other client threads and the auctioneer program itself must 192
continue uninterrupted. 193
© 2023 The University of Queensland
6 Version 1.1 - 13 October 2023
Auction running algorithm 194
The auction is run according to the following algorithm. Refer to the Communication protocol section for details 195
of message syntax and required responses. 196
• auctioneer receives new items to auction via the sell command. The arguments to this command are 197
validated and if correct, the item is now available for sale. If the command is invalid, the client is informed 198
and the sell command does not succeed. 2263 199
• auctioneer receives bids on sale items via the bid command. If the command syntax is valid, the item 200
exists and is currently available, and the bid on the item is higher than any previous bid on the same 201
item, then the bidding client is remembered as the current winning bidder for that item. If there was a 202
previous winning bidder, that client is sent an outbid message informing it that it has been outbid on the 203
item. If an invalid bid command is received, then the bidding client is informed and the bid is otherwise 204
ignored by auctioneer. 205
• auctioneer accepts the list command from any connected client, regardless of whether that client has 206
listed or bid on any items. The list command returns a formatted list describing each item available, its 207
reserve price, current maximum bid, and the time remaining in the auction for that item. 208
• When the auction on any item completes (reaches the expiry time), auctioneer takes one of the two 209
following actions: 210
– If there is a winning bid which is greater than or equal to the reserve price, then the winning bidder is 211
sent a win message identifying the item and the winning bid amount. The seller of the item receives 212
a sold message indicating the item that was sold and the winning bid amount. 213
– If there were no bids on the item, or no bids at or above the reserve price, then auctioneer sends 214
a unsold message to the seller, informing it that the item did not sell. No message is sent to any 215
previous bidding client in the event that the item goes unsold. 216
• Advanced: auctioneer is to limit bids from clients to a maximum of one bid per item per second. That 217
is, if a client has an accepted bid on an item more recently than one second ago, a rejected message is 218
sent in reply. Rate limiting is not to be implemented. 219
About time 220
auctioneer relies on time to determine when auctions expire. Expiry time is at the resolution of milliseconds. 221
The following approach to handling time and auction expiry is recommended. You may choose another approach 222
if you wish as long as the behaviour is the same. 223
• the provided library function “double get_time_ms(void)” returns a floating point time value in seconds, 224
to millisecond resolution, e.g. the value 16.745 represents 16.745 seconds. 225
• for each auction item, store an expiry time (not a duration). So, as each new item is listed, store its expiry 226
time calculated by (get_time_ms() + duration). 227
• to report auction time remaining (e.g. for the list command), calculate (item.expiry - get_time_- 228
ms())) which will yield a floating point value, in seconds, until the auction expires. Note that the list 229
command shall report time remaining rounded down to the nearest second – see the Communication 230
protocol section for details. 231
The simplest way to check on expiring auctions is to run a dedicated server thread which periodically checks 232
the current time (get_time_ms()) against each item’s expiry time, and marks as ‘complete’ any such items 233
which have expired, and handle any necessary communication and cleanup associated with expired auctions. 234
Be mindful of locking and mutual exclusion, because client threads may also be accessing the auction data 235
structures while this is taking place. 236
Important: To avoid excessive busy waiting and CPU use, please have this auction expiry thread sleep() 237
for 100 milliseconds between each check through the item list. The usleep() library function can be used to 238
achieve this, although note that its argument is expressed as microseconds, not milliseconds! Excessive CPU 239
use in your solution will be checked for and may be penalised. 240
© 2023 The University of Queensland
7 Version 1.1 - 13 October 2023
Disconnecting clients 241
If a client disconnects before the end of an auction, (e.g. a read() or equivalent) from the client returns EOF, 242
or a write() or equivalent fails), the auctioneer is to simply ignore that fact for the purposes of the auction, 243
and close the network connection to that client, cleaning up data structures as required. 244
If a client disconnects, any auctions it was involved with proceed until they naturally expire. 245
So, if a disconnected client was selling an item, other clients may still bid on the item in the normal manner. 246
When the auction expires, auctioneer will inform the winning bidder, but will not attempt to send the sold 247
message to the now-disconnected seller, nor send the unsold message if no valid bids were received. 248
Similarly if a bidder disconnects mid-auction, the auction proceeds and their bid remains valid. 249
If this disconnected client ends up winning the auction, the selling client still receives the sold message, there 250
is just no attempt to communicate to the now-disconnected bidder. If a disconnected client gets outbid, the 251
outbid message is not sent. 252
SIGHUP handling (Advanced) 253
Upon receiving SIGHUP, auctioneer is to emit (and flush) to stderr statistics reflecting the program’s operation 254
to-date, specifically 255
• Total number of clients connected (at this instant) 256
• The total number of clients that have connected and disconnected since program start 257
• The number of active auctions in progress (at this instant) 258
• The total number of sell requests received (since program start), including invalid2
. and rejected requests 259
• The total number of accepted sell requests received (since program start) 260
• The total number of bid requests received (since program start), including invalid3 and rejected bids 261
• The total number of accepted bid requests received (since program start) 262
The required format is illustrated below. Each of the seven lines is terminated by a single newline. You can 263
assume that all numbers will fit in a 32-bit unsigned integer, i.e. you do not have to consider numbers larger 264
than 4,294,967,295. 2263 265
Listing 1: auctioneer SIGHUP stderr output sample
1 Connected clients: 4
2 Completed clients: 20
3 Active auctions: 2
4 Total sell requests: 20
5 Successful sell requests: 14
6 Total bid requests: 34
7 Successful bid requests: 31
Note that to accurately gather these statistics and avoid race conditions, you will need some sort of mutual 266
exclusion protecting the variables holding these statistics. 267
Global variables are NOT to be used to implement signal handling. See the Hints section below for how you 268
can implement this. 269
Client connection limiting (Advanced) 270
If the --maxconn num-connections feature is implemented and a non-zero command line argument is provided, 271
then auctioneer must not permit more than that number of simultaneous client connections to the server. 272
auctioneer shall maintain a connected client count, and if a client beyond that limit attempts to connect, it 273
shall block, indefinitely if required, until another client leaves and this new client’s connection request can be 274
accept()ed. Clients in this waiting state are not to be counted in statistics reporting – they are only counted 275
once they have properly connected. 2263 276
2An invalid sell request is one where the command word (characters before the first space on the request line) is “sell” but
the arguments are invalid – see the Communication protocol section for details.
3An invalid bid request is one where the command word is “bid” but the arguments are invalid – see the Communication
protocol section for details.
© 2023 The University of Queensland
8 Version 1.1 - 13 October 2023
HTTP connection handling (CSSE7231 students only) 277
CSSE7231 students shall, in addition, implement a simple HTTP server in their auctioneer implementa- 278
tion. Upon startup, auctioneer shall check the value of the environment variable A4_HTTP_PORT. If set, then 279
auctioneer shall also listen for connections on that port number (or service name). 280
If auctioneer is unable to listen on that port or service name then it shall emit the following message to 281
stderr and terminate with exit status 8: 282
auctioneer: unable to open HTTP socket for listening
The ability to listen on this port is checked after the ability to listen on the “main” port (i.e. the one given 283
on the command line). If the A4_HTTP_PORT environment variable is not set then auctioneer shall not listen 284
on any additional ports and shall not handle these HTTP connections. 285
The communication protocol uses HTTP. The connecting program (e.g. netcat, or a web browser) shall 286
send HTTP requests and auctioneer shall send HTTP responses as described below. The connection between 287
client and server is kept alive between requests. Multiple HTTP clients may be connected simultaneously. 288
Additional HTTP header lines beyond those specified may be present in requests or responses and must be 289
ignored by the respective server/client. Note that interaction between a client on the HTTP port and auctioneer 290
is synchronous – any one client can only have a single request underway at any one time. This greatly simplifies 291
the implementation of the auctioneer HTTP connection handling threads. 2263 292
The only supported request method is a GET request in the following format: 293
• Request: GET /stats HTTP/1.1 294
– Description: the client is requesting statistics from auctioneer 295
– Request 296
∗ Request Headers: none expected, any headers present will be ignored by auctioneer. 297
∗ Request Body: none, any request body will be ignored 298
– Response 299
∗ Response Status: 200 (OK). 300
∗ Response Headers: the Content-Length header with correct value is required (number of bytes 301
in the response body), other headers are optional. 302
∗ Response Body: the ASCII text containing the same auctioneer statistics information described 303
in the SIGHUP handling section above. 304
If auctioneer receives an invalid HTTP request then it should close the connection to that requestor (and 305
terminate the thread associated with that connection). Similarly, if a HTTP client disconnects, auctioneer 306
should handle this gracefully and terminate the thread associated with the connection. HTTP clients are NOT 307
included in the client count statistics. 308
Program output 309
Other than error messages, the listening port number, and SIGHUP-initiated statistics output, auctioneer is 310
not to emit any output to stdout or stderr. 311
Communication protocol 312
The communication protocol between clients and auctioneer uses simple newline-terminated text message 313
strings as described below. Note that the angle brackets are used to represent placeholders, and are not 314
part of the command syntax. 2263 315
Supported messages from a client to auctioneer are: 316
• sell - – the client is requesting to sell the item called
- , with a 317
reserve price of , with the auction lasting for seconds. 318
See below for the conditions that must be met for a sell command to be accepted. 319
• bid
- – the client is requesting to bid on the specified
- . 320
See below for the conditions that must be met for a bid command to be accepted. 321
• list – the client is requesting a list of items currently available for auction. See below for the reply format. 322
© 2023 The University of Queensland
9 Version 1.1 - 13 October 2023
Single spaces are used as separators between fields, which implies that - must not contain spaces. 323
All numerical values must be valid decimal integers (and subject to additional value requirements as described 324
below). 325
Supported messages from auctioneer to a client are as follows. Error conditions in messages should be 326
tested in this order as well – first look for “invalid” commands, then check to see if the command should be 327
“rejected”: 328
• :invalid – sent by the server to a client if any of the following conditions are true: 329
– Invalid command word – an empty string or a command word which is not sell, bid or list 330
– Too few or too many arguments 331
– An invalid value for a numerical field, including 332
∗ not a properly formed integer (e.g. “10.2”, “12p” etc) 333
∗ a negative reserve price in a sell command 334
∗ a duration of less than 1 second in a sell command 335
∗ a bid value of less than 1 in a bid command 336
– Any other kind of malformed message 2263 337
• :rejected – sent by the server to a client if one any of the following conditions is true: 338
– a client attempts to bid on an item which is not for sale 339
– a client attempts to bid on an item for which they are already the highest bidder 340
– the client sends a bid command but the bid amount is less than the reserve price or less than or 341
equal to the current maximum bid 342
– a client attempts to bid on an item that they themselves have listed for sale 343
– the client sent a sell command but there is already an item for sale by the same name 344
• :listed - – sent to the client when
- is successfully listed for auction 345
• :bid - - sent to the client when a bid is successfully placed on
- 346
• response to a list command, in the following format: 347
348
:list |. . . | | 349
350
That is, for each item currently available for auction, the name, reserve price, maximum bid so far, 351
and remaining time (rounded down to the nearest second) is emitted in a space-separated format, fol- 352
lowed by a vertical bar “|” character. Items should be reported in the same order that they were 353
submitted to auctioneer – there is no need to perform additional sorting on the list, simply 354
storing them in order of arrival is sufficient. Note that the rounding down of time means that the 355
remaining time for an item should be reported as 0 (zero) if the time remaining is between 0 and 1 seconds. 356
357
If there are no items currently available for auction, then the string “:list” is returned. 358
• :outbid - – the receiving (bidding) client has been outbid on
- , the new highest 359
bid is . 360
361
Note, the outbid client will receive no further notifications about this item unless they 362
bid again. They are effectively out of the auction at this point. 2263 363
• :won
- – the receiving bidding client won the auction on
- with their bid of 364
• :sold
- – the receiving selling client just sold
- for 365
• :unsold - – the receiving selling client had the given item passed-in, i.e. there were no bids at the 366
reserve price or higher when the auction expired 367
© 2023 The University of Queensland
10 Version 1.1 - 13 October 2023
Provided Libraries 368
libcsse2310a4 369
A split_by_char() function is available to break a line up into multiple parts, e.g. based on spaces. This is 370
similar to the split_line() function from libcsse2310a3 though allows a maximum number of fields to be 371
specified. 372
The get_time_ms() function will return a millisecond-precision, monotonically increasing time value to 373
support all time-related functions in this assignment. The specific value returned is not particularly meaningful, 374
however the difference between values returned from calls to this function can be used to accurately measure 375
the passage of time. 376
Several additional library functions have been provided to aid CSSE7231 students in parsing/construction 377
of HTTP requests/responses. The functions in this library are: 378
double get_time_ms(void);
char** split_by_char(char* str, char split, unsigned int maxFields);
int get_HTTP_request(FILE *f, char **method, char **address,
HttpHeader ***headers, char **body);
char* construct_HTTP_response(int status, char* statusExplanation,
HttpHeader** headers, char* body);
int get_HTTP_response(FILE *f, int* httpStatus, char** statusExplain,
HttpHeader*** headers, char** body);
void free_header(HttpHeader* header);
void free_array_of_headers(HttpHeader** headers);
These functions and the HttpHeader type are declared in /local/courses/csse2310/include/csse2310a4.h 379
on moss and their behaviour is described in man pages on moss – see get_time_ms(3), split_by_char(3), 380
get_HTTP_request(3), and free_header(3). 381
To use these library functions, you will need to add #include to your code and use the 382
compiler flag -I/local/courses/csse2310/include when compiling your code so that the compiler can find 383
the include file. You will also need to link with the library containing these functions. To do this, use the 384
compiler arguments -L/local/courses/csse2310/lib -lcsse2310a4 385
Finally, will need to link your programs with the -lm flag to add the maths library, required by the get_- 386
time_ms() function. 387
libcsse2310a3 388
You are also welcome to use the "libcsse2310a3" library from Assignment 3 if you wish. This can be linked 389
with -L/local/courses/csse2310/lib -lcsse2310a3. 390
Style 391
Your program must follow version 2.4.1 of the CSSE2310/CSSE7231 C programming style guide available on 392
the course Blackboard site. 393
Hints 394
1. Review the lectures related to network clients, threads and synchronisation and multi-threaded network 395
servers (and HTTP for CSSE7231 students). This assignment builds on all of these concepts. 396
2. You should test auctionclient and auctioneer independently using netcat as demonstrated in the 397
lectures. You can also use the provided demo programs demo-auctionclient and demo-auctioneer. 398
© 2023 The University of Queensland
11 Version 1.1 - 13 October 2023
3. The read_line() function from libcsse2310a3 may be useful in both auctionclient and auctioneer. 399
4. The multithreaded network server example from the lectures can form the basis of auctioneer. 400
5. Use the provided library functions (see above). 2263 401
6. Consider a dedicated signal handling thread for SIGHUP. pthread_sigmask() can be used to mask signal 402
delivery to threads, and sigwait() can be used in a thread to block until a signal is received. You will 403
need to do some research and experimentation to get this working. Be sure to properly reference any code 404
samples or inspiration you use. 405
7. Remember to fflush() output that you printf() or fprintf()! 406
Possible Approach 407
1. Try implementing auctionclient first. (The programs are independent so this is not a requirement, but 408
when you test it with demo-auctioneer it may give you a better understanding of how auctioneer 409
works.) 410
2. For auctioneer, start with the multithreaded network server example from the lectures, gradually adding 411
functionality for supported message types. 2263 412
3. Design a simple data structure for auctioneer to store items for sale. This data structure will be accessed 413
by client threads to add new items, determine validity of bids, and respond to list commands. It will 414
also need to be accessed by whichever thread checks for auction expiry. Locking and mutual exclusion will 415
be essential, but don’t over-complicate it! 416
Forbidden Functions 417
You must not use any of the following C statements/directives/etc. If you do so, you will get zero (0) marks for 418
the assignment. 419
• goto 420
• #pragma 421
• gcc attributes 422
You must not use any of the following C functions. If you do so, you will get zero (0) marks for any test case 423
that calls the function. 424
• longjmp() and equivalent functions 425
• system() 426
• mkfifo() or mkfifoat() 427
• fork(), pipe(), popen(), execl(), execvp() and other exec family members. 428
• pthread_cancel() 429
• Functions described in the man page as non standard 430
Submission 431
Your submission must include all source and any other required files (in particular you must submit a Makefile). 432
Do not submit compiled files (eg .o, compiled programs) or test files. 2263 433
Your programs (named auctionclient and auctioneer) must build on moss.labs.eait.uq.edu.au with: 434
make 435
If you only implement one of the programs then it is acceptable for make to just build that program – and 436
we will only test that program. 437
© 2023 The University of Queensland
12 Version 1.1 - 13 October 2023
Your programs must be compiled with gcc with at least the following switches (plus applicable -I options 438
etc. – see Provided Libraries above): 439
-pedantic -Wall -std=gnu99 440
You are not permitted to disable warnings or use pragmas or other methods to hide them. You may not use 441
source files other than .c and .h files as part of the build process – such files will be removed before building 442
your program. 2263 443
If any errors result from the make command (e.g. an executable can not be created) then you will receive 444
0 marks for functionality (see below). Any code without academic merit will be removed from your program 445
before compilation is attempted (and if compilation fails, you will receive 0 marks for functionality). 446
Your program must not invoke other programs or use non-standard headers/libraries (besides those we have 447
provided for you to use). 448
Your assignment submission must be committed to your subversion repository under 449
https://source.eait.uq.edu.au/svn/csse2310-sem2-sXXXXXXX/trunk/a4 450
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 451
files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these 452
will not be considered in marking – they will not be checked out of your repository. 453
You must ensure that all files needed to compile and use your assignment (including a Makefile) are commit- 454
ted and within the trunk/a4 directory in your repository (and not within a subdirectory) and not just sitting 455
in your working directory. Do not commit compiled files or binaries. You are strongly encouraged to check out 456
a clean copy for testing purposes – the reptesta4.sh script will do this for you. 2263 457
To submit your assignment, you must run the command 458
2310createzip a4 459
on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 460
available in the Assessment area on the CSSE2310/7231 Blackboard site)4
. The zip file will be named 461
sXXXXXXX_csse2310_a4_timestamp.zip 462
where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 463
the time that the zip file was created. 464
The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 465
ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your 466
Subversion commit history and a checksum of the zip file contents. You may be asked for your password as 467
part of this process in order to check out your submission from your repository. You will be asked to confirm 468
references in your code. 2263 469
You must not create the zip file using some other mechanism and you must not modify the zip file prior 470
to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file 471
is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 472
creation of your submission zip file. 473
We will mark your last submission, even if that is after the deadline and you made submissions before the 474
deadline. Any submissions after the deadline5 will incur a late penalty – see the CSSE2310/7231 course profile 475
for details. 476
Note that Gradescope will run the test suite immediately after you submit. When complete6 you will be 477
able to see the results of the “public” tests. 478
Marks 479
Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked 480
to attend an interview about your assignment and you are unable to adequately respond to questions – see the 481
Student conduct section above. 482
4You may need to use scp or a graphical equivalent such as WinSCP, Filezilla or Cyberduck in order to download the zip file to
your local computer and then upload it to the submission site.
5or your extended deadline if you are granted an extension.
6Gradescope marking may take only a few minutes or more than 30 minutes depending on the functionality/efficiency of your
code.
© 2023 The University of Queensland
13 Version 1.1 - 13 October 2023
Functionality (60 marks CSSE2310/ 70 marks CSSE7231) 483
Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), 484
and your zip file has not been modified prior to submission, then you will earn functionality marks based on 485
the number of features your program correctly implements, as outlined below. Partial marks will be awarded 486
for partially meeting the functionality requirements. Not all features are of equal difficulty. If your program 487
does not allow a feature to be tested then you will receive 0 marks for that feature, even if you 488
claim to have implemented it. Reasonable time limits will be applied to all tests. If your program takes longer 489
than this limit, then it will be terminated and you will earn no marks for the functionality associated with that 490
test. 2263 491
Exact text matching of files and output (stdout and stderr) and communication messages is 492
used for functionality marking. Strict adherence to the formats in this specification is critical to 493
earn functionality marks. 494
The markers will make no alterations to your code (other than to remove code without academic merit). 495
Note that your client and server will be tested independently. 496
Marks will be assigned in the following categories. There are 16 marks for auctionclient and 44 marks 497
(CSSE2310) or 54 marks (CSSE7231) for auctioneer. 498
1. auctionclient correctly handles invalid command lines (2 marks) 499
2. auctionclient connects to server and also handles inability to connect to server (2 marks) 500
3. auctionclient correctly handles input from stdin (i.e. sends appropriate lines to server) (3 marks) 501
4. auctionclient correctly displays lines received from the server (2 marks) 502
5. auctionclient correctly handles communication failure on the server socket 503
(includes handling SIGPIPE) (2 3 marks) 504
6. auctionclient correctly handles the quit command and EOF on stdin (5 4 marks) 505
7. auctioneer correctly handles invalid command lines (3 marks) 506
8. auctioneer correctly listens for connections and reports the port 507
(including inability to listen for connections) (2 marks) 508
9. auctioneer correctly handles invalid command messages (3 marks) 509
10. auctioneer correctly handles a single auction with correct expiry and bidding behaviour (5 marks) 510
11. auctioneer correctly handles multiple bidders on a single auction with correct expiry 511
and bidding behaviour (7 marks) 512
12. auctioneer correctly handles list requests (4 marks) 513
13. auctioneer correctly handles multiple simultaneous auctions from multiple clients 514
and multiple bidders (using threads) (7 marks) 515
14. auctioneer correctly handles disconnecting clients and communication failure (3 marks) 516
15. auctioneer correctly implements client connection limiting (3 marks) 517
16. auctioneer correctly implements SIGHUP statistics reporting (including protecting 518
data structures with mutexes or semaphores) (7 marks) 2263 519
17. (CSSE7231 only) auctioneer correctly listens on the port specified by A4_HTTP_PORT 520
(and handles inability to listen or environment variable not set) (3 marks) 521
18. (CSSE7231 only) auctioneer correctly responds to HTTP requests (including invalid requests) 522
from a single client issuing one request per connection (4 marks) 523
19. (CSSE7231 only) auctioneer supports multiple simultaneous HTTP clients and multiple 524
sequential requests over each connection (3 marks) 525
Some functionality may be assessed in multiple categories. The ability to support multiple simultaneous clients 526
will be covered in multiple categories. 527
© 2023 The University of Queensland
14 Version 1.1 - 13 October 2023
Style Marking 528
Style marking is based on the number of style guide violations, i.e. the number of violations of version 2.4.1 of 529
the CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of 530
two components – automated style marks and human style marks. These are detailed below. 531
You should pay particular attention to commenting so that others can understand your code. The marker’s 532
decision with respect to commenting violations is final – it is the marker who has to understand your code. To 533
satisfy layout related guidelines, you may wish to consider the indent(1) tool. Your style marks can never be 534
more than your functionality mark – this prevents the submission of well styled programs which don’t meet at 535
least a minimum level of required functionality. 536
You are encouraged to use the style.sh tool installed on moss to style check your code before submission. 537
This does not check all style requirements, but it will determine your automated style mark (see below). Other 538
elements of the style guide are checked by humans. 539
All .c and .h files in your submission will be subject to style marking. This applies whether they are 540
compiled/linked into your executable or not7. 541
Automated Style Marking (5 marks) 542
Automated style marks will be calculated over all of your .c and .h files as follows. If any of your submitted 543
.c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). 544
(Automated style marking can only be undertaken on code that compiles. The provided style.sh script checks 545
this for you.) 546
If your code does compile then your automated style mark will be determined as follows: Let 547
• W be the total number of distinct compilation warnings recorded when your .c files are individually built 548
(using the correct compiler arguments) 549
• A be the total number of style violations detected by style.sh when it is run over each of your .c and 550
.h files individually8. 551
Your automated style mark S will be 552
S = 5 5 (W + A) 553
If W +A ≥ 5 then S will be zero (0) – no negative marks will be awarded. Note that in some cases style.sh 554
may erroneously report style violations when correct style has been followed. If you believe that you have been 555
penalised incorrectly then please bring this to the attention of the course coordinator and your mark can be 556
updated if this is the case. Note also that when style.sh is run for marking purposes it may detect style 557
errors not picked up when you run style.sh on moss. This will not be considered a marking error – it is your 558
responsibility to ensure that all of your code follows the style guide, even if styling errors are not detected 559
in some runs of style.sh. You can check the result of Gradescope style marking soon after your Gradescope 560
submission – when its test suite completes running. 561
Human Style Marking (5 marks) 562
The human style mark (out of 5 marks) will be based on the criteria/standards below for “comments”, “naming” 563
and “other”. The meanings of words like appropriate and required are determined by the requirements in the 564
style guide. Note that functions longer than 50 lines will be penalised in the automated style marking. Functions 565
that are also longer than 100 lines will be further penalised here. 566
7Make sure you remove any unneeded files from your repository, or they will be subject to style marking.
8Every .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.
© 2023 The University of Queensland
15 Version 1.1 - 13 October 2023
Comments (2.5 marks) 567
Mark Description
0
The majority (50%+) of comments present are inappropriate OR there are many required comments
missing
0.5 The majority of comments present are appropriate AND the majority of required comments are
present
1.0 The vast majority (80%+) of comments present are appropriate AND there are at most a few missing
comments
1.5 All or almost all comments present are appropriate AND there are at most a few missing comments
2.0 Almost all comments present are appropriate AND there are no missing comments
2.5 All comments present are appropriate AND there are no missing comments
568
Naming (1 mark) 569
Mark Description
0 At least a few names used are inappropriate
0.5 Almost all names used are appropriate
1.0 All names used are appropriate
570
Other (1.5 marks) 571
Mark Description
0
One or more functions is longer than 100 lines of code OR there is more than one global/static
variable present inappropriately OR there is a global struct variable present inappropriately OR
there are more than a few instances of poor modularity (e.g. repeated code)
0.5 All functions are 100 lines or shorter AND there is at most one inappropriate non-struct global/static
variable AND there are at most a few instances of poor modularity
1.0
All functions are 100 lines or shorter AND there are no instances of inappropriate global/static
variables AND there is no or very limited use of magic numbers AND there is at most one instance
or poor modularity
1.5 All functions are 100 lines or shorter AND there are no instances of inappropriate global/static
variables AND there is no use of magic numbers AND there are no instances of poor modularity
572
SVN Commit History Marking (5 marks) 573
Markers will review your SVN commit history for your assignment up to your submission time. This element 574
will be graded according to the following principles: 575
• Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will 576
yield a score of zero for this section) 577
• Appropriate use of log messages to capture the changes represented by each commit. (Meaningful messages 578
explain briefly what has changed in the commit (e.g. in terms of functionality) and/or why the change 579
has been made and will be usually be more detailed for significant changes.) 580
The standards expected are outlined in the following rubric: 581
Mark
(out of 5) Description
0
Minimal commit history – only one or two commits OR
all commit messages are meaningless.
1
Some progressive development evident (three or more commits) AND
at least one commit message is meaningful.
2
Progressive development is evident (multiple commits) AND
at least half the commit messages are meaningful.
3
Multiple commits that show progressive development of ALL functionality (e.g. no large commits with multiple features in them) AND at least half the commit messages are meaningful.
4
Multiple commits that show progressive development of ALL functionality AND
meaningful messages for all but one or two of the commits.
5
Multiple commits that show progressive development of ALL functionality AND
meaningful messages for ALL commits.
582
© 2023 The University of Queensland
16 Version 1.1 - 13 October 2023
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 errors or omissions discovered in the assignment specification will be added here, and new versions released 601
with adequate time for students to respond prior to due date. Potential specification errors or omissions can be 602
discussed on the discussion forum or emailed to csse2310@uq.edu.au.2263 603
604
Version 1.1 605
• Clarified number of arguments for auctioneer. 606
• Added :unsold message to protocol description and noted that it should not be sent to a disconnected 607
client. 608
• Removed the description of advanced functionality – no rate limiting is to be implemented. 609
• Added hint about fflush()ing. 610
• Added note about two threads in the client. 611
• Added note about the :list response including remaining times of 0 (zero) if the time remaining is 612
between 0 and 1 seconds. 613
• Made it clear that the client handling communication failure on the server socket includes handling SIG- 614
PIPE. 615
• Modification of marks for auctionclient category 5 and 6. 616
© 2023 The University of Queensland
17 Version 1.1 - 13 October 2023