CS3103 Operating System

Project Instruction Document

Option A

Version 1.0

Note: All following steps are based on the given virtual machine which has been deployed with
all needed utilities. Issues caused by other development environments may exceed the scope of TA
support. If any questions, please contat Mr. SONG Ziwei via [email protected]
CS3103 Project Instruction Doc Option A

1 Supplement information
Before making introduce about Project (Option A), the basic usages of development environment
is shown as follows:

After correct import and startup of the given virtual machine (Please follows the guide
document provided), You may see the desktop view like the following figure. The marked folder
contains all needed files for Project (Option A).
It’s highly recommended to use VSCode as development platform, which has been already
installed in the virtual machine. Use VSCode to open the marked folder and start a new terminal
as the following figure depicts.

Then you can enter prompts in that terminal.

1
CS3103 Project Instruction Doc Option A

2
CS3103 Project Instruction Doc Option A

2 Project (Option A) Overview

The goal of Project (Option A):

• Learn how to synchronize the execution of processes and coordinate the use of shared
memory segment with POSIX Semaphores.
• Learn how to coordinate the execution of multiple threads in multi-threaded programming
with POSIX Thread.
• Learn to understand the file system and related directory/file operations.

Project (Option A) has two problems: Problem 1 and Problem 2. You will implement two C
programs to solve Problem 1 and Problem 2, respectively. For both problems, your implementa-
tion should comply with the proposed requirements. Since completing former problem will help
you with the later one more smoothly, it is highly recommended that you implement the two
programs for Problem 1 and Problem 2 in order.
To help you get started, some C program files in a compressed file named project.zip are avail-
able on the Google Drive, which is in /public/cs3103/project/, including the following files/di-
rectories:
Project
| - - test_case / # The t e s t c a s e d i r e c t o r y f o r p r o b l e m 2 .
| - - helpers . c # Useful functions
| - - helpers . h # Useful functions
| - - problem1 . c # The s o u r c e c o d e f i l e f o r p r o b l e m 1 .
| - - problem2 . c # The s o u r c e c o d e f i l e f o r p r o b l e m 2 .
‘-- Makefile # I t can be u s e d t o c o m p i l e s o u r c e c o d e .
In helper.h file, there are some helper functions, which are implemented in helper.c file,
that may be used for your programs. Please read the comments carefully to understand the
functionalities of the functions before using them. The provided Makefile can be directly used to
compile problem1.c. If you want to use it to compile other source files, please modify Makefile
before using it. For Problem 1, we provide the sample code in problem1.c about how to create
process and use shared memory segment and semaphores. Please implement your program for
Problem 2 in the file named problem2.c, where we have provided the necessary coding logic.
Tips: You can also learn how the shared memory and POSIX semaphore work and how to
use them in your program from online pages. Here are some useful links:
• Shared memory: https://man7.org/linux/man-pages/man7/shm overview.7.html
• Semaphore: https://man7.org/linux/man-pages/man7/sem overview.7.html

The following table lists some functions with brief description that may be used in this project,
you can click the name of functions for detail descriptions:

3
CS3103 Project Instruction Doc Option A

shmget() Allocate a shared memory segment

shmat() Shared memory attach operation
shmdt() Shared memory detach operation
shmctl() Perform the control operation for a shared memory
sem open() Initialize and open a named semaphore
sem init() Initialize an unnamed semaphore
sem wait() Lock a semaphore
sem post() Unlock a semaphore (similar to signal() in lecture)
sem close() Close a named semaphore
sem unlink() Remove a named semaphore
sem destroy() Destroy an unnamed semaphore
pthread create() Create a new thread
pthread join() Join with a terminated thread
pthread exit() Terminate the calling thread

4
CS3103 Project Instruction Doc Option A

3 Problem 1
3.1 Introduction
Problem 1 aims to help you understand how the shared memory and semaphores are used among
processes (or threads). Please implement your program in problem1.c, run it and answer the
questions about Problem 1.
In problem1.c, we use three types of variables, i.e., the global variable global param (line
17), the local variable local param (line 29), and the shared memory variables shared param p,
shared param c (line 30). The values of all variables are initialized to 0 (the shared memory is
automatically initialized).

