FAT File Management System

CS 345 - Project Six

Purpose
File management is a central component to most applications. With the exception of perhaps real-time
applications, the input and output of an application is via a file. Files have a life outside of any individual
application and provide a medium for later access by the user or by other programs. Typically, an operating
system implements a file management system with a set of utility programs that run as privileged
applications. In this project, you will add a MS-DOS® FAT-12 file manager to your operating system that
will enable you to traverse file directories, read/write/seek file data, and execute LC-3 program files.

Project Six is designed to help the student:

 understand the organization of a file management system.

 understand file allocation tables (FAT).
 understand FAT directory structures and cluster chains.
 understand a boot sector.
 understand file system buffering, basic file I/O, file descriptors, and file pointers.
 understand file access modes and learn how to modify file allocation tables (FAT), directory
structures and cluster chains.

Project Requirements
The following are important guidelines for programming the FAT FMS assignment:

1) RAM Disk Image: A FAT-12 disk image is loaded into a RAM disk (memory array) using the shell
mount command. The RAM disk is divided into 2849 sectors, each being 512 bytes in length. The
file allocation tables (FAT1 and FAT2) are held in separate memory arrays. All memory accesses to
the RAM disk array must be made using the following read/write sector functions:

a. int fmsReadSector(void* buffer, int sectorNumber)

 Read into buffer buffer RAM disk sector number sectorNumber. Sectors are 512 bytes.
 Return 0 for success; otherwise, return an error number.

b. int fmsWriteSector(void* buffer, int sectorNumber)

 Write 512 bytes from memory pointed to by buffer to RAM disk sector sectorNumber.
 Return 0 for success; otherwise, return an error number.

2) RAM Disk Files and Directories: A FAT-12 file system specifies how files are named, accessed,
and stored in your RAM disk image. Your program will maintain a “current directory” variable (cDir
in the task control block) which points to the start cluster of the current working directory. You must
be able to navigate hierarchal directories using the cd and dir shell commands. Short file and
directory names can be assumed to be at most 8 characters long, with an optional 1-3 character
extension (filename is separated from the extensions by a dot [.]).

BYU, CS 345 Project Six – FAT Page 1/10

 3) FAT Directory and Cluster Chains: Project Six is divided into two parts. The first part deals with
disk directories and file navigation. You will need to implement the following API‟s: (Do NOT
change these API‟s.)

a. int fmsChangeDir(char* dirName)

 The fmsChangeDir function changes the current directory to the subdirectory specified by the
string argument dirName.
 You will only need to handle moving up or down a directory.
 Verify that dirName is a valid directory name in the current directory.
 Return a 0 for success; otherwise return error number.

b. int fmsGetNextDirEntry(int* dirNum, char* mask, DirEntry* dirEntry, int cDir)

 The fmsGetNextDirEntry function reads the next directory entry from the cDir directory as
specified by dirNum, into the 32 byte dirEntry struct. (See Directory Structure below.)
 The dirNum parameter is passed by reference and set to 0 for the first entry. Each call to
fmsGetNextDirEntry updates this value for subsequent calls. dirNum acts as a directory iterator
and holds entry index state in a local task variable and not in the FMS subsystem.
 The parameter mask is a selection string. If null, return next directory entry. Otherwise, use
the mask string to select the next directory entry. An „*‟ is a wild card for any length string.
A „?‟ is a wild card for any single character. Any other character must match exactly. (See
mask description below.)
 Return 0 for success; otherwise, return the error number.

4) C File Management Functions: The second part of Project Six deals with basic file I/O operations.
You will need to implement the following C functions in your File Management System: (Again, do
NOT change the API‟s.):

a. int fmsCloseFile(int fileDescriptor)

 The fmsCloseFile function closes the open file specified by fileDescriptor.
 The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.
 Return a 0 for success; otherwise return error number.

b. int fmsDefineFile(char* filename, int attribute)

 If attribute equals 0x10, then a new sub-directory file, named directoryName, is created in the
current directory. One cluster is allocated to the file with new directory entries “.” and “..”.
 Else, a new file, named filename, is created in the current directory with file attribute equal to
