tar.c documentation

1 files changed, 55 insertions, 57 deletions

diff --git a/kernel/fs/tar.c b/kernel/fs/tar.c
index 569a876..4e66944 100644
--- a/kernel/fs/tar.c
+++ b/kernel/fs/tar.c
@@ -2,6 +2,7 @@
 #include <lib.h>
 #include <comus/tar.h>
 
+
 // the placements of these values mimics their placement in standard UStar
 struct tar_header {
     char name[100]; // 0-99
@@ -41,12 +42,17 @@ struct tar_file {
     size_t offset;
     size_t sect; 
 };
-// read_tar_header reads what is in tar
+/// @brief reads from the disk into tar_header
+/// @param disk the disk used with disk_read
+/// @param sect the sector to read (used for disk_read offset)
+/// @param hdr the tar_header to read into. read_tar_header is essentially used to output this.
+/// @return NOERROR_TAR or ERROR_TAR
 int read_tar_header(struct disk *disk, uint32_t sect, struct tar_header *hdr) {
-    
+    // makes sure it reads enough bytes.
     if(disk_read(disk, sect * TAR_SIZE, TAR_SIZE, hdr) < TAR_SIZE) {
         return ERROR_TAR;
     }
+    // makes sure magic and version are correct for USTar.
     if(memcmp(hdr->magic, TMAGIC, TMAGLEN) != 0 || memcmp(hdr->version, TVERSION, TVERSLEN) != 0) {
         return ERROR_TAR;
     }
@@ -54,11 +60,11 @@ int read_tar_header(struct disk *disk, uint32_t sect, struct tar_header *hdr) {
     
 }
 
-/// @brief 
+/// @brief reads from the file, and puts it into buffer
 /// @param f the file to be read
 /// @param buffer the buffer that the content of the file is read into
-/// @param len 
-/// @return 
+/// @param len length of the buffer, which caps what can be read if the file has more data.
+/// @return size of what was read.
 int tar_read(struct file *f, void *buffer, size_t len) {
     struct tar_file *tf = (struct tar_file*) f;
     long size = MIN((tf->len - tf->offset), len);
@@ -69,10 +75,14 @@ int tar_read(struct file *f, void *buffer, size_t len) {
     tf->offset += size;
     return size;
 }
-//static int read_tar()
-// we are assuming that things are formatted correctly.
+/// @brief used to locate files
+/// @param fs the file system being used
+/// @param filepath the path to the file
+/// @param sect the sector to begin at, defaults to 0 if NULL.
+/// @param sect_return the sector to be outputted
+/// @param outHeader tar_header output for file found.
+/// @return NOERROR_TAR or ERROR_TAR
 int find_file(struct file_system *fs, const char *filepath, size_t *sect, size_t *sect_return, struct tar_header *outHeader) {
-    //char *tempFilePath = filepath;
     struct tar_header hdr;
     size_t curr_sect;
     if(sect == NULL) {
@@ -81,12 +91,12 @@ int find_file(struct file_system *fs, const char *filepath, size_t *sect, size_t
         curr_sect = *sect;
     }
     while (1 == 1) {
+        // if read_tar_header errors
         if(read_tar_header(fs->fs_disk, curr_sect, &hdr) != 0) {
             return ERROR_TAR;
         }
         if(memcmp(hdr.name, filepath, strlen(filepath) + 1) != 0) {
             // didn't find it.
-            
             curr_sect += ((strtoull(hdr.fileSize, NULL, 8) + TAR_SIZE - 1)/TAR_SIZE) + 1;
             continue;
         } else {
@@ -101,6 +111,8 @@ int find_file(struct file_system *fs, const char *filepath, size_t *sect, size_t
     }
     return ERROR_TAR;
 }
+
+// similar to find_file, but with a partition
 int find_file_redux(struct file_system *fs, const char *filepath, size_t *sect, size_t *sect_return, struct tar_header *outHeader) {
     struct tar_header hdr;
     size_t curr_sect;
@@ -132,12 +144,17 @@ int find_file_redux(struct file_system *fs, const char *filepath, size_t *sect,
     return ERROR_TAR; // it should never actually reach here.
 
 }
-
-
+/// @brief closes the file
+/// @param f the file to close, and free memory from.
 void tar_close(struct file *f) {
     kfree(f); 
 }
 
+/// @brief 
+/// @param f the file to perform seek
+/// @param offsetAdd what to add/adjust to the offset
+/// @param theSeek what kind of seek we are doing
+/// @return the new offset, or -1 on error (we can't use 1 since that is a possible offset change).
 int tar_seek(struct file *f, long int offsetAdd, int theSeek) {
     struct tar_file *tf = (struct tar_file*) f;
     if(theSeek == SEEK_SET) {
@@ -150,11 +167,16 @@ int tar_seek(struct file *f, long int offsetAdd, int theSeek) {
         tf->offset = tf->len + offsetAdd;
         return tf->offset;
     } else {
-        return -1;
+        return -1; // if seek has a bad value for some reason.
     }
 
 }
 
+/// @brief 
+/// @param f the file to write to (in theory)
+/// @param buffer the buffer to write from (in theory)
+/// @param len the length of the buffer to be written into (in theory)
+/// @return ERROR_TAR or NOERROR_TAR (in this case always ERROR_TAR).
 int tar_write(struct file *f, const void *buffer, size_t len) {
     // tar doesn't do write lol. This is just here so there is something to send to write
     (void)f;
@@ -163,40 +185,11 @@ int tar_write(struct file *f, const void *buffer, size_t len) {
     return ERROR_TAR;
 }
 
-/*int tar_ents(struct file *f, struct dirent *d, size_t dIndex) {
-    struct tar_header hdr;
-    struct tar_header dir;
-    struct tar_file *tf = (struct tar_file*) f;
-    size_t sect = 0;
-    size_t sect_off = 0;
-    size_t curr_index = 0;
-    if(read_tar_header(tf->fs->fs_disk, sect, &hdr) != 0) {
-        return ERROR_TAR;
-    }
-    while(1 == 1) {
-        if(find_file_redux(tf->fs, dir.name, &sect_off, &sect, &dir) != 0) {
-            return ERROR_TAR;
-        }
-        if(curr_index < dIndex) {
-            curr_index += 1;
-        } else if(curr_index > dIndex) {
-            // something went seriously wrong
-            return ERROR_TAR;
-        } else {
-            d->d_namelen = strlen(hdr.name);
-            dir.type_flag = DIRTYPE;
-            d->d_offset = dIndex;
-            memcpy(d->d_name, hdr.name, d->d_namelen + 1);
-            return NOERROR_TAR;
-        }
-
-
-    }
-
-    
-}*/
-
-
+/// @brief gets the directory entry for the given file
+/// @param f the file 
+/// @param ent the directory entry is put into here
+/// @param entry where idx needs to reach
+/// @return NOERROR_TAR or ERROR_TAR
 int tar_ents(struct file *f, struct dirent *ent, size_t entry)
 {
 	struct tar_file *tf;
@@ -209,7 +202,7 @@ int tar_ents(struct file *f, struct dirent *ent, size_t entry)
 	sect = 0;
 
 	if (tf->file.f_type != F_DIR)
-		return -1;
+		return ERROR_TAR;
 
 	if (read_tar_header(tf->fs->fs_disk, sect, &dir)) {
         return ERROR_TAR;
@@ -233,7 +226,12 @@ int tar_ents(struct file *f, struct dirent *ent, size_t entry)
 	return ERROR_TAR;
 }
 
-// opens up the tar file at fullpath, and puts it in out.
+/// @brief opens up the file at the full file path, and prepares it for further action
+/// @param fs the file system being used
+/// @param fullpath the full file path to the file that needs to be opened
+/// @param flags in this case, just used to check whether the file is set to read only, to make sure it is correct
+/// @param out the file, ready to be acted upon, with the other functions loaded onto it.
+/// @return NOERROR_TAR or ERROR_TAR
 int tar_open(struct file_system *fs, const char *fullpath, int flags, struct file **out) {
     struct tar_header hdr;
     struct tar_file *newFile;
@@ -257,13 +255,13 @@ int tar_open(struct file_system *fs, const char *fullpath, int flags, struct fil
 
     *out = (struct file *)newFile;
     return NOERROR_TAR;
-    
-
-
-    
 }
 
-// gets stats at the file at fullpath, putting them in out.
+/// @brief gets the stats for the file found at fullpath, putting them in out
+/// @param fs the file system being used
+/// @param fullpath the full filepath of the file
+/// @param out the stats for the file found
+/// @return NOERROR_TAR OR ERROR_TAR
 int tar_stat(struct file_system *fs, const char *fullpath, struct stat *out) {
     struct tar_header hdr;
     size_t sect_result;
@@ -280,7 +278,9 @@ int tar_stat(struct file_system *fs, const char *fullpath, struct stat *out) {
     return NOERROR_TAR;
 }
 
-// use tar for the filesystem.
+/// @brief use tar for the filesystem.
+/// @param fs the file system being used, and loading tar into it.
+/// @return NOERROR_TAR or ERROR_TAR
 int tar_mount(struct file_system *fs) {
     struct tar_header hdr;
     // reads into hdr
@@ -292,6 +292,4 @@ int tar_mount(struct file_system *fs) {
         return NOERROR_TAR;
     }
     return ERROR_TAR;
-}
-
-// no need to unmount, since mount just overrides whatever it was using previously.
\ No newline at end of file
+}
\ No newline at end of file