We use the fork() system call to create a new child process. After that, the parent process and
child process will execute their own code independently and concurrently. The parent process
catches an input parameter in the command line from terminal (see 3.2 How to run Problem
1). The input parameter should be one of your group member’s CityU student
ID number, aka an eight-digit decimal number. Then the parent process assigns the
value of the input parameter to the three variables. The child process tries to get the input
parameter by reading the values of these variables and print them in terminal. We use the
semaphore PARAM ACCESS SEMAPHORE coordinate the operations on the variables between
the processes. In this way, we can ensure that only one process can access the variables at any
time, i.e., mutual exclusion.

3.2 How to run Problem 1

Compile problem1.c with the provided Makefile:
$ make
or by typing in terminal:
$ gcc problem1 . c helper . c -o problem1 -I . - pthread
If everything goes well, run the executable file with command:
$ ./ problem1 < input_param >

5
CS3103 Project Instruction Doc Option A

3.3 Questions of Problem 1

Please read code in problem1.c and learn how to use the shared memory and semaphore to
coordinate the execution of processes. Please answer the following two questions in our
project report.

3.3.1 Question 1 of Problem 1

Recall the introduction about the process creation and how processes communicate with each
other (i.e., share data) in the lecture. From line 99 to 101 in problem1.c, the child process
prints values of the three variables, i.e., global param, local param, and shared param c. When
executing the three lines of code, does the variable global param have the same value as the input
parameter? Why? How about the variables local param, and shared param c? Please explain
your answers. (Hint: You can compile the problem1.c program and run the corresponding
executable to verify your answer.)

3.3.2 Question 2 of Problem 1

After finishing Question 1, the child process should have obtained the value of the input pa-
rameter. For this question, you will implement a multi-threaded program based on problem1.c.
All threads try to access the shared data (the chosen student ID number, an eight-digit
decimal number, in this case). You should try to ensure mutual exclusion when the threads
access the shared data to handle the potential issues. The input parameter should be one of
your group member’s CityU student ID number, aka an eight-digit decimal number.
Before dealing Problem 1, your group should decide to choose one student’s cityu
ID number of your group member, this 8-digit number will be used.
Your program should accept two command-line parameters as shown below:
$ ./ problem1 < input_param > < num_of_operations >
where input param is an eight-digit decimal number, and num of operations is the number
of times executing the addition operation for each thread (more detail in 3.4 Problem 1 Require-
ments e) and f)).
Please implement your code into the function multi threads run(), which can be found in line
188 as shown above. Remember to uncomment the function call in line 123, and pass the input
parameter when calling multi threads run(). Your code in multi threads run() function must
comply with the following requirements.

3.4 Requirements of Problem 1

a)This function can only be invoked in the child process. It should catch your student ID number,
aka an eight-digit decimal number, i.e., the input parameter, which should be obtained from one
of the three variables, i.e., global param, local param, and shared param c (Recall Question 1,
you should know which variable(s) has the value of the input parameter).
b)This function (in the master thread of the child process) must create eight threads (i.e.,
child threads) by calling pthread create(). Each thread must access (read and write) two

6
CS3103 Project Instruction Doc Option A