attribute. No clusters are allocated to that file.
 Return 0 for success; otherwise, return the error number.

c. int fmsDeleteFile(char* fileName)

 This function deletes the file/directory file named fileName from the current directory.
 The file name in the directory entry should be marked with a 0xe5 as the first character and the
chained clusters in FAT 1 reallocated (set to 0).
 A directory file must not have any valid file or directory entries.
 Return 0 for success; otherwise, return the error number.

d. int fmsOpenFile(char* fileName, int rwMode)

 This function opens the file named fileName for access as specified by rwMode.
 The open mode rwMode is defined as follows:
0 - Read access only.
BYU, CS 345 Project Six – FAT File Management System Page 2/10
 The file pointer is initialized to the beginning of the file.
Writing to this file is not allowed.
1 - Write access only.
The file pointer is initialized to the beginning of the file.
Reading from this file is not allowed.
2 - Append access.
The file pointer is moved to the end of the file.
Reading from this file is not allowed.
3 - Read/Write access.
The file pointer is initialized to the beginning of the file.
Both read and writing to the file is allowed.
 A maximum of 32 files may be open at any one time.
 Return an error if the file does not exist, already open, or too many files are open.
 If successful, return a file descriptor that is used in calling subsequent file handling functions;
otherwise, return the error number.

e. int fmsReadFile(int fileDescriptor, char* buffer, int nBytes)

 This function reads nBytes bytes from the open file specified by fileDescriptor into memory
pointed to by buffer.
 The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.
 After each read, the file pointer is advanced.
 Return the number of bytes successfully read (watch for the end of file), or the error number
for failure (error numbers are negative). (If you are already at the end of the file, return 0
bytes successfully read.)

f. int fmsSeekFile(int fileDescriptor, int index)

 This function changes the current file pointer of the open file specified by fileDescriptor to the
new file position specified by index.
 The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.
 The file position may not be positioned beyond the end of the file.
 Return the new position in the file if successful; otherwise, return the error number.

g. int fmsWriteFile(int fileDescriptor, char* buffer, int nBytes)

 This function writes nBytes bytes to the open file specified by fileDescriptor from memory
pointed to by buffer.
 The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.
 Writing is always "overwriting" not "inserting" in the file and always writes forward from the
current file pointer position.
 Return the number of bytes successfully written; otherwise, return the error number.

5) Validation: Your completed file management system must be able to pass a disk validation program
(chkdsk) and a final stress test (final). The DOS function chkdsk analyzes a FAT-12 disk and reports
any problems. (See description below.) The final program has six steps that will test various
implementations of your file manager and must be executed in order. These tests include the creation
and deletion of a large number of files and directories, opening and closing a maximum number of
files, random access within files using the read, seek, and write primitives, and testing the various
modes of opening files including read-only, write, read/write, and append.

BYU, CS 345 Project Six – FAT File Management System Page 3/10
About DOS File Names
A DOS 8.3 file name is composed of two parts: a name, which can be up to eight characters long, and an
optional extension, which can be up to three characters long. The name and extension are separated by a
period. A file name may not begin with a period. Extensions are typically not added to directory names
because it makes discerning them from filenames difficult. The extension is DOS' way of determining
which of the four basic functions a file performs: executable (.exe or .com), support (.ini, .cgf, or .dll),
data (.doc, .txt, .xls, .dbf, and .dxf), and batch (.bat).

In general, DOS filenames use only letters and numerals. Upper and lower case letters are considered
identical. In addition, the following symbols can be used in file names:

