diff --git a/src/pack.c b/src/pack.c index 6415673..ed12afc 100644 --- a/src/pack.c +++ b/src/pack.c @@ -9,7 +9,11 @@ #include "log.h" #include "md5.h" -/* == Store data in a funky format. ======================= +/* + * @file pack.c + * + * @brief Stores data in funky format. + * * Format: * -- Index. * -- Magic number (16 bytes). @@ -26,23 +30,27 @@ * -- Write magic number and number of files. * -- Write the index. * -- Pack the files. - * ======================================================== */ -#undef DEBUG /* this will be spammy. */ +#undef DEBUG /* This will be spammy. */ #define DEBUG(str, args...) do{;} while(0) -/* The read/write block size. */ -#define BLOCKSIZE 128*1024 +#define BLOCKSIZE 128*1024 /**< The read/write block size */ /* Max filename length. */ -#define MAX_FILENAME 100 +#define MAX_FILENAME 100 /**< Maximum file name length. */ -#define PERMS S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH +#define PERMS S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH /**< Default permissions. */ -const uint64_t magic = 0x25524573; /* sER% */ +const uint64_t magic = 0x25524573; /**< File magic number: sER% */ -/* Grab the filesize. */ +/** + * @fn static off_t getfilesize(const char* filename) + * + * @brief Get the file size. + * @param filename File to get the size of. + * @return The size of the file. + */ static off_t getfilesize(const char* filename) { #ifdef _POSIX_SOURCE struct stat file; @@ -66,7 +74,13 @@ static off_t getfilesize(const char* filename) { #endif } -/* Return true if filename is a Packfile. */ +/** + * @fn int pack_check(const char* filename) + * + * @brief Check to see if a file is a packfile + * @param filename Name of the file to check. + * @return 1 if it is a packfile, 0 if it isn't and -1 on error. + */ int pack_check(const char* filename) { int ret; char* buf; @@ -109,7 +123,15 @@ int pack_check(const char* filename) { return ret; } -/* Pack nfiles, infiles into outfile. */ +/** + * @fn int pack_files(const char* outfile, const char** infiles, const uint32_t nfiles) + * + * @brief Packages files into a packfile. + * @param outfile Name of the file to output to. + * @param infiles Array of filenames to package. + * @param nfiles Number of filenames in infiles. + * @return 0 on success. + */ #ifdef _POSIX_SOURCE #define WRITE(b,n) if(write(outfd, b, n)==-1) { \ ERR("Error writing to file: %s", strerror(errno)); \ @@ -229,7 +251,15 @@ int pack_files(const char* outfile, const char** infiles, const uint32_t nfiles) } #undef WRITE -/* Opens the filename in packfile for reading. */ +/** + * @fn int pack_open(Packfile* file, const char* packfile, const char* filename) + * + * @brief Open a file in the packfile for reading. + * @param file Packfile to store data into. + * @param packfile Path to real packfile. + * @param filename Name of the file within th. packfile. + * @return 0 on success. + */ #ifdef _POSIX_SOURCE #define READ(b,n) if(read(file->fd, (b), (n))!=(n)) { \ ERR("Too few bytes read. Expected more."); \ @@ -308,7 +338,17 @@ int pack_open(Packfile* file, const char* packfile, const char* filename) { } #undef READ -/* Read count bytes from file and put them into buf. */ +/** + * @fn ssize_t pack_read(Packfile* file, void* buf, size_t count) + * + * @brief Reads data from a packfile. + * + * Behaves like POSIX read. + * @param file Opened packfile to read data from. + * @param buf Allocated buffer to read into. + * @param count Bytes to read. + * @return Bytes to read or -1 on error. + */ ssize_t pack_read(Packfile* file, void* buf, size_t count) { if(file->pos + count > file->end) count = file->end - file->pos; /* Can't go past the end! */ @@ -329,7 +369,19 @@ ssize_t pack_read(Packfile* file, void* buf, size_t count) { return bytes; } -/* Seek in the packfile. */ +/** + * @fn off_t pack_seek(Packfile* file, off_t offset, int whence) + * + * @brief Seeks within a file inside a packfile. + * + * Behaves like lseek/fseek. + * + * @todo It's broken, needs fixing. + * @param file File to seek. + * @param offset Position to seek to. + * @param whence Either SEEK_SET, SEEK_CUR or SEEK_END. + * @return The position moved to. + */ off_t pack_seek(Packfile* file, off_t offset, int whence) { DEBUG("Attempting to seek offset: %d, whence: %d", offset, whence); off_t ret; @@ -374,12 +426,26 @@ off_t pack_seek(Packfile* file, off_t offset, int whence) { return ret - file->start; } -/* Return current pointer position. */ +/** + * @fn long pack_tell(Packfile* file) + * + * @brief Get the current position in the file. + * @param file Packfile to get the position from. + * @return The current position in the file. + */ long pack_tell(Packfile* file) { return file->pos - file->start; } -/* Loads an entire file into memory and returns a pointer to it. */ +/** + * @fn void* pack_readfile(const char* packfile, const char* filename, uint32_t* filesize) + * + * @brief Read an entire file into memory. + * @param packfile Name of the packfile to read from. + * @param filename Name of the packed file to read. + * @param filesize Is set to the size of the file. + * @return A pointer to the sata in the file or NULL if an error accured. + */ void* pack_readfile(const char* packfile, const char* filename, uint32_t* filesize) { Packfile* file = (Packfile*)malloc(sizeof(Packfile)); void* buf; @@ -446,9 +512,16 @@ void* pack_readfile(const char* packfile, const char* filename, uint32_t* filesi return buf; } -/* Load the filenames int the packfile to filenames. */ -/* filenames should be freed after use */ -/* On error if filenames is (char**)-1. */ +/** + * @fn char** pack_listfiles(const char* packfile, uint32_t* nfiles) + * + * @brief Get what files are in the packfile. + * + * Each name must be freed individually afterwords and the array of names too. + * @param packfile Packfile to query it's internal files. + * @param nfiles Stores the amount of files in packfile. + * @return An array of filenames in packfile. + */ #ifdef _POSIX_SOURCE #define READ(b,n) if(read(fd, (b), (n))!=(n)) { \ ERR("Too few bytes read"); \ @@ -510,7 +583,13 @@ char** pack_listfiles(const char* packfile, uint32_t* nfiles) { } #undef READ -/* Close the packfile. */ +/** + * @fn int pack_close(Packfile* file) + * + * @brief Closes a packfile. + * @param file Packfile to close. + * @return 0 on success. + */ int pack_close(Packfile* file) { int i; #ifdef _POSIX_SOURCE diff --git a/src/pack.h b/src/pack.h index badb15b..bede538 100644 --- a/src/pack.h +++ b/src/pack.h @@ -5,14 +5,21 @@ #endif #include <stdint.h> + +/** + * @struct Packfile + * + * @brief Abstracts around packfile + */ typedef struct Packfile_ { #ifdef _POSIX_SOURCE - int fd; /* File descriptor. */ + int fd; /**< File descriptor. */ #else - FILE* fp; + FILE* fp; /**< For non-posix. */ #endif - uint32_t pos; /* position. */ - uint32_t start, end; /* file limits. */ + uint32_t pos; /**< position. */ + uint32_t start; /**< File start */ + uint32_t end; /**< File end. */ } Packfile; /* Packfile manipulation. Automatically allocated and freed (with open and close). */