adjacent digits among the eight digits of the eight-digit decimal number. See 3.5 Explanation
for more detail about the thread-to-digit mapping rule.
c)This function must create eight semaphores, each of which should be associated with
one digit of the eight-digit decimal number. The semaphore is used to ensure that only one
thread can access the corresponding digit at any time. When a thread tries to access one digit,
it must first be able to lock the corresponding semaphore.
d)You should design a strategy to ensure mutual exclusion when the threads access the
digits. Specifically, only when a thread can lock two semaphores at the same time, it can access
the two corresponding digits and further proceed to execute operations. Please use the semaphore
to achieve this. Any other mechanisms are NOT allowed and will be graded with zero points.
e)Once a thread can access the two digits, it can read their values and increase each by 1
respectively. If a digit’s value reaches ten after adding 1, the thread should reassign modulo 10
of the value to it, since the number is decimal. DON’T do carry in operation. Once the thread
finishes the above operation, we say it executes an addition operation.
f )Once a thread is created or it finishes an addition operation, it must try to lock the
semaphores immediately until it finishes all the addition operations (depending on num of operations).
g)When all eight child threads finish their addition operations, the master thread should
write the modified eight-digit decimal number into a text file by calling the saveResult() function,
which is in helper.h. The function has two input parameters, i.e., the name of the text file (must
be p1 result.txt for Problem 1) and a long int type number, such as the modified eight-digit
decimal number for Problem 1.
Warnings!
• Please define the name of a semaphore as ”xxx GROUP NAME”, where GROUP
is your group number, NAME is your full name, and ”xxx” can be any char-
acters for your own usage.
• Please close and delete your semaphores in the parent process by calling sem close()
and sem unlink() functions. Read the code in problem1.c to learn how to do
this.

3.5 Explanation
Here we introduce the detail about the thread-to-digit mapping rule (as stated in 3.4 Problem
1 Requirements b)). For example, the chosen student ID is 56781234. We can assign an
index to each of the eight digits from the most significant digit to the least significant digit (i.e.,
from left to right):
• digit1 = 5
• digit1 = 6

7
CS3103 Project Instruction Doc Option A

• digit1 = 7

• digit1 = 8
• digit1 = 1
• digit1 = 2
• digit1 = 3

• digit1 = 4
Suppose that each thread has an index corresponding to the order in which they were created.
For example, the first thread created can be named thread1 , the second thread created can be
named thread2 , and so on until the eighth thread created is named thread8 .
Then, the thread-to-digit mapping rule is shown in the following figure. The first thread1
should access the digit1 and digit2 , the second thread2 should access the digit2 and digit3 , and
so on. Note that the ninth thread8 should access the digit8 and digit1 .

3.5.1 Hints about Problem 1

1)You can add any other code for your own implementation, such as defining a local variable (in
the main() function) or a global variable, etc.
2)You can encapsulate any other C functions as auxiliary functions to be called in the function
multi threads run().
3)You can modify the input parameter of the multi threads run() function.
4)The master thread should wait for the child threads to finish by calling pthread join().
5)Except your student ID number, your program should be able to handle any other eight-
digit decimal number as the input parameter. To test the correctness of your program, the
grading team will evaluate it with random nine-digit decimal numbers and a random number of
times executing the addition operation when grading.

3.6 Requirements about Problem 1 of your design in project report

In project report, please answer the following two questions:
1)Could your program execute properly? If not, please give the possible reason.
2)How do you handle the thread deadlocks when using the semaphore?
Note: You should claim the student ID number your group chose, which must
belong to one of the group member.

8
CS3103 Project Instruction Doc Option A

4 Problem 2
4.1 Introduction
In Problem 2, you are required to implement a word counter to automatically count the number
of words in text files (with suffix.txt). You should achieve this with a C program using two
processes (named parent process and child process respectively). The parent process reads text
files (with suffix.txt) under the given directory (which can be obtained from the input parameter
of this program). Then the child process counts the number of words in those text files by
calling the wordCount() function in helpers.h (implemented in helpers.c). Two processes
communicate with each other using a shared memory. You should write your code in the provided
problem2.c file.
The following table lists some functions may be used for your program implementation:

opendir() Open a directory

readdir() Read a directory, return a dirent structure
stat(),lstat() Get file/directory status, return a stat structure
fopen()) Open a file and associates a stream with it
fseek() Reset the file position indicator for the stream
fread() Read the file data
fclose() Close a file and the stream

4.2 Requirements of Problem 2