`~!@#$%^&()_-{}'

Valid DOS file names Invalid DOS file names

RESULTS.TXT MYRESULTS.TXT (MYRESULTS is 9 characters)
SEARCH.#1 SEARCH.RESULTS (RESULTS is 7 characters)
READ.ME! ONE.TWO.3 (Only use one period)
MY.DOC /.\ (Invalid punctuation symbols)
A.A
A
{MYFILE}

File/Directory Masks
A file name mask is used to selectively qualify directory entries. A wildcard is a special character that
can fill in for missing letter(s) in file and directory names when used to add specificity to OS commands.
Although there are various ways to define the syntax and semantics of a mask string, we will use the
following rules:

 A mask has two parts, one for the file name and the other for the extension. If an extension mask is
included, it is separated from the file mask by a period.
 A null file mask string qualifies all entries (regardless of extension.)
 An „*‟ qualifies all characters to the right and cannot be followed by any characters (other than a
period and an extension mask.) There can be only one “*” per file name and/or extension mask.
Thus a single “*” would select all files without an extension. A “*.*” mask would be the same as a
null string and select all files with or without an extension.
 A „?‟ is a wild card for any single character and requires the presence of a character in the file name
to qualify. It may be used multiple times in the file name and/or file extension mask.

Examples: *.* All files

B* All files beginning with „B‟ and no extension
???*.C All files of length at least 3 with „C‟ extension
*.TXT All files with “TXT” extension

BYU, CS 345 Project Six – FAT File Management System Page 4/10
Directory structure
A DOS directory entry is a 32-byte struct that contains the file name, extension, time and date of last
update, size of the file (in bytes), and the cluster number of the cluster of the file. File names follow the
8.3 naming standard. Time, date, startCluster, and fileSize are in little-endian format. The struct must be
byte aligned.

#pragma pack(push,1) /* byte align in memory (no padding) */

typedef struct
{ unsigned char Name[8]; /* file name */
unsigned char Extension[3]; /* extension */
unsigned char Attributes; /* holds the attributes code */
unsigned char Reserved[10]; /* reserved */
unsigned short Time; /* time of last write */
unsigned short Date; /* date of last write */
unsigned short startCluster; /* pointer to the first cluster of the file. */
unsigned long fileSize; /* file size in bytes */
} DirEntry;
#pragma pack(pop) /* end of strict alignment */

File/Directory Deletion
DOS does not immediately erase a file or directory when it is deleted. In fact, it does nothing to the
clusters that contain the information (this is why it is sometimes possible to un-delete something).
However, DOS does zero out the file/directory's cluster chain from the FAT table and places a special
character (0xe5) in the first byte of the directory entry signaling that this entry has been deleted. You will
need to do the same when a file or directory is deleted. Start with the cluster indicated in the directory
entry, traverse the cluster chain, and then set each FAT entry to zero including the EOC entry.

The special code 0xe5 in the first byte of a directory entry, indicates that this directory entry is free, and
may be overwritten with a new entry in the future. Place this value in the first byte of the directory entry
to effectively delete it (it will be the first character of the file/directory name field). When reading
directory entries, ignore all entries that begin with 0xe5.

When making any change to the FAT 1 table, copy the FAT 1 table to the FAT 2 table, EXCEPT when
deleting a file.

Validity (chkdsk) Command

The DOS function chkdsk analyzes a FAT-12 disk and reports any problems. You should use chkdsk to
validate your file manager implementation. Here are some checks and error messages that the chkdsk
program will look for:

 lost chains – Allocated sectors not belonging to any directory or file.

 cross-linked chains – two entries in the FAT table are "pointing" to the same cluster.
BYU, CS 345 Project Six – FAT File Management System Page 5/10
  invalid directory entry
o invalid name – directory entries padded with zeros instead of spaces or lowercase.
o invalid extended attribute handle – "reserved" field of directory entry not zeroed out.
o invalid attribute – combination of attribute bits not recognizable.
o invalid date – date in future (or before 2000).
o invalid file size – file size impossible or file size 0 with non-zero start cluster.
o invalid file start cluster – start cluster out of bounds.
o zombie long name directory entry – long short names differ.
 invalid directory
o dot/dotdot invalid – dot or dotdot entries invalid or missing.
o invalid format – directory entries after “last” entry.
 improperly formatted disk
o invalid boot sector – corrupted data or constants.
o invalid fat tables – fat tables have not been or cannot be reconciled.

FMS Errors
In order to use the LC-3 file programs, we must standardize on error numbers coming from the File
Management System. As such, please use the following error definitions in your implementation:

# Error Description # Error Description

-50 "Invalid File Name" -67 "End-Of-Directory"
-51 "Invalid File Type" -68 "Directory Not Found"
-52 "Invalid File Descriptor" -69 "Can Not Delete"
-53 "Invalid Sector Number" -70 "Too Many Files Open"
-54 "Invalid FAT Chain" -71 "Not Enough Contiguous Space"
-55 "Invalid Directory" -72 "Disk Not Mounted"
-60 "File Already Defined" -80 "File Seek Error"
-61 "File Not Defined" -81 "File Locked""
-62 "File Already Open" -82 "File Delete Protected"
-63 "File Not Open" -83 "File Write Protected"
-64 "File Directory Full" -84 "Read Only File"
-65 "File Space Full" -85 "Illegal Access"
-66 "End-Of-File" -1 "Undefined Error

Implementation Strategy
1. Read and comprehend the MS-DOS FAT File System help document as well as Stallings, Chapter 12.
2. Comprehend these lab specs. Discuss questions with classmates, the TA‟s and/or the professor.
Make sure you understand what the requirements are!
3. Design your file management system. Break the problem down into manageable parts.
4. A suggested implementation order might be:
a. Begin with the shell commands cd and dir. Implement the fmsChangeDir and
fmsGetNextDirEntry functions.
b. Implement fmsOpenFile, fmsReadFile, and fmsCloseFile. Verify your implement using the
type command.
c. Implement fmsWriteFile. Verify your implement using the copy command.
d. Implement fmsDefineFile, fmsDeleteFile.
BYU, CS 345 Project Six – FAT File Management System Page 6/10
 e. Implement fmsSeekFile and test with LC-3 decoder programs.
f. Valid your completed FMS with the chkdsk and final programs.

Grading and Pass-off

Your FMS I assignment is to be demonstrated in person to a TA and is outlined as follows:

1) Do the following:
 Add a FAT-12 file management system to your operating system. Use an open file table, I/O
buffering, file descriptors to accommodate up to 32 open files at a time.
 Change your shell prompt to display the current working directory path name.
 Use the following shell commands to demonstrate your file manager: (Please ask your
instructor/TA for further clarification of arguments.)
o cd <file name/..> Change directory
o chkdsk Check disk
o copy <file1>,<file2> Copy file
o define <file> Define file
o delete <file name> Delete file
o dir {<mask>} Display files in current directory
o fat <#>,<s>,<e> Display FAT structure
o final Test file manager
o map {<mask>} Map files from current directory
o mkdir <dir name> Create directory
o mount <file name> Initialize FAT-12 RAM disk from file
o run <file name> Execute LC-3 program
o sp Display bytes used/free/bad/size
o type <file name> Display file
o unmount <file name> Write FAT-12 RAM disk to file

2) Demonstrate that your file management system is functioning correctly. Be able to traverse the
directory structure on a disk and list selected files. Be able to display file contents. Be able to copy
files, create and delete files and directories, seek, read/write, and append files, and successfully
execute LC-3 file programs from your RAM disk.

3) There are 20 points possible for Project 6. The grading criteria will be as follows:

 1 pt – Correctly detect invalid DOS file names where applicable.

 2 pts – Successfully traverse (cd) file directories and display at the shell prompt, the full path
name to the current working directory.
 2 pts – Correctly display entries in the current directory (dir) using a selection mask while
ignoring long file names (unless implementing bonus).
 3 pts – Successfully define (define, mkdir) and delete (delete) files/directories.
 3 pts – Successfully copy files using the copy command.
 3 pts – Successfully execute (run) the LC-3 decoder programs (decode1.hex,…, decode9.hex) from
RAM disk 4.
 6 pts – Successfully validate your implementation with the chkdsk command and pass all the file
management stress tests (final, p6). (Tests must be passed in consecutive order.)

BYU, CS 345 Project Six – FAT File Management System Page 7/10
 In addition to the possible 20 points, the following bonus/penalties apply:

 +2 points bonus for early pass-off (at least one day before due date.)
 +2 points bonus for implementing support (cd, dir) for long file names.
 +2 points bonus for implementing an undelete command.
 +2 points bonus for implementing a rename command.
 +2 points bonus for deleting multiple files using a file mask.
 +5 points bonus for implementing your file management functions as background kernel tasks that
suspend the calling process until I/O operations complete.
 -2 points penalty for each school day late.
 -20 points penalty for any invalid reference to the RAM disk.

Sample Output
***NOTE: This sample may or may not reflect your results and should not be used as validation of your
FMS implementation.

CS345 F2008
0>>mount
Mount Disk "c:/lcc/projects/disk4"
System: IBM 3.3
Bytes/Sector: 512
Sectors/Cluster: 1
Reserved sectors: 1
FAT tables: 2
Max root dir entries: 224
FAT-12 sectors: 2880
FAT sectors: 9
Sectors/track: 18
Heads/volume: 2
FAT-32 sectors: 0
c:/lcc/projects/disk4:\>>final all
Running Test 1...
Define 128 directories...
Define 64 files...
Running Test 2...
Open 64 files...
Now is the time for all good men to come to the aid of their country.
Running Test 3...
Now is the time for all good men to come to the aid of their country.
Running Test 4...
Now is the time for all good men to come to the aid of their country.
Running Test 5...
fmsMakeDirectory("TESTDIR")
fmsChangeDir("TESTDIR")
Define 64 files...
fmsChangeDir("..")
fmsDeleteFile("TESTDIR") Can Not Delete... Good!
fmsChangeDir("TESTDIR")
Delete 64 files...
fmsChangeDir("..")
fmsDeleteFile("TESTDIR")
Running Test 6...
Delete 64 files...

BYU, CS 345 Project Six – FAT File Management System Page 8/10
 Delete 128 directories...
Slot Name Ext Atr Size Strt Curr cDir cPID Mode Flag Indx
Name:ext time date cluster size
BIGDIR ----D- 11:31:40 03/31/2004 3 0
BYU ----D- 11:34:54 03/31/2004 171 0
JOKES ----D- 11:37:06 03/31/2004 800 0
LONGFI~1 ----D- 11:37:14 03/31/2004 875 0
PERSONAL ----D- 11:37:18 03/31/2004 937 0
TEMP ----D- 11:37:36 03/31/2004 1355 0
H2O.C -----A 19:00:02 02/12/2004 1380 3425
MAKE.TXT -----A 16:26:58 02/27/2004 1387 18584
CONGRATULATIONS! YOU PASS!
c:/lcc/projects/disk4:\>>cd byu
c:/lcc/projects/disk4:\byu>>cd cs345
c:/lcc/projects/disk4:\byu\cs345>>cd projects
c:/lcc/projects/disk4:\byu\cs345\projects>>cd p6
c:/lcc/projects/disk4:\byu\cs345\projects\p6>>run decode1.hex
c:/lcc/projects/disk4:\byu\cs345\projects\p6>>
Load "decode1.hex" from FAT
Memory loaded! PC=0x3000
Process #1 Halted at 0x313e
Exit Task 1
c:/lcc/projects/disk4:\byu\cs345\projects\p6>>dir
Name:ext time date cluster size
. ----D- 11:35:10 03/31/2004 224 0
.. ----D- 11:35:10 03/31/2004 222 0
DECODE1.HEX -----A 11:00:58 03/31/2004 225 3630
DECODE2.HEX -----A 11:02:10 03/31/2004 233 3630
DECODE3.HEX -----A 11:02:56 03/31/2004 241 3630
DECODE4.HEX -----A 11:03:44 03/31/2004 249 3630
DECODE5.HEX -----A 11:04:14 03/31/2004 257 3630
DECODE6.HEX -----A 11:04:36 03/31/2004 265 3630
DECODE7.HEX -----A 11:05:02 03/31/2004 273 3630
DECODE8.HEX -----A 11:05:26 03/31/2004 281 3630
DECODE9.HEX -----A 11:05:48 03/31/2004 289 3630
DICT.DAT -----A 13:45:30 03/22/2004 297 4600
SECRET1.DAT -----A 13:45:30 03/22/2004 306 156
SECRET2.DAT -----A 13:45:30 03/22/2004 307 966
SECRET3.DAT -----A 13:45:30 03/22/2004 309 300
SECRET4.DAT -----A 13:45:30 03/22/2004 310 1146
SECRET5.DAT -----A 13:45:30 03/22/2004 314 660
SECRET6.DAT -----A 13:45:30 03/22/2004 316 1494
SECRET7.DAT -----A 13:45:30 03/22/2004 319 492
SECRET8.DAT -----A 13:45:30 03/22/2004 320 438
SECRET9.DAT -----A 13:45:30 03/22/2004 321 282
MAP.HEX -----A 13:11:24 03/20/2004 1563 1782
CALCUL~1.HEX -----A 14:38:18 01/27/2004 1567 6174
CRAWLER.HEX -----A 17:18:00 02/02/2004 1580 1980
MEMTEST.HEX -----A 22:09:32 02/09/2004 1584 2640
MESSAGE1.TXT -----A 15:14:44 10/01/2008 2 61
c:/lcc/projects/disk4:\byu\cs345\projects\p6>>type message1.txt
Men do not fail,
but often rather,
they simply quit trying...
c:/lcc/projects/disk4:\byu\cs345\projects\p6>>final all
Running Test 1...
Define 128 directories...
Define 64 files...
Running Test 2...
Open 64 files...
Now is the time for all good men to come to the aid of their country.
BYU, CS 345 Project Six – FAT File Management System Page 9/10
Running Test 3...
Now is the time for all good men to come to the aid of their country.
Running Test 4...
Now is the time for all good men to come to the aid of their country.
Running Test 5...
fmsMakeDirectory("TESTDIR")
fmsChangeDir("TESTDIR")
Define 64 files...
fmsChangeDir("..")
fmsDeleteFile("TESTDIR") Can Not Delete... Good!
fmsChangeDir("TESTDIR")
Delete 64 files...
fmsChangeDir("..")
fmsDeleteFile("TESTDIR")
Running Test 6...
Delete 64 files...
Delete 128 directories...
Slot Name Ext Atr Size Strt Curr cDir cPID Mode Flag Indx
Name:ext time date cluster size
. ----D- 11:35:10 03/31/2004 224 0
.. ----D- 11:35:10 03/31/2004 222 0
DECODE1.HEX -----A 11:00:58 03/31/2004 225 3630
DECODE2.HEX -----A 11:02:10 03/31/2004 233 3630
DECODE3.HEX -----A 11:02:56 03/31/2004 241 3630
DECODE4.HEX -----A 11:03:44 03/31/2004 249 3630
DECODE5.HEX -----A 11:04:14 03/31/2004 257 3630
DECODE6.HEX -----A 11:04:36 03/31/2004 265 3630
DECODE7.HEX -----A 11:05:02 03/31/2004 273 3630
DECODE8.HEX -----A 11:05:26 03/31/2004 281 3630
DECODE9.HEX -----A 11:05:48 03/31/2004 289 3630
DICT.DAT -----A 13:45:30 03/22/2004 297 4600
SECRET1.DAT -----A 13:45:30 03/22/2004 306 156
SECRET2.DAT -----A 13:45:30 03/22/2004 307 966
SECRET3.DAT -----A 13:45:30 03/22/2004 309 300
SECRET4.DAT -----A 13:45:30 03/22/2004 310 1146
SECRET5.DAT -----A 13:45:30 03/22/2004 314 660
SECRET6.DAT -----A 13:45:30 03/22/2004 316 1494
SECRET7.DAT -----A 13:45:30 03/22/2004 319 492
SECRET8.DAT -----A 13:45:30 03/22/2004 320 438
SECRET9.DAT -----A 13:45:30 03/22/2004 321 282
MAP.HEX -----A 13:11:24 03/20/2004 1563 1782
CALCUL~1.HEX -----A 14:38:18 01/27/2004 1567 6174
CRAWLER.HEX -----A 17:18:00 02/02/2004 1580 1980
MEMTEST.HEX -----A 22:09:32 02/09/2004 1584 2640
MESSAGE1.TXT -----A 15:14:44 10/01/2008 2 61
CONGRATULATIONS! YOU PASS!
c:/lcc/projects/disk4:\byu\cs345\projects\p6>>

BYU, CS 345 Project Six – FAT File Management System Page 10/10