From d123c4994660b575733f1edc583fb9f2ebe73437 Mon Sep 17 00:00:00 2001 From: apio Date: Mon, 21 Nov 2022 20:20:37 +0100 Subject: [PATCH] Do not automatically read an entry's contents, leave it up to the user This API change modifies minitar_read_entry to skip over the file's contents and instead store the current read position in the entry. struct minitar_entry no longer has a ptr field, but has a position field (of type fpos_t) for internal use. minitar_free_entry no longer frees entry->ptr. A new function has been added, minitar_read_contents(). It reads a certain number of bytes from an entry (which is capped to the entry's size) into a user-provided buffer. This function can be called at any time provided it is called with a valid archive stream and entry. This is achieved by calling fgetpos() to store the start of the entry's contents in the entry's position field while reading it. Then minitar_read_contents() will store the current position, rewind to the entry's position, read the chosen number of bytes from the archive, and then rewind back to the current position. Since this is a breaking change, it needs a major version bump. Since there was no version, I bumped it to 1.0.0 :) --- CMakeLists.txt | 2 +- README.md | 23 +++++++++++++++++------ minitar.h | 5 +++-- src/tar.c | 28 ++++++++++++++++++++++++---- src/util.c | 45 +++++++++++++++------------------------------ 5 files changed, 60 insertions(+), 43 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 454d1f6..cb6cbd1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.8..3.22) -project(minitar C) +project(minitar LANGUAGES C VERSION 1.0.0) set(SOURCES src/tar.c diff --git a/README.md b/README.md index 82314bc..ab1e6ce 100644 --- a/README.md +++ b/README.md @@ -48,16 +48,16 @@ A `struct minitar` is opaque, and should only be passed to other minitar functio Reads the next entry from a `struct minitar` which should be the return value of a previous call to `minitar_open()`. The return value is a heap-allocated `struct minitar_entry`, which should be freed with `minitar_free_entry()` when no longer needed. -This structure consists of the file metadata (in the `metadata` field), and a heap-allocated pointer to the file's contents (the `ptr` field), of size metadata.size + a NULL character, for convenience. This means you can use normal C string functions if you're expecting an ASCII file. Other kinds of files may have NULL characters before the end of the file, so you should assume the length of `ptr` is `metadata.size` and not `strlen(ptr)`. +This structure consists of the file metadata (in the `metadata` field), and other internally-used values. -This pointer will be freed when calling `minitar_free_entry()`, so if you're intending to use the file's contents later, copy them somewhere else. +To read the contents of an entry, you should allocate a buffer large enough to hold `metadata.size` bytes and pass it to `minitar_read_contents()`. This function returns NULL on end-of-file (when all entries have been read). ### minitar_free_entry `void minitar_free_entry(struct minitar_entry* entry)` -Frees the heap-allocated `struct minitar_entry` and the file contents stored inside it. The pointer passed to `minitar_free_entry()` should be the return value of a previous call to `minitar_read_entry()`, `minitar_find_by_name()` or `minitar_find_any_of()`. +Frees the heap-allocated `struct minitar_entry`. The pointer passed to `minitar_free_entry()` should be the return value of a previous call to `minitar_read_entry()`, `minitar_find_by_name()` or `minitar_find_any_of()`. ### minitar_rewind `void minitar_rewind(struct minitar* mp)` @@ -80,6 +80,19 @@ In order to perform other minitar operations on the archive, `minitar_rewind()` Does the same thing as `minitar_find_by_name()`, but matches the file type instead of the name. As with `minitar_find_by_name()`, this function starts searching from the current archive position and calling it in a loop until it returns NULL will return all matching entries. +### minitar_read_contents +`size_t minitar_read_contents(struct minitar* mp, struct minitar_entry* entry, char* buf, size_t max)` + +Reads up to `max` bytes of an entry's contents from the archive stream `mp` and stores them into `buf`. + +This function can be called as many times as desired, and at any given point in time, provided both `mp` and `entry` are valid. (`mp` should be the return value of a previous call to `minitar_open()`, and `entry` the return value of a previous call to `minitar_read_entry()`, `minitar_find_by_name()` or `minitar_find_any_of()`). + +This function returns the number of bytes read, or 0 on error. 0 might also be a successful return value (if `max` is 0 or the entry's size is 0, for example), which means `errno` should be checked to see if 0 means error or simply 0 bytes read. + +`minitar_read_contents()` only reads up to `metadata.size`, regardless of the value in `max`. + +The contents are not null-terminated. If you want null-termination (keep in mind the contents might not be ASCII and might contain null bytes before the end), just do `buf[nread] = 0;`. In that case, the value of `max` should be one less than the size of the buffer, to make sure the zero byte is not written past the end of `buf` if `max` bytes are read. + ### minitar_close `int minitar_close(struct minitar* mp)` @@ -134,9 +147,7 @@ An entry in a tar archive. Fields: `metadata`: The entry's metadata. (`struct minitar_entry_metadata`) -`ptr`: A pointer to the entry's contents, heap-allocated. (`char*`) - -More details about this structure are available in the documentation for `minitar_read_entry()`. +`position`: Reserved for internal use. (`fpos_t`) ## Error handling diff --git a/minitar.h b/minitar.h index 6454e0d..381b277 100644 --- a/minitar.h +++ b/minitar.h @@ -1,9 +1,9 @@ #ifndef MINITAR_H #define MINITAR_H +#include #include #ifdef _IN_MINITAR -#include struct minitar { FILE* stream; @@ -36,7 +36,7 @@ struct minitar_entry_metadata struct minitar_entry { struct minitar_entry_metadata metadata; - char* ptr; + fpos_t position; }; #ifdef __cplusplus @@ -51,6 +51,7 @@ extern "C" struct minitar_entry* minitar_find_by_name(struct minitar* mp, const char* name); struct minitar_entry* minitar_find_any_of(struct minitar* mp, enum minitar_file_type type); int minitar_close(struct minitar* mp); + size_t minitar_read_contents(struct minitar* mp, struct minitar_entry* entry, char* buf, size_t max); #ifdef __cplusplus } diff --git a/src/tar.c b/src/tar.c index 62a5896..ef2fc74 100644 --- a/src/tar.c +++ b/src/tar.c @@ -10,6 +10,7 @@ int minitar_validate_header(const struct tar_header*); void minitar_parse_tar_header(const struct tar_header*, struct minitar_entry_metadata*); struct minitar_entry* minitar_dup_entry(const struct minitar_entry*); char* minitar_read_file_contents(struct minitar_entry_metadata*, struct minitar*); +size_t minitar_get_size_in_blocks(size_t); struct minitar* minitar_open(const char* pathname) { @@ -47,11 +48,19 @@ static struct minitar_entry* minitar_attempt_read_entry(struct minitar* mp, int* *valid = 0; return NULL; } + *valid = 0; + if (fgetpos(mp->stream, &entry.position)) return NULL; *valid = 1; minitar_parse_tar_header(&hdr, &entry.metadata); - char* buf = minitar_read_file_contents(&entry.metadata, mp); - if (!buf) return NULL; - entry.ptr = buf; + if (entry.metadata.size) + { + size_t size_in_blocks = minitar_get_size_in_blocks(entry.metadata.size); + if (fseek(mp->stream, size_in_blocks, + SEEK_CUR)) // move over to the next block, skipping over the file contents + { + return NULL; + } + } return minitar_dup_entry(&entry); } @@ -72,7 +81,6 @@ void minitar_rewind(struct minitar* mp) void minitar_free_entry(struct minitar_entry* entry) { - free(entry->ptr); free(entry); } @@ -102,4 +110,16 @@ struct minitar_entry* minitar_find_any_of(struct minitar* mp, enum minitar_file_ } } while (entry); return NULL; +} + +size_t minitar_read_contents(struct minitar* mp, struct minitar_entry* entry, char* buf, size_t max) +{ + if (!max) return 0; + fpos_t current_position; + if (fgetpos(mp->stream, ¤t_position)) return 0; + if (fsetpos(mp->stream, &entry->position)) return 0; + size_t nread = fread(buf, 1, max > entry->metadata.size ? entry->metadata.size : max, mp->stream); + if (ferror(mp->stream)) return 0; + if (fsetpos(mp->stream, ¤t_position)) return 0; + return nread; } \ No newline at end of file diff --git a/src/util.c b/src/util.c index 8b512fa..da50aa2 100644 --- a/src/util.c +++ b/src/util.c @@ -39,6 +39,21 @@ void minitar_append_char(char* str, char c) str[len + 1] = 0; } +size_t minitar_is_block_aligned(size_t size) +{ + return (size % 512 == 0); +} + +size_t minitar_align_down_to_block(size_t size) +{ + return size - (size % 512); +} + +size_t minitar_get_size_in_blocks(size_t size) +{ + return minitar_is_block_aligned(size) ? size : minitar_align_down_to_block(size) + 512; +} + void minitar_parse_tar_header(const struct tar_header* hdr, struct minitar_entry_metadata* metadata) { if (!strlen(hdr->prefix)) @@ -110,34 +125,4 @@ struct minitar_entry* minitar_dup_entry(const struct minitar_entry* original) if (!new) return NULL; memcpy(new, original, sizeof *new); return new; -} - -char* minitar_read_file_contents(struct minitar_entry_metadata* metadata, struct minitar* mp) -{ - char* buf = malloc(metadata->size + 1); - if (!buf) return NULL; - - size_t nread = fread(buf, 1, metadata->size, mp->stream); - if (!nread) - { - if (feof(mp->stream)) - { - free(buf); - return NULL; - } - if (ferror(mp->stream)) - { - free(buf); - minitar_panic("Error while reading file data from tar archive"); - } - } - else - { - long rem = 512 - (nread % 512); - fseek(mp->stream, rem, SEEK_CUR); // move the file offset over to the start of the next block - } - - buf[nread] = 0; - - return buf; } \ No newline at end of file