Please carefully read the following requirements, with which your implementation should comply:
a)The parent should first find all the text files (10 in all) under the given directory. Since
the number of the text files and their locations in the directory are unknown, you should design
your code to traverse the directory to find all the text files under it. Please directly implement
this into the traverseDir() function. By invoking traverseDir() with a given directory, the
program should find all the text files and their access paths under the directory.
b)The parent process should read the text files one-by-one and write the content of each
text file into a shared memory with a limited buffer size of 1MB. Only one shared memory
is allowed to be used in your program.
c)Once the parent process has written the content of a text file into the shared memory, the
child process is then able to read the content from the shared memory and count the number of
words by invoking the wordCount() function (DON’T modify this function). After that, the
parent process can write data into the shared memory again.
d)The above process must alternate. Specifically, the parent process must first write data
into the shared memory, followed by the child process reading the data. Subsequently, the parent
process can write data again, and then the child process reads the data. This sequence can repeat
multiple times. You should use semaphore to synchronize the writing and reading operations
of the two processes on the shared memory.
e)Given that the parent process should not modify the shared memory while the child process
is reading from it (and vice versa), you should use the semaphore to ensure mutual exclusion
while the processes access (i.e., read or modify) the shared memory.
f )Finally, the child process should write the total number of words into a text file by calling
the saveResult() function. The first parameter should be the name of the text file (must be
“p2 result.txt” for Problem 2), and the second one should be the total number of words.

9
CS3103 Project Instruction Doc Option A

g)In addition, the child process should correctly find a txt file, where the last number of
words in the file is equal to the last number of the chosen student ID (A different ID
number from problem 1), and the child process needs to print the name of the txt file. For
example, the chosen student ID is 56781234, the txt file “CityU.txt” has 274 words, then
the child process should print “CityU.txt” on screen.
Warnings!

• Please detach your processes (including the parent process and child process)
from the shared memory by calling shmdt() if it will not be used.
• Please delete the shared memory in the parent process by calling shmctl() if
it will not be used. Read the code in problem1.c carefully to learn how to do
this.

4.2.1 Hints about Problem 2

1) When the parent process reads the text files, it doesn’t matter in what order the files are
read.
2) You should handle the case that the total size of a text file exceeds the buffer size and
count the total number of words in such file.
3) In Problem 1, the semaphore is used for the purpose of mutual exclusion. Mutual
exclusion means that at any time only one process can access a “critical section” (the decimal
digits in this case) that you want only one process/thread to access at a time. In this Problem
2, you should also think about how to use the semaphore to achieve synchronization between
the parent and child processes.
4) The 10 txt files provided in the test case folder have different number of words and the
last number of the words, so you must find the only correct file name. You should define the last
digit of your student ID as int type variables.

4.3 Test your program of Problem 2

We provide the test case folder in the compressed file for you to test your program. We will use
other test cases when grading your submission. The test cases are just to help you to evaluate
your solution. Before submitting your program, please run it on the test cases and check whether
it works correctly.
You can compile the files based on the provided Makefile (you may modify it before using it
for this problem) following this command:
$ make
or you can directly use the following command:
$ gcc problem2 . c helpers . c -o problem2 -I . - pthread
After compiling, run the executable to test your program by typing command:
$ ./ problem2 < source_dir >
where source dir is the name of a source directory. If your program works correctly, it should
be able to save the result, i.e., the total number of words in a given directory, into p2 result.txt
file.

10
CS3103 Project Instruction Doc Option A

4.4 Requirements about Problem 2 of your design in project report

In project report, please answer the following four questions:
1)Could your program pass all the provided 3 test cases? If not, please give the possible
reason.
2)How you find all the text files under a directory, i.e., the implementation of traverseDir()
function.
3)How you achieve the synchronization between two processes using the semaphore.
4)How you handle the case that the total size of a text file exceeds the buffer size.
Note: You should claim the student ID number your group chose, which must
belong to one of the group member, it must be different from the ID number Problem
1 chooses.

11
CS3103 Project Instruction Doc Option A

5 Grading
We will grade your work with the following three considerations:
• Design (Project Report) 30%
• Implementation (Code) 30%

• Evaluation (Test Result) 40% .

5.1 Design 30%

Your project report explaining your design details will account for 30% of your project grade.
The project report should encompass the following content:
a)Answer the proposed questions (15%). Please explain how you address the proposed
questions for both problems. Please provide a detailed explanation of the abstract idea behind
your design. You can utilize various methods to present your design, such as textual descriptions,
flow diagrams, pseudo-code, or any other suitable means.
b)Implemented functions (15%). List and explain all the functions you have implemented
for both problems. Ensure to include the input and output arguments for each function, as well
as a clear description of their functionality. It is recommended to provide comprehensive coverage
of all the relevant functions.
You could also discuss any difficulties encountered and the lessons learned in solving them.
In case your code cannot be compiled or does not give the correct result, you may still get part
of the design scores according to the quality of your project report.

5.2 Implementation 30%

The implementation of your two programs will account for 30% of your project grade. Your code
must be written by you own. The code should be nicely formatted with sufficient comments. Each
function should be preceded by a header comment that describes what the function does. The
code should be easy to read, properly indented, employ good naming standards, and structure,
and correctly implement the design. Your code should match your design.
In case your code cannot be compiled or does not give the correct result, you may still get
part of the implementation scores according to the quality and degree of correctness of the codes.

5.3 Evaluation 40%

The evaluation of your two programs will account for 40% of your project grade, with 20% for
each Problem 1 and Problem 2. Your programs will be tested for correctness validation, ensuring
that they work correctly. For each problem, the grading team will use 5 test cases to test your
programs when grading. For both problems, each test case is worth 4%. For the sake of fairness,
the same 5 test cases for each problem will be used for each group when grading.
Note: the grade for this part would be zero if your program could not be built and run
properly.

12
CS3103 Project Instruction Doc Option A

6 Submission
Please submit the following files:
• Source code files (with suffixes “.h” and “.c”), (at least) including problem1.c, problem2.c,
helpers.h, helpers.c, and Makefile (if any).
• The compiled executable files. The executable files should be named as “problem1” and
“problem2” for two problems, respectively.
• Project report in PDF format based on report template for Project A. It should be named
as “XX-report.pdf ”, where XX represents your group number. For example, if you are in
group 12, then your submitted report should be named as “12-report.pdf”. Please list the
names, student numbers, and emails of all group members at the beginning of the project
report and describe each team member’s contribution.
Please organize and compress the above listed files in a zip format file (named as “XX-
project.zip”, where XX is your group number):
/ XX - project
| - - helpers . c
| - - helpers . h
| - - ... # Any o t h e r s o u r c e c o d e f i l e s .
| - - Makefile # I f any .
| - - problem1 # The c o m p i l e d e x e c u t a b l e f o r p r o b l e m 1 .
| - - problem1 . c # The s o u r c e c o d e f i l e f o r p r o b l e m 1 .
| - - problem2 # The c o m p i l e d e x e c u t a b l e f o r p r o b l e m 2 .
| - - problem2 . c # The s o u r c e c o d e f i l e f o r p r o b l e m 2 .
| - - XX - report . pdf # The p r o j e c t r e p o r t f i l e .
Submit to CANVAS Self-sign-up is enabled for groups. Instead of all students having to
submit a solution to the project, Canvas allows one person from each group to submit on behalf
of their team. If you work with partner(s), both you and your partner(s) will receive the same
grade for the project.
When you’re ready to hand in your work, go to the course site in Canvas, choose the ”As-
signments” section ¿ ”Project” item ¿ ”Start Assignment” button, and upload your compressed
zip file named as “XX-project.zip”, where XX is your group number.

13
CS3103 Project Instruction Doc Option A

7 Academic Honesty
All work must be developed by each group independently. Please write your own code. All
submitted source code will be scanned by anti-plagiarism software. We will both test
your code and carefully check your source code. If your submitted code does not work,
please indicate it in the report clearly